Persist workspace, conversation, and canvas state across reloads and failures

[robinbraemer]

Outcome

Preserve the canonical workspace, conversation, user draft, running-canvas revision, and last-known-good state across refresh, restart, crash, quota pressure, and interrupted writes. Recovery should feel like continuing work, not operating an internal state machine.

Dependencies

Builds on the Git-backed history contract in #25 and the persistent workspace host in #33.

Required behavior

• Keep source, dependencies, assets, agent tools, compiler state, canvas revision, and history anchored to one canonical workspace identity.
• Persist bounded schema-decoded conversation and task context needed for the agent to continue; credentials, private grants, model internals, raw provider payloads, and unbounded tool output stay excluded.
• Preserve unsent user drafts and restore them without sending twice.
• Reopen on the latest valid visible checkpoint and retain actionable diagnostics for an interrupted or failed edit.
• Detect schema, host, runtime, and workspace incompatibility before mutation and offer a safe migration, export, or restore path.
• Reject stale tool results and concurrent writes using workspace revision identity.
• Handle OPFS/IndexedDB quota exhaustion, partial writes, corruption, interrupted migration, and multiple tabs without replacing the last-known-good state.
• Compact bounded conversational context and disposable build caches without deleting source history.
• Keep internal agent-session lifecycle and recovery receipts out of the default UI.

Acceptance criteria

• Production Chromium refreshes and restarts during idle, prompt drafting, agent streaming, tool execution, incremental build, failing build, direct manipulation, Undo, and history restore.
• Every restart returns to the exact canonical source revision and matching running-canvas revision or explains one bounded recovery action.
• A preserved unsent draft is restored; a submitted prompt and its tool effects are never duplicated.
• Fault injection covers quota exhaustion, partial writes, corrupted entries, incompatible schema, stale revisions, interrupted migration, simultaneous tabs, worker termination, and storage eviction.
• The packaged macOS app recovers after runtime termination and relaunch without losing the latest valid work or exposing private state.
• Fifty edit/reload cycles stay within the memory and storage budgets from Make Flect feel instant with strict live-editing performance budgets #20.
• Recovery can inspect, export, retry, or restore without a model when the model is unavailable.
• The user-facing flow contains no App/Shaper/Guardian, candidate, accepted/rejected, safe-mode, branch, or reset-mode terminology.
• Recovery evidence is bounded and attributable and contains no credential-bearing transcript.

Non-goals

• Persisting every model token, screenshot, network body, or tool payload.
• Treating browser storage as a security boundary.
• Inventing history separate from the canonical Git workspace.
• Recreating disposable compiler caches when a clean incremental rebuild is safer.

[robinbraemer]

The browser role-continuity slice is now implemented and mandatory. Canonical design: docs/superpowers/specs/2026-08-01-flect-role-continuity-design.md. User lifecycle: docs/recovery.md. Dated evidence: docs/verification/2026-08-01-role-continuity-verification.md. The strict Effect schema is capped at 512 KiB; the repository uses Web Locks where available, generation checks, one-value atomic replacement, bounded validated export, isolated discard, and typed recovery for malformed, incompatible, oversized, stale, and rejected writes. Accepted Use, candidate Use, and Shape drafts use a private reactive channel and never enter workspace snapshots, AXI, control events, logs, diagnostics, or auth state. Completed App, Preview App, and Shaper conversations restore separately; Preview App continuity requires the exact candidate revision; active partial assistant output and tool activities are not durable. Production Chromium now proves completed role history restoration, three isolated drafts, candidate refresh and Reject cleanup, active Shaper interruption normalization, safe-mode non-hydration, valid export, retry, and isolated discard. Fresh check:all passed Effect/Rifty checks, Biome, TypeScript, 498 unit and contract tests with one intentional skip, 25 production Chromium workflows, 18 Rust tests, and a rebuilt signed-ad-hoc macOS app. This issue remains open for real simultaneous-tab fault injection, production browser quota and future interrupted-migration proof, and exact packaged sidecar-loss/relaunch evidence. Those residuals are recorded explicitly and are not claimed complete.

[robinbraemer]

Follow-up proof closed the browser concurrency and quota residuals. Two real same-origin production pages now load the same generation; after the first tab saves a newer draft, the stale second tab is rejected, cannot replace the durable value, and exposes stale-write in protected recovery. A separate production-page test injects QuotaExceededError only for flect.role-continuity.v1, proves the exact prior encoded record remains unchanged, and exposes storage-unavailable recovery. The complete production Chromium suite now passes 27 of 27 workflows. Packaged-host dogfood also isolated one newly launched exact bundle by full executable path, killed only its own flect-runtime child with SIGKILL, confirmed the owning app remained alive, then relaunched that exact bundle. A new private runtime appeared and the same validated Flect Studio candidate plus Keep/Reject decision remained visible with Pi ready. No pre-existing Flect process was targeted. Remaining issue scope is now narrower: future interrupted-migration proof when a compatible schema evolution exists, and extension of native evidence from candidate preservation to an explicitly accepted revision, completed role continuity, and a packaged private-state canary.

[robinbraemer]

2026-08-01 verification update:

• Fixed a real first-run recovery defect: a blank workspace could create its Git directory without accepted/LKG refs plus activation receipt, so reload before first edit entered safe mode. New repository load now commits and binds the built-in revision atomically before exposing the workspace; legacy migration remains separate.
• Browser evidence now uses fresh isolated Wasm-Git workspaces and real OPFS cleanup instead of localStorage-only setup.
• bun run check:all is green: 563 unit/integration tests (+1 intentional skip), 58 production-Chromium journeys, 18 Rust tests, and a fresh local macOS app bundle.

Still open: visible OPFS-degraded UX, clean packaged-host restart evidence, and remaining issue acceptance criteria.

[robinbraemer]

2026-08-01 degradation UX update:

Compiled archive persistence now projects durable, session, or unavailable separately from source history. If OPFS initialization falls back to memory, the collapsed Diagnostics summary visibly says “Session-only storage”; the expanded alert names what will be lost and directs export before leaving. Normal production Chromium reports both source and compiled interfaces durable.

This closes the previously invisible fallback defect, but OPFS-disabled end-to-end automation and broader quota/recovery acceptance criteria remain open.

[robinbraemer]

Pushed verification update — 2026-08-10

Browser recovery continues to cover workspace, Git, canvas, conversation, drafts, interruption, stale writers, quota failure, reload, and offline packages. The new real packaged-host gate additionally kills the exact private sidecar with SIGKILL, proves the main application and private draft survive, then terminates/relaunches the app and observes the exact restored draft, one new runtime, and one window.

Evidence: packaged macOS verification. Clean-machine accepted-revision and storage-pressure evidence remains external.