Uh oh!
There was an error while loading. Please reload this page.
feat(runtime): add durable safe-boundary resume phases 0-2 - #1223
Conversation
# Conflicts: # packages/runtime/src/index.ts
Review conclusionThis is a novel and technically strong approach to runtime resume. The PR does not try to revive an old JavaScript stack, provider stream, Promise, or operating-system process. Instead, it reconstructs durable execution facts, proves that a continuation boundary is safe, and then starts a new Run, Invocation, and Turn. The most important design choice is the distinction between replaying tool history and re-executing tool side effects:
This gives Maka a useful resume primitive without claiming exactly-once execution for arbitrary Bash commands, filesystem mutations, or external APIs. Problem being solvedThe existing RuntimeEvent ledger could answer what had been recorded, but it could not reliably answer whether a tool might already have crossed the side-effect boundary. Two crash windows are particularly dangerous:
In either case, treating a missing result as proof that the tool did not execute can duplicate writes, deletes, deployments, payments, or remote requests. The previous startup repair path could converge a dangling Run to a failed terminal state, but it could not safely continue execution. This PR solves that by adding a durable tool-dispatch boundary, deterministic recovery projection, and safe-boundary continuation. Module viewflowchart LR
subgraph Entry["Product entry points"]
Desktop["Desktop Safe resume and startup recovery"]
CLI["CLI and TUI /resume"]
end
subgraph Control["Recovery control plane"]
SessionManager["SessionManager<br/>candidate discovery and lifecycle"]
Inspector["ContinuationSafetyInspector<br/>cwd, workspace, tools, background work"]
Planner["RuntimeContinuationPlanner<br/>continue or park"]
Resolver["RecoveryResolver<br/>single decision authority"]
end
subgraph Execution["Execution plane"]
Kernel["RuntimeKernel<br/>revalidation and claim"]
AgentRun["AgentRun<br/>fresh execution identity"]
Runner["RuntimeRunner<br/>continuation-start fact"]
Backend["AiSdkFlow and AiSdkBackend<br/>provider replay"]
ToolRuntime["ToolRuntime<br/>preflight, T1, implementation, T2"]
end
subgraph Persistence["Persistence"]
Bootstrap["openRuntimeEventPersistence"]
SQLite[("runtime.sqlite<br/>canonical RuntimeEvent store")]
Projection["tool_journal_events and tool_operations<br/>rebuildable projections"]
JSONL["Legacy RuntimeEvent JSONL<br/>import and explicit export"]
end
Desktop --> SessionManager
CLI --> SessionManager
SessionManager --> Inspector
SessionManager --> Planner
Inspector --> Planner
SQLite --> Planner
Planner --> Resolver
Resolver --> Planner
Planner -->|"approved continuation"| Kernel
Planner -->|"park with stable reason codes"| Desktop
Kernel --> AgentRun
AgentRun --> Runner
Runner --> Backend
Backend --> ToolRuntime
Runner -->|"continuation-start"| SQLite
ToolRuntime -->|"T1 and T2"| SQLite
SQLite -.->|"synchronous projection"| Projection
Bootstrap --> SQLite
Bootstrap -.->|"unmigrated workspace and flag disabled"| JSONL
JSONL -->|"sticky, idempotent import"| SQLite
The architectural boundary is clear:
How the tool boundary closes the crash windowssequenceDiagram
autonumber
participant Provider as Model Provider
participant Backend as AiSdkBackend
participant Runtime as ToolRuntime
participant Store as SqliteRuntimeStore
participant Tool as Tool Implementation
Provider->>Backend: function_call
Backend->>Runtime: execute tool
Runtime->>Runtime: validate args, availability, loop, permissions, and runtime guards
Runtime->>Store: T1 commitToolPrepared
Note over Store: Insert or verify function_call<br/>append toolDispatch RuntimeEvent<br/>update journal and operation projection
alt T1 fails
Store--xRuntime: rollback
Note right of Runtime: Tool implementation is never called
else T1 commits
Store-->>Runtime: durable dispatch boundary
Runtime->>Tool: execute implementation
Tool-->>Runtime: result or error
Runtime->>Store: T2 commitToolOutcome
Note over Store: Append function_response<br/>append outcome journal<br/>CAS operation state
alt T2 fails
Store--xRuntime: rollback
Note right of Runtime: Result is not returned to the next model step
else T2 commits
Store-->>Runtime: durable outcome
Runtime-->>Backend: tool_result
Backend-->>Provider: next provider step
end
end
This establishes two important invariants:
The external side effect still occurs between two short database transactions, so SQLite cannot make an arbitrary external operation atomic. Instead, a crash between T1 and T2 becomes an explicit How safe continuation workssequenceDiagram
autonumber
participant Entry as User or Startup Recovery
participant Manager as SessionManager
participant Inspector as Safety Inspector
participant Planner as Continuation Planner
participant Resolver as RecoveryResolver
participant Store as Durable Stores
participant Kernel as RuntimeKernel
participant Provider as Model Provider
Entry->>Manager: resumeLatest
Manager->>Store: find latest failed or cancelled session-inline Run
Manager->>Inspector: inspect cwd, workspace identity, tool catalog, and background work
Inspector-->>Manager: authoritative safety observation
Manager->>Planner: plan source boundary
Planner->>Store: read Run header, RuntimeEvents, and continuation ancestors
Planner->>Resolver: resolve tool recovery facts
Resolver-->>Planner: completed, indeterminate, not dispatched, or corruption
alt Any safety condition fails
Planner-->>Manager: park with stable reason codes
Manager-->>Entry: explain why resume is unavailable
Note over Entry,Provider: Provider is not called
else Boundary is safe
Planner-->>Manager: continuation plan with fresh identities and safety snapshot
Manager->>Kernel: execute continuation
Kernel->>Store: re-read source terminal, high-water, identity, and replay
Kernel->>Inspector: revalidate external safety facts
Kernel->>Store: create target Run with continuationSource claim
Kernel->>Store: commit continuation-start RuntimeEvent
Kernel->>Provider: replay committed history without a duplicate user message
Provider-->>Kernel: continue from the validated boundary
end
Planning and execution are intentionally separate. A valid plan is not treated as an execution lease. Immediately before execution, the Runtime re-reads durable state and rechecks workspace identity, active operations, tool availability, source high-water, and replay equality. The continuation also creates new execution identity: The source ledger is not mutated by the continuation. Recovery decisions
This is effectively tool-log replay: the provider receives the completed tool interaction as historical context, while the Runtime avoids replaying the old implementation or side effect. What this PR introduces
Current boundariesThe conservative scope is appropriate, but it is important to preserve these limitations:
Future value of checkpoints and Git snapshotsThe next major step that could make this resume system broadly practical is coupling the RuntimeEvent high-water with a workspace checkpoint, especially a Git-backed snapshot. That would let recovery validate or restore both sides of the continuation boundary:
A durable boundary containing: would allow Maka to resume after a crash without assuming that the current filesystem still matches the interrupted Run. It would also make planning and execution revalidation stronger because the continuation could prove that conversational state and workspace state refer to the same execution boundary. Overall assessmentThis is an excellent foundation and a genuinely interesting resume design. The durable tool-call protocol makes safe history replay possible without conflating replay with side-effect re-execution. The fail-closed behavior is correct, the new execution identity keeps lineage understandable, and the single canonical recovery authority avoids parallel state machines. With checkpoint and Git snapshot integration, this design could evolve from safe conversational continuation into a practical end-to-end runtime resume system. |
zhiiw
commented
Jul 19, 2026
Conflict-resolution verification updateThe branch was reconciled with current Additional compatibility fixes made during the merge:
Verification after reconciliation:
Windows-only file |
zhiiw
commented
Jul 19, 2026
CI follow-up is complete on head \ |
Uh oh!
There was an error while loading. Please reload this page.
…nip zero-hint, resume hook, QR fixture (#1241) * feat(core): add settings-bots-onboarding visual-smoke scenario + botOnboardingProvider * feat(desktop): hold-in-waiting bot onboarding adapter + fixture state for QR capture * feat(desktop): auto-open bot scan-login modal under settings-bots-onboarding fixture * chore(scripts): register settings-bots-onboarding in capture + audit scenario lists * fix(desktop): wait for QR paint before auto-capturing bot-onboarding fixture * docs(notes): frontend architecture map — measured baseline + 8 staged rounds (2026-07-19) Re-ran the census (wc over non-test TS/TSX for desktop main/preload/renderer + packages/ui; CSS totals; top-10 hotspot table incl. visual-smoke-fixture.ts marked OUT-OF-SCOPE other-sessions' territory). Staged R1 knip de-rot, R2 app-shell resume-cluster extraction, R3 visual-smoke split (BLOCKED on concurrent fixture branch), R4-R6 main.ts extractions (require maintainer-approved contract re-pins — registerIpc / startup / tool-assembly / modelSupportsVision direct-pinned), R7 provider-connection-detail decomposition (needs its own blade plan), R8 CSS raw-hex residue (verified clean on this tip — #1085 already converted it). * chore(knip): de-rot config — clear all 13 stale hints (R1) knip reported 13 configuration hints (7 desktop + 6 ui), all redundant/stale config, zero code impact: - Drop 'overlayscrollbars' from desktop ignoreDependencies — now redundant (knip no longer flags it; the package is owned by packages/ui and only referenced there). The overlay-scrollbars contract forbids declaring it as a *desktop dependency*, not as an ignore — removing a redundant ignore is compatible and coverage is unchanged. - Delete the dead 'src/renderer/**/*.test.ts' entry glob (no matches — renderer has zero test files; all 338 desktop tests live under src/main/__tests__/*.test.ts). - Drop 11 redundant explicit entries knip already auto-detects: desktop preload.ts / renderer/main.tsx / playwright.config.ts / .storybook/main.ts / dev.mjs (vite / playwright / storybook / npm-scripts plugins), and all 6 ui entries (index.ts, icons.tsx, artifact-preview-registry.ts, assistant-stream.ts, maka-uri.ts, smooth-stream.ts) resolved from packages/ui package.json#exports. Non-redundant entries kept verbatim (main.ts, overlay/*, main test glob, e2e specs, storybook preview, stories, browser-observe-act-smoke.mjs, both ui test globs). No broad ignores added — coverage is not weakened. knip --workspace apps/desktop and packages/ui now both exit 0 AND report zero config hints (was: exit 0 with 13 hints). * refactor(renderer): extract app-shell resume cluster into use-shell-resume (R2) The #1223 safe-boundary resume cluster moves out of app-shell.tsx into a new use-shell-resume.ts hook, following the use-shell-connections / use-shell-chat-model house style (options object; state + handler returned; stable identities preserved). Pure move, zero behavior change: the two useState declarations (resumePendingSessionId, resumeParkDescriptionBySession) and the resumeInterruptedSession handler move verbatim; activeId/toastApi/shellCopy/uiLocale are injected as options. app-shell keeps the banner JSX wiring (safeResumeAction=) and the sendWithAttachments guard. resumeParkToastCopy is no longer imported into app-shell (it now lives in the hook). app-shell.tsx 1686 -> 1654 (-32 lines). Contract re-pin (never deletes coverage): runtime-resume-routing-contract.test.ts read the handler-shape assertions (resumeInterruptedSession / resumeLatest(sessionId) / resumeParkToastCopy / no rejectionReasons.join) from app-shell.tsx single-file; they now read use-shell-resume.ts where that logic lives, while the app-shell-specific assertions (sendWithAttachments '/resume' guard, safeResumeAction= wiring) still read app-shell.tsx. use-shell-resume.ts added to renderer-shell-source-helpers sourcePaths (Round B/E precedent) so combined-source contracts see it. Gates: desktop 2740/2740, ui 196/196, typecheck 0, check-dead-css clean, knip desktop+ui exit 0, AUDIT_PORT_BASE=23900 alignment auditor exit 0 (all 10 fixtures clean, real renderer). CDP turn-narrative branch-vs-baseline (real Electron, light+dark 1280) byte-identical (sha256 match) — proven render no-op.
Summary
Implements the Runtime Resume foundation from Phase 0 through Phase 2, with RuntimeEvent as the single canonical recovery fact source.
The Desktop manual recovery entry is attached to the interrupted-turn banner as Safe resume. CLI/TUI retain
/resume. Park reasons are translated for users while stable reason codes remain available to diagnostics.Related to #186.
Safety and rollout
Both capabilities remain disabled by default:
MAKA_RUNTIME_SQLITE_CANONICAL=1runtime.sqlite; disabling the flag does not return that workspace to JSONL.MAKA_RUNTIME_SAFE_BOUNDARY_RESUME=1Ambiguous tool outcomes are parked, never blindly retried. Phase 3 reconciliation is intentionally outside this PR.
Dogfooding and regression fixes
Real restart/resume testing found and fixed:
The final recovery gates also reject duplicate dispatch/response facts and unknown runtime protocol markers as corruption.
Known limitations
definitely_not_dispatchedis classified but its Phase 3 automated recovery policy is not implemented.Verification
npm run typecheck(all workspaces)git diff --check