Start here

What's new

What changed recently, and what changes when you upgrade. Published releases come first. After them are the changes already in the SDK repositories that ship with the next SDK and CLI releases. Read those before you upgrade, because several of them change defaults.

Published

2 November 2026

• Flutter adapter packages are on pub.dev. bug_capsule_firebase, bug_capsule_geolocator, bug_capsule_google_maps, bug_capsule_stripe and bug_capsule_shorebird are published as 0.1.0-dev.1. They need bug_capsule ^0.4.1-beta.10. See adapter packages and the Shorebird adapter.
• Dashboard: verdict v2 results on runs. Runs show Fixed (qualified) and Unsafe badges and say why such a run doesn't count as fixed. A v2 Fixed run shows the baseline behind it, for example "Baseline 3/3 reproduced on abc1234". A Fixed run judged with the old rules says so. See verdict v2.

1 November 2026

• Flutter 0.4.1-beta.10, the standalone CLI 0.4.1-beta.10 (npm installer @bugcapsule/cli 0.4.0-beta.5), Flutter bug_capsule_patch 0.1.0-dev.1 and iOS 0.4.1-beta.5: signed patch runtime and patch CLI commands (signed patch engine), guard decisions recorded into capsules (emergency recovery).

Coming in the next SDK and CLI releases

Stricter verdicts (verdict v2)

verify, regress run and gate report FIXED only when the capsule's own commit reproduced the failure every time (the baseline), enough attempts on your build ran cleanly, and each clean attempt shows the failing path ran. Two new verdicts appear: FIXED (QUALIFIED) (exit 4) and UNSAFE (exit 5). Add BugCapsule.expect(…) postconditions to flows whose capsules come from exceptions. The full rules are under verdict v2.

Privacy defaults

• No request or response bodies in production by default. Production mode keeps method, URL, status, headers and timing. Debug and QA modes still record (redacted) bodies. Set captureNetworkBodies: true to keep bodies in production. An explicit value always wins over the mode, and your project's capture settings can turn bodies off but never on. On Android and iOS the option becomes optional (Boolean? / Bool?), which breaks code that reads it as a plain boolean.
• Binary bodies are recorded as size and content type only, in every mode, unless you opt in: Flutter maxBinaryBytes on the Dio or http integration, Android BugCapsuleOkHttp(captureBinaryBodies = true), iOS captureBinaryBodies: true, web networkIntegration({ captureBinaryBodies: true }).
• A capsule without bodies still replays. Responses come back with their recorded status, headers and latency and an empty body, the attempt reports network.noBody, and eligibility lists network.bodies.
• Android SQLite spans replace SQL literals with ?.
• Redaction removes every BugCapsule credential format from free text, including SDK tokens, CLI tokens and keys, wherever they appear in logs, messages or bodies. The web SDK also redacts more key names (pwd, pass, csrf, refresh, access) and headers (X-Session, Authentication). Form-encoded bodies follow the URL parameter rules, which changes request keys for form posts with fields such as code or session.

Consent and local data

Flutter, Android and web add collectionEnabled in the config, a persisted setCollectionEnabled(…) consent switch and clearLocalData(). Saved captures expire after 7 days. Android keeps its files out of Auto Backup, and Flutter on iOS can exclude them from backups with bug_capsule_native. The iOS SDK follows in a later release. See consent and local data.

Project settings can only narrow capture

• Trace propagation targets from your project's settings can only remove destinations from the list in your app. They are matched as plain substrings, never as regular expressions. If you set trace targets only in the dashboard, list those destinations in tracePropagationTargets in the app.
• The capsule size limit from project settings is capped at 50 MiB. Android also caps a server Retry-After at 24 hours.
• Plain http:// is refused in SDK tokens and explicit backend settings, except to localhost, 127.0.0.0/8, [::1] and the Android emulator's 10.0.2.2. A project secret key (bcs_…) in an app is refused. A refused setup never crashes the app: it runs without capture or uploads, and the status API says why (iOS: invalid_backend). For a backend on your LAN, use https, adb reverse or a tunnel.

Storage restore follows the capture policy

Capsules record which storage keys their capture allowed (manifest.storagePolicy). Replay writes only those keys, further narrowed by the replayed build's own allowlist, and reports every other key as the material divergence restore.disallowed. Android also validates SharedPreferences and DataStore names and refuses paths outside the app's storage directories. Capsules recorded by older SDKs have no policy and replay without storage restoration.

Replay safety

• Web: replay network is deny by default. From the app's origin the page may only load static resources with GET/HEAD. Every other request, real WebSocket, beacon, EventSource, form post or worker request is blocked and reported as network.escaped. A dev server's live-reload socket is blocked too, so replay against a production-style build. --allow-live <url substring> lets matching requests through for debugging and makes the run UNSAFE. Release @bugcapsule/web-replay with the matching @bugcapsule/web.
• Flutter: replay fails closed. When replay can't start (fetch, schema or preflight failure), the app shows a short screen with the reason instead of running live. Replay runs only in debug builds, or in profile builds compiled with --dart-define=BUGCAPSULE_ALLOW_PROFILE_REPLAY=true.
• A result printed on stdout counts only when it carries the armed attempt's random id, so logged text can't complete an attempt.

Startup and memory

• Android init does no disk I/O on the calling thread. BugCapsule.isRecording turns true shortly after init. Events, logs and scope changes made in between are kept (up to 256 of each) and applied once ready. captureException and captureMessage return null during startup and send the event afterwards. Transactions started during startup aren't traced.
• The in-memory recorder has a byte budget: Android maxRetainedBytes and web maxRecorderBytes, both 8 MiB. Over it, the oldest HTTP bodies and interaction payloads are dropped first, then the oldest events, and capsules list capture.truncated.

CLI

• verify builds the capsule's commit first (--baseline-runs, default 3) and raises --runs to what the baseline requires. New flags: --accept-qualified, --verdict-v1, and gate --fail-on unverified.
• The CLI no longer writes, runs or opens anything a capsule or server chose. Capsule file names are validated. Pinned worktrees live under ~/.bugcapsule/pins (owner-only) and are reused only for the same commit. Downloads are capped at 256 MiB, with a 60-second stall limit. Saved credentials are written owner-only. Browser login opens only an https page on your BugCapsule site.
• Web sourcemaps inject / upload follow only .map files inside the input directory, and warn when the secret key is passed as --key. Use BUGCAPSULE_SECRET_KEY instead.

Upgrade checklist

1. Decide whether production needs bodies, and set captureNetworkBodies explicitly if it does. On Android and iOS, update code that reads it as a boolean.
2. Move trace propagation targets you set only in the dashboard into the app config.
3. Replace plain-http LAN backends with https, adb reverse or a tunnel.
4. Add BugCapsule.expect(…) postconditions for key flows, so fixes can reach FIXED instead of FIXED (QUALIFIED) or INCONCLUSIVE.
5. Update CI: treat exit codes 4 and 5, decide on --accept-qualified and --fail-on unverified, and make sure CI can check out the capsule's commit for the baseline.
6. Wire your consent screen to setCollectionEnabled and your "delete my data" action to clearLocalData().
7. Web: replay against a production-style build, and upgrade @bugcapsule/web and @bugcapsule/web-replay together.
8. Flutter: add the profile replay dart-define if you replay profile builds.