Distillation

["lore_tm_v1_Cs9ncedZ9n2r-4BUqxo1LrsQZC8iAA0fIolEE0Fl24c","lore_tm_v1_o0tAJKcmaW8TLp5a0KvW6Imc1EBTL5HXFcp6XovyJOI","lore_tm_v1_ta2lsRhT9r8qrENGietqj98OLbNq9e_qkUcGa91jx_M","lore_tm_v1_uebb04k9Q9YlpZhfEix5vVedDJA_9oS7xIHXBfVvTuE","lore_tm_v1_1qULXU-rso6-Zp7Fs45FY6JMk7tLhjXUT7CTV62t_4U","lore_tm_v1_CeCdj3VIt7iZ45KkIFMTm6FEDqoyGtTH1HJjoxgR4II","lore_tm_v1_f3OZShxieARnKAnAugfJvOdRRzqO-LsfqT3A8RSiVdE","lore_tm_v1_5avyb6ometKFxPCnuPpD4JRjJcBDrbqjM-rBKzX1YbQ","lore_tm_v1_IP2Wmq-yG5MgwywNdq0sIBvzmS8hayw5zFaZVcc8PAw","lore_tm_v1_wAm8KyVVpcbddfHdw-CZd6oDPJHiVARWoOtkGnzC4lQ","lore_tm_v1_sj77Rrv_0CkNp3EUFZTpaNNEzN-Nso7MeL0QnejKuc4","lore_tm_v1_XjEWPd286LWZAaNsyBN_eDCsVFmwl5m7xLSatDijtkM","lore_tm_v1_KIBrc57ALvDTxil4QfIXEPVsmhUS3Dy2F_SQshlYwkk","lore_tm_v1_wda5j7tVU_xOpjkAou42WNlaSBYiyrS9satDSI9y1Yc","lore_tm_v1_o_gMok2slwQBNW4tDgAovL1jb5wshhHEIy4cZMSw8WA","lore_tm_v1_oWh_PL2ZCmIh08LuGuOlIWemx3ZVuRAQKuf96drjewU","lore_tm_v1_n3X7ijsaWjWsgMswlo7F0gFGMW7ZYmN502sf0e7llBo","lore_tm_v1_u2pe8GOR_sAL4IYbWbaH_FV3rptbR5PITLznO5TlKBE","lore_tm_v1_SxVR62ZvP90JMkUEfKLNCtfdql8BBlbta1bpbrzOjF8","lore_tm_v1_dvolw8Wr5Dv3S5xXf5YC8LNR28d_X7D280Pu-WvIvhM","lore_tm_v1_0gu8NdgRgeHN8OcngNTCRuBUVSUh_e9Tcj5tc7ovuCc","lore_tm_v1_AfiMoDFBp0R6dcYuLNXscRKh6kFzL-3SYNHtBzEp0og","lore_tm_v1_DTo40h0iT1BL75lYhm2TLamiU1QNHHH79WLlTjYHbU4","lore_tm_v1_Ima2iPc3FPFPhTf7QXh2O5JRQWQjuLrSvU0wo3W8pzk","lore_tm_v1_kjXC2yRqHs2Bh1pllKSI6aBVAjwRLASLv3tjI5gOmJo","lore_tm_v1_On_yjask0cKDjEW2U77CLTlSTObpoR_H-T-ExKYEhvg","lore_tm_v1_tmHbzvA9WnvgZOXCZmVwnsfsZYH6nhiivK0mUmB6guA","lore_tm_v1_zyLQ_R4pVjU_dEut_rCxijtjwng2geg7GutaXf7QSGw","lore_tm_v1_VVjmgGw-YWMYjq-xPTIkMyupbMmZomJn1ZKVzp2WNz8","lore_tm_v1_Vi5UeynTaUtmTG_30C6C3kkyBPioaEzaBYRfstzlX54","lore_tm_v1_YHgwnKAd8Pzqz8TBcmcwg5yj_YJ7X8upOmwno4BY2mY","lore_tm_v1_ubjgrZjm6pbMXK6ET8UodpFmhKIO3KTyuwYyr57K50Q","lore_tm_v1_4HUqznZdwoHjWMiC8wrem10lbBxzDlNkSBwNclcgIxc","lore_tm_v1_XOUINqPFlRN_ZeQAkvuWLpDE-08dyCVKNgCnw5o7ZGU","lore_tm_v1_PXOQKwVZ6GKZuC0l6Vl90t_praf9N0z3n75IFN1CJ74","lore_tm_v1_21GuQsoyR5pMVLTUK82rNOCXPpRCskxiiHDxMrKTlN4","lore_tm_v1_RFXvc8PrCtEJhKFm9_5Ju6U9wC3go2vQ7nmHefy5CQA","lore_tm_v1_gpgM8KfK-Z7uAksGj537iZuhjFMGye_P6hy7LUXXYFc","lore_tm_v1_eC8s4zEf7207CrEkmjoYvDEt6AU29FkgKFzE85uy7Ho","lore_tm_v1_WnT4WB4JnfSENY-whkzJakaRJ8IqcYWsHesAEz9VT10","lore_tm_v1_H9Kast3gndsMfXiVT6a9wPMT2QDHkH3TimjB8xtI0rs","lore_tm_v1_f6Olk85cN6TM6uJ8LtywCnG5qAiQ4jEqHFHSbonq6Ok","lore_tm_v1_G70y4jOfYi0i3gYPsg1vDigsx_8FmMZHbx2AuubC2Ro","lore_tm_v1_okhBFymhrEZfjjS3G0QLNwlT6AIJCvJnqRN57uKUVqE","lore_tm_v1_9hBjO-rJK9bB76JLZNA6YMC4a1kvw6kU5ETHaWl9c_k","lore_tm_v1_HMnfnyrNjPunsv-7FML_56qtIXCOjzf1WQGLYtpkh00","lore_tm_v1_Ef2V3VehOfWs2wOzCBh1GD_CUsJyDHPcBR1Q5Yk6XUE","lore_tm_v1_oZNgo-cLG2Yg592bDdLlpdBMQzg6jZw_tQl2ej0dWeM","lore_tm_v1_1qBxskgY15IL66kfFfM2_VQGJtjuksP9Z3CyaMJ8dKg","lore_tm_v1_Xa5FGWzZZ3VbZVfL6neaQ_rB6Tbw9h7mH1JhxWQaOFo","lore_tm_v1_Mil2pUeawed6NhH0I5HEqpx1NCZPissevU1uroZfIP0","lore_tm_v1_wZxXxkaeK-iuix7ebhOkKb-vvUxQzG2b7lLG-hKmZnA","lore_tm_v1_SHI6BfbvUEhBPhw7vSLIzWJ7VfW3pUN4qMUu__BoxRs","lore_tm_v1_unEQowyaKgpYs6QUN36GTiWiTiGAdm_ZsvtkIocdlLM","lore_tm_v1_fX5uFwAGR6tBmiCe72XcfOvsRwtc9NczbLAYjXC2rd8","lore_tm_v1_uVPCIwObkYsfkX-AS5CVT01ofqQvuP2lDobtRVqbAvI","lore_tm_v1_M9KmGPiKHyCmEcnwWw0wxObSyMB3KfWS0FfwFMjirXM","lore_tm_v1_OLKsD0qIC1YHYEDK-i430OY3Tw_UDgywTXOMVJIif5g","lore_tm_v1_yPjuDtHMquVFXzcnfiXcBkYVDseLw10Fu2DoojSlq_A","lore_tm_v1_U2hYz4pyYN1ZM4f0xUD8R-YrYBdQK0LC-bCUMpwnWIg","lore_tm_v1_AKXKf6OmR3tQ9DSkZfmlPT5or5iZIzfI0pCMvaM3Ru0","lore_tm_v1_aPKeRTH0CYlOQfLKbtsuc2pBNrtSkMpn8LC_-3EkIb8","lore_tm_v1_SAv_6JxZAJOxW_hrrtkWWBkElUk9njqAa8-gBIrR3LI","lore_tm_v1_iJMeoVJ0ceL6H1jG5_T_Amx-9vgw7BiUZ5AtAQkfPZU","lore_tm_v1_3mNa7H8mR0hLvEcXnGvyhR4AT2rqeSq7wXufvjlJb0M","lore_tm_v1_U63oPqjrPuXt6kcjIw2aFw5UHCt_DQNbRpw0X2Na1GE","lore_tm_v1_GeOWAVGvOfz-1OMQkQevi-u931XXCAVvlJYNRyaCbS0","lore_tm_v1_CAEHEqcdLKcffI8fV_EEBUteSjVaZCor5-iky5n_xPw","lore_tm_v1_biWsWiVHua2xyHT2RgQplh_4S4W-aJrDkzoagyh8Fk4","lore_tm_v1_b3OfqYF2Uui0CXuDPiSy7QV5Hn0ApwmSWrq2uoRNAEg","lore_tm_v1_Tlherg9VUtdTZAwHs3YsCKI4gAbYqKGFxDJtrm8XAiY","lore_tm_v1_rilt7c1pl1KewjCiJqAV1HW7Kfy0PM-8nt_Mh7EJAJI","lore_tm_v1_Md9MbTZqvtWdBqYjwD_RwyNjCzhae-1jVkAWNwabB3M","lore_tm_v1__ROiM3iuLKAyOmawCSx0CBtrFTVPkfCl9HAU7t8dQNI","lore_tm_v1_PLkUCfXpVsVI5R5CZFBoxilEx9zVLXpuhXBCx91hHf0","lore_tm_v1_niXtgqBYSTipqzvWgv1dCWnIxvf30vtZEaPJKSidcNM","lore_tm_v1_IvOHbEU6w0TOPWI1vx2WeDbpUudnT8sd5K_rj10dhv0","lore_tm_v1_Ve-vLWANMQ27sZyJz17eJ1wwVXVlqMOuK70qUJ1m9BQ","lore_tm_v1_YQ9MTOUyoM5ZrJ_f4S9OLWu6u8Vy0o8m7D1P3mqey30","lore_tm_v1_yoc438RSkrINg3WMdS-8Gs6h4fhJrViTI2uYtIsxSRY","lore_tm_v1_xSC5eCUeelQY3m75UgIMZOxChd8gXsQOTmIHjWxXAk4","lore_tm_v1_6n0ZYu6Xnq24ttunZ64ZCBcfPNtVeHQWOiUop-FeOuc","lore_tm_v1_m7mg85AjWdfvDg2Jyn6NW1cquUrjSehLtrUiQ1gnvnM","lore_tm_v1_GlFSzkDR5QDx0ZY2OP05sla56GplTFpXoX0KjP-HU2w","lore_tm_v1_VlEmBAofBDdX2eLRhZTUeiTdL5dUPyaSJCSKHfTTGSs","lore_tm_v1_AhGvKI-l-C_wDQcfxb7h_LfbP_mmE30_uSUyRJx2Nhc","lore_tm_v1_w7GFMGQuT9OJ1RqGPeyAZy2mIlCElDvl340ytNW-m1M","lore_tm_v1_nlmu0H_IAAXg949rwIWE3OU-9B_dIvvRFJ7cuv_JIzk","lore_tm_v1_J0igZykNFEpt9we3N56f3f0GNIQU7f6xgxfQ9V0-x4c","lore_tm_v1_Y-zLXBY9hnm5_IcMY3yE6nwXI4M1MQTtDaw_N4tLlzk","lore_tm_v1_VJQCR3g-QNRft4qotyiAsZ-5ZyRxV-QQZJBg3Wm9gM0","lore_tm_v1_4RF2lrnHOiqQGU13FS2oTOaQPsKGK0Knh3o4DQ9W1ck","lore_tm_v1_g9ArUZjsXQatTFPuAVDpN85apxtS0HaFFFi3AMxLFY4","lore_tm_v1_w6Gtw4EpPGJ6i6rQ6yxfqMFIUn_s7ToTZJujPzxA7Os","lore_tm_v1_h-ZHvps2PAfHdMGuFrmAElZOnZ8gLhbK_nF_eiXp_AA","lore_tm_v1_DMfeyK3abdhoTywUjJ6PeNWhwjc5sw-TDjKfB1rUcW4","lore_tm_v1_R7jXE0lkA9-OBpRqqhG3OYO5VzW-SUraNAsdEddxdXM"]

Current State

• Date / active task: Sep 14, 2026. Research is in progress in /home/byk/Code/opencode.
• Mode: 🔴 Research-only. No files may be edited and no implementation may be performed.
• Immediate user request: Produce a substantive, evidence-based design for the smallest correct V2 startup-recovery slice that:
  1. discovers Sessions left active/unfinished by a prior process,
  2. durably reconciles abandoned provider/tool work as interrupted or unknown and makes that visible to the model,
  3. admits exactly one fresh synthetic input equivalent to continue,
  4. wakes the Session through the normal V2 execution path,
  5. never calls or bridges through legacy SessionPrompt,
  6. prevents duplicate recovery by concurrent processes through an atomic durable claim, and
  7. preserves package/service layering.
• Expected deliverable: Exact proposed files, symbols, schema/table columns, event changes, startup wiring, regression tests, source references, and concrete layering constraints. The user explicitly requested either a substantive answer or an exact blocker statement because a prior response was empty.
• Current blocker / unresolved design issue: Existing durable state does not provide a complete, unambiguous startup-discovery or provider-dispatch recovery signal. A correct design still needs to specify:
  • which durable facts identify a Session as recovery-eligible,
  • how provider preparation versus dispatch ambiguity is represented,
  • how automatic abandonment differs from explicit retry,
  • how a claim is atomically acquired and fenced across processes,
  • how exactly-one synthetic continuation admission is made idempotent,
  • and where startup scanning belongs without violating Schema → Core/Protocol → Server layering.
• No code changes or test runs have occurred.

Current repository facts relevant to the design

• SessionExecution.active() is runtime-only, reports foreground drains owned by the current process, and is empty after restart.
• SessionTable, SessionMessageTable, SessionInputTable, and SessionContextEpochTable contain no durable active-run identity, provider-turn status, recovery claim, recovery epoch, recovery timestamp, or clustered execution owner.
• Durable projected transcript state can expose incomplete assistant/tool work, but by itself does not prove that a process died rather than another process still owning the work.
• Existing explicit session.resume(sessionID) behavior already repairs stale projected tool work:
  • local running tools become error results with exact message Tool execution interrupted,
  • provider-hosted tools become provider-executed error results,
  • pending tool input also becomes an error. This is explicit-resume behavior, not safe startup discovery/claiming.
• Current advisory wake(sessionID) must not infer that ambiguous provider work is safe to retry. The V2 spec explicitly defers post-crash continuation recovery until provider-dispatch ambiguity, continuation, queued-input handling, retry/abandon policy, visibility, startup discovery, and ownership fencing are jointly modeled.
• Recovery invariant from the user: “never resume an older assistant projection”; a newer turn supersedes stale incomplete rows.
• Side-effect invariants from the user:
  • abandoned side effects are never silently replayed,
  • recovery never loops or replays partial side effects,
  • provider-native assistant/reasoning/tool messages never survive across the compaction boundary.
• Cluster direction: replace process-local ownership with durable multi-node ownership when clustered; EventV2 replay-owner claims must stay separate from Session-execution ownership.

Important files currently under consideration

• Core Session:
  • packages/core/src/session/projector.ts
  • packages/core/src/session/compaction.ts
  • packages/core/src/session/todo.ts
  • packages/core/src/session/store.ts
  • packages/core/src/session/sql.ts
  • packages/core/src/session/schema.ts
  • packages/core/src/session/run-coordinator.ts
  • packages/core/src/session/revert.ts
  • packages/core/src/session/prompt.ts
  • packages/core/src/session/message.ts
  • packages/core/src/session/message-updater.ts
  • packages/core/src/session/input.ts
  • packages/core/src/session/info.ts
  • packages/core/src/session/history.ts
  • packages/core/src/session/execution.ts
  • packages/core/src/session/event.ts
  • packages/core/src/session/error.ts
  • packages/core/src/session/context-epoch.ts
  • packages/core/src/session/execution/local.ts
  • packages/core/src/session/runner/index.ts
  • packages/core/src/session/runner/llm.ts
  • packages/core/src/session/runner/model.ts
  • packages/core/src/session/runner/max-steps.ts
  • packages/core/src/session/runner/to-llm-message.ts
  • packages/core/src/session/runner/publish-llm-event.ts
• Schema / Protocol:
  • packages/schema/src/session.ts
  • packages/schema/src/session-id.ts
  • packages/schema/src/session-event.ts
  • packages/schema/src/session-message.ts
  • packages/schema/src/session-input.ts
  • packages/schema/src/session-delivery.ts
  • packages/schema/src/session-status-event.ts
  • packages/schema/src/event.ts
  • packages/schema/src/event-manifest.ts
  • packages/schema/src/durable-event-manifest.ts
  • packages/schema/src/prompt.ts
  • packages/protocol/src/groups/session.ts
  • packages/protocol/src/groups/message.ts
• Persistence / startup:
  • packages/core/src/event/sql.ts
  • packages/core/src/database/database.ts
  • packages/core/src/database/migration.ts
  • packages/core/src/database/migration.gen.ts
  • packages/core/src/database/schema.gen.ts
  • packages/core/script/migration.ts
  • packages/server/src/routes.ts
  • packages/cli/src/commands/handlers/serve.ts
  • packages/core/src/effect/app-node.ts
  • packages/core/src/effect/app-node-builder.ts
  • packages/core/src/location-services.ts
• Design references:
  • specs/v2/session.md
  • specs/v2/schema-changelog.md
  • specs/v2/todo.md
  • .opencode/references/effect-smol
• Existing Core Session tests inspected/identified:
  • packages/core/test/session-runner.test.ts
  • packages/core/test/session-projector.test.ts
  • packages/core/test/session-compaction.test.ts
  • packages/core/test/session-runner-tool-registry.test.ts
  • packages/core/test/session-runner-recorded.test.ts
  • packages/core/test/session-prompt.test.ts
  • packages/core/test/session-history.test.ts
  • packages/core/test/session-create.test.ts
  • packages/core/test/move-session.test.ts
  • packages/core/test/session-tool-progress.test.ts
  • packages/core/test/session-todo.test.ts
  • packages/core/test/session-runner-tool-events.test.ts
  • packages/core/test/session-runner-model.test.ts
  • packages/core/test/session-runner-message.test.ts
  • packages/core/test/session-run-coordinator.test.ts
  • packages/core/test/database-migration.test.ts
  • packages/core/test/event.test.ts

---

Key Decisions

User-mandated architecture and behavior

• No legacy bridge: Startup recovery must never invoke SessionPrompt, SessionPrompt.loop(...), or any legacy/in-memory tool loop.
• Durable admission remains separate from execution: SessionV2.prompt(...) admits one durable session_input row before advisory SessionExecution.wake(sessionID); resume: false means admit-only.
• Normal wake path: Recovery must perform durable reconciliation and admission first, then call the ordinary Session-ID-based SessionExecution.wake(sessionID).
• Atomic multi-process claim is mandatory: Discovery without a durable compare-and-set claim is insufficient because multiple server processes may start against the same SQLite database.
• No enclosing durable “drain” identity merely for grouping facts: A process-local drain has no durable transcript boundary. specs/v2/todo.md explicitly rejects inventing an enclosing execution identity solely to group continuation-recovery state.
• Never replay ambiguous side effects automatically: Provider dispatch may have happened even when no durable output exists. Unknown provider outcomes must be made visible and require an explicit retry/abandon policy rather than being silently retried.
• Tools are reconciled, not replayed: Previously running local tools are durably failed with Tool execution interrupted. Hosted/provider-executed tool settlement must preserve provider metadata and represent the unknown/interrupted result without calling the tool again.
• Projection ownership rule: Settlement/recovery events must target the owning assistantMessageID; stale incomplete assistants must not be revived when a newer turn exists.
• Exactly-one continuation input: Recovery must admit one fresh synthetic continue equivalent, with an idempotency mechanism tied to the durable recovery claim/epoch rather than merely checking prompt text.
• Cluster future: Durable Session execution ownership and stale-owner fencing belong to the Session recovery/execution slice; EventV2 replay-owner claims are a separate concern.
• Layering: Browser-safe wire/storage contracts belong in @opencode-ai/schema; persistence and recovery behavior belong in Core; process-start composition belongs in Server/CLI. Client runtime may depend on Schema and Protocol, never Core or Server. sdk-next composes Client/Core/Server.
• Location scope remains intact: SessionRunner, model resolution, tool registry, permissions, and filesystem stay Location-scoped. SessionExecution and SessionStore remain process-global and Session-ID-based; no layer may take a Session ID.
• Execution semantics remain unchanged: Exactly one explicit llm.stream(request) per provider turn, projected history reloaded before durable continuation, and safe-boundary delivery semantics preserved.
• Current wake semantics must not be repurposed as recovery inference: wake() is advisory; startup recovery needs an explicit durable policy and claim before waking.

Existing alternatives rejected or deferred

• Using SessionExecution.active() for discovery: Rejected because it is process-local and empty after restart.
• Scanning incomplete assistant/tool projections without ownership state: Insufficient because another process could still own the work and provider dispatch ambiguity cannot be determined safely.
• Treating every startup wake as safe retry: Explicitly rejected by specs/v2/session.md and specs/v2/todo.md.
• Automatically retrying unknown provider work: Rejected unless provider/tool idempotency and bounded retry policy make it safe.
• Reusing EventV2 replay owner_id: Rejected by repository policy requiring replay-owner claims to remain separate from Session-execution ownership.
• Adding a durable outer execution/run identity only to support recovery: Rejected because drains have no durable transcript boundary.
• Retrying partial local tool effects: Rejected; abandoned tools must settle as interrupted.
• Reviving the oldest incomplete assistant projection: Rejected; newest-turn ownership wins.
• Putting side-effecting recovery services in Schema: Rejected by package ownership rules.
• Running startup recovery through a Location-scoped layer: In tension with the process-global discovery/claim requirement; Location resolution should happen only when normal Session execution drains the claimed Session.

Tooling and style decisions that any future implementation must follow

• Verify Effect v4 / effect-smol usage against .opencode/references/effect-smol and nearby code, not memory.
• Reusable Effect workflows should use Effect.gen(function* () { ... }) and Effect.fn("Name") or Effect.fnUntraced(...) where appropriate.
• Effect service tests should use repository patterns such as testEffect(...) from packages/opencode/test/lib/effect.ts, it.live(...) for live platform behavior, and explicit layers/scoped fixtures.
• Never run package tests from repository root. Root package.json intentionally fails with "test": "echo 'do not run tests from root' && exit 1"; see root AGENTS.md:141-145.
• Typecheck with bun typecheck from the package directory, never direct tsc; see root AGENTS.md:147-149.
• No aliased imports and no star imports.
• Prefer narrow-scope dynamic imports for heavy startup-sensitive modules; destructure bindings near the top of the narrow scope and avoid inline await import(...).then(...) or (await import(...)).value().
• Drizzle fields use snake_case.
• Bind yielded Effect services to named variables before method calls.
• Avoid any, unchecked casts, non-null assertions, unnecessary try/catch, unnecessary destructuring/reassignment, and else when early return suffices.
• Repository versions observed: Bun 1.3.14, Effect 4.0.0-beta.83, Drizzle ORM 1.0.0-rc.2, TypeScript 5.8.2.
• packages/core/package.json: "test": "bun test --only-failures", "typecheck": "tsgo --noEmit".
• packages/server/package.json: "typecheck": "tsgo --noEmit".

---

Technical Changes

Changes made

• None. This session is research-only; no source, schema, migration, test, or generated file was modified.

Durable data model findings

• packages/schema/src/session.ts
  • Session.Info contains metadata, placement, accounting, timestamps, and revert state only.
  • No active-run identity, provider-turn state, tool-work status, claim, recovery epoch, or recovery timestamp.
  • Session.Info is currently annotated "SessionV2.Info" at line 44, which conflicts with the Schema rule that current permanent contracts remove V2.
  • Session.ListAnchor at lines 46-51 contains id, finite time, and direction "previous" | "next".
• packages/schema/src/session-message.ts
  • Current message ID prefix is msg_.
  • Eight message variants, in order: AgentSwitched, ModelSwitched, User, Synthetic, System, Shell, Assistant, Compaction.
  • Assistant content: AssistantText | AssistantReasoning | AssistantTool.
  • Tool states: ToolStatePending | ToolStateRunning | ToolStateCompleted | ToolStateError.
  • Assistant projections have no durable run/claim/recovery identity.
• packages/schema/src/session-input.ts
  • SessionInput.Admitted: admittedSeq, message id, sessionID, prompt, delivery, timeCreated, optional promotedSeq.
• packages/core/src/session/sql.ts
  • Current tables: SessionTable, SessionMessageTable, SessionInputTable, SessionContextEpochTable.
  • Retained V1 tables: MessageTable, PartTable, TodoTable.
  • SessionTable has no durable recovery/ownership columns.
  • SessionMessageTable: primary key id, session_id, type, per-session seq, timestamps, JSON data; unique (session_id, seq).
  • SessionInputTable: id, session_id, JSON prompt, delivery, admitted_seq, nullable promoted_seq, time_created; unique per-session admitted/promoted sequences.
  • SessionContextEpochTable: one row per Session with baseline, JSON snapshot, and baseline_seq.
• packages/core/src/event/sql.ts
  • event_sequence(aggregate_id PRIMARY KEY, seq NOT NULL, owner_id NULL).
  • event(id PRIMARY KEY, aggregate_id FK CASCADE, seq, type, data).
  • Unique event index (aggregate_id, seq).
  • Existing owner_id belongs to EventV2 replay ownership and must not be reused for Session execution recovery.

Event model findings

• packages/schema/src/session-event.ts:47 declares the V2 durable Session event version as 2.
• Event.versionedType(type, version) is at packages/schema/src/event.ts:94; durable-key construction is around line 102.
• Durable Session events include lifecycle facts for prompts, steps, text, tools, reasoning, compaction, and revert.
• Step.Started records assistantMessageID, agent, model, and optional snapshot.
• Step.Ended records finish, cost, token accounting, optional snapshot/files.
• Step.Failed records UnknownError.
• Step.Ended and Step.Failed use synchronized durable version 2, because settlement is bound to an explicit assistant message ID.
• Tool events:
  • Tool.Called: tool name, decoded input, provider execution metadata.
  • Tool.Progress: durable bounded running checkpoint with structured and content.
  • Tool.Success: structured/content output, optional paths/result, provider metadata.
  • Tool.Failed: UnknownError, optional result, provider metadata.
• Stream fragments are live-only:
  • Text.Delta
  • Reasoning.Delta
  • Tool.Input.Delta
  • Compaction.Delta Their replayable boundaries are the corresponding Ended events.
• SessionEvent.DurableDefinitions was reported as containing 29 events; the observed ordered list was:
  1. AgentSwitched
  2. ModelSwitched
  3. Moved
  4. Prompted
  5. PromptAdmitted
  6. ContextUpdated
  7. Synthetic
  8. Shell.Started
  9. Shell.Ended
  10. Step.Started
  11. Step.Ended
  12. Step.Failed
  13. Text.Started
  14. Text.Ended
  15. Tool.Input.Started
  16. Tool.Input.Ended
  17. Tool.Called
  18. Tool.Progress
  19. Tool.Success
  20. Tool.Failed
  21. Reasoning.Started
  22. Reasoning.Ended
  23. Retried
  24. Compaction.Started
  25. Compaction.Ended
  26. RevertEvent.Staged
  27. RevertEvent.Cleared
  28. RevertEvent.Committed The source observation’s count and displayed enumeration differ and should be rechecked before relying on a manifest delta.
• packages/schema/src/durable-event-manifest.ts combines durable V1 definitions and all current SessionEvent.DurableDefinitions.
• Manifest regression values in packages/schema/test/event-manifest.test.ts:
  • EventManifest.ServerDefinitions.length === 55
  • EventManifest.Definitions.length === 85
  • EventManifest.Latest.size === 85
  • EventManifest.Durable.size === 32
  • legacy key "session.next.step.ended.1" absent
  • "session.next.step.ended.2" maps to SessionEvent.Step.Ended.

Current input admission and normal execution path

• packages/core/src/session/input.ts operations:
  • find
  • admit
  • projectAdmitted
  • projectPrompted
  • hasPending
  • equivalent
  • promoteSteers
  • promoteNextQueued
• SessionInput.admit is idempotent by SessionMessage.ID. It publishes PromptAdmitted only if absent and derives admittedSeq from the durable event sequence.
• projectAdmitted rejects message/input lifecycle collisions and inserts with onConflictDoNothing().
• projectPrompted atomically changes promoted_seq only where null, validates projection identity, and can reconstruct a missing admitted row.
• Steers are promoted in ascending admitted order up to a cutoff; only the earliest queued input is promoted when the Session would otherwise idle.
• packages/core/src/session/execution.ts:
  • active
  • resume(sessionID)
  • wake(sessionID)
  • interrupt(sessionID)
• SessionExecution.Service is global and unbound; noopLayer supports admit-only callers.
• packages/core/src/session/execution/local.ts:
  • process-local coordinator,
  • loads Session from SessionStore,
  • resolves Location using LocationServiceMap.get(session.location) only when draining,
  • calls runner.run({ sessionID, force }),
  • dies with exact message Session not found: ${sessionID} when absent,
  • logs non-interrupt failures as Failed to drain Session.
• packages/core/src/session/run-coordinator.ts:
  • serializes execution per Session key,
  • allows different Sessions concurrently,
  • coalesces wakes using pendingWake,
  • joins same-Session explicit runs,
  • interrupts only the local owner,
  • uses Effect.uninterruptibleMask for run(key).

Projection and stale-work behavior

• Projector ownership helpers include:
  • activeShellIndex(callID)
  • updateOwnedAssistant(assistantMessageID, ...)
  • latestText(...)
  • latestTool(...)
• Events mutate the explicitly owning assistant; stale incomplete assistant rows are ignored when a newer turn owns the event.
• Shell updates are routed through updateShell.
• Explicit projector no-ops include:
  • "session.next.moved": () => Effect.void
  • "session.next.revert.staged": () => Effect.void
• Regression tests:
  • "updates only the newest incomplete assistant projection" verifies only msg_assistant_2 receives completion.
  • "does not revive a stale incomplete assistant projection" leaves msg_assistant_stale untouched and applies new text to the newer completed assistant.

Existing recovery-like runner behavior and tests

In packages/core/test/session-runner.test.ts:

• Lines 2233-2259: steering "Recover with this" admitted while "Start working" provider stream is gated; after streamFailure, a second request contains both user texts in order.
• Lines 2262-2319: prior-process local tool recovery:
  • stale call-interrupted, tool echo, input { text: "stale" }, provider { executed: false };
  • explicit session.resume(sessionID) sends roles ["user", "assistant", "tool"];
  • projected state becomes error with exact message Tool execution interrupted.
• Lines 2322-2380: prior-process hosted web_search recovery:
  • call-hosted-interrupted,
  • provider metadata includes OpenAI itemId,
  • resume sends ["user", "assistant"],
  • assistant contains provider-executed tool call followed by provider-executed error result.
• Lines 2382-2419: pending tool input call-pending-interrupted is recovered as an assistant tool error; request roles are ["user", "assistant", "tool"].
• Lines 2421-2439: waking an idle Session promotes one queued input "Wait in queue" after it was admitted with resume: false.
• Lines 2441-2465: prompt projection rollback with new Error("fail after prompt promotion"); a later wake still produces "Recover promoted input".
• Test "transitions streamed raw tool input to parsed called input" currently ends with hosted tool state { status: "error", input: { query: "hello" } }.
• Exact stream-order defects:
  • "Duplicate text start: text-1"
  • "Tool input delta before start: call-1"
• For every fragmentKinds entry there are three regressions:
  1. ephemeral deltas broadcast without projection rewrites,
  2. partial fragments durably close on provider failure,
  3. partial fragments durably close on interruption.

These tests show the runner can reconcile stale projections once explicitly invoked, but they do not provide startup scanning, ownership claiming, exactly-once continuation admission, or concurrent-process coverage.

History/model lowering facts

• SessionHistory.load() loads baseline sequence and latest compaction concurrently, then decodes ordered message rows.
• loadForRunner() / entriesForRunner() select projected history after the active compaction and baseline.
• Decode failures become MessageDecodeError with Session and message IDs.
• toLLMMessages:
  • omits agent/model switch records,
  • lowers synthetic records as user messages,
  • preserves reasoning/provider metadata only for the same historical/current model,
  • emits local tool results as separate tool messages,
  • keeps provider-executed results beside calls in assistant content.
• Local stale tools becoming durable error results therefore become model-visible in the next provider request.
• Pending tool input attempts JSON parsing and falls back to the raw string.
• Unresolved remote/managed URIs remain a TODO because ToolOutput.toResultValue rejects them.

Compaction facts relevant to recovery

• Constants in packages/core/src/session/compaction.ts:
  • DEFAULT_BUFFER = 20_000
  • DEFAULT_KEEP_TOKENS = 8_000
  • TOOL_OUTPUT_MAX_CHARS = 2_000
  • SUMMARY_OUTPUT_TOKENS = 4_096
• Compaction publishes Compaction.Started, streams a no-tool summary, and publishes Compaction.Ended only for successful nonempty output.
• Only completed compaction changes the model-visible boundary; interrupted attempts leave previous history active.
• Synthetic transcript serialization is [Synthetic context]: ${message.text}.
• Overflow compaction supports one rebuilt physical attempt only before durable assistant output/tool execution.
• TurnTransitionError includes:
  • { _tag: "ContinueAfterCompaction"; step: number }
  • { _tag: "ContinueAfterOverflowCompaction"; step: number }

Startup/layer wiring findings

• packages/server/src/routes.ts builds application services from:
  • Database.node
  • EventV2.node
  • HTTP client
  • ToolOutputStore.cleanupNode
  • SessionV2.node
  • PermissionSaved.node
  • PtyTicket.node
  • Credential.node
  • PtyEnvironment.node
  • LocationServiceMap.node
• It binds [SessionExecution.node, SessionExecutionLocal.node] through AppNodeBuilder.build.
• Concrete CLI process start is packages/cli/src/commands/handlers/serve.ts:
  • Runtime.handler(Commands.commands.serve, Effect.fn("cli.serve")(...))
  • listen() probes ports 4096 through 65_535 when no explicit port is supplied.
  • bind() serves createRoutes(password) and builds Credential.node plus PermissionSaved.node.
• AppNodeBuilder.build(root, replacements) auto-builds a LocationServiceMap when an unbound node is present and no replacement exists; replacements match by node name.
• makeGlobalNode and makeLocationNode are defined from LayerNode.tags({ location: ["global"], global: [] }).
• buildLocationServiceMap():
  • keys by Location.Ref,
  • adds Location.node and Location.boundNode(ref),
  • hoists global dependencies,
  • logs "booting location services",
  • uses idleTimeToLive: "60 minutes".
• 🔴 [location-node aggregation] The Location service graph contains 37 nodes:
  1. Location.node
  2. Policy.node
  3. Config.node
  4. AgentV2.node
  5. CommandV2.node
  6. Reference.node
  7. Integration.node
  8. Catalog.node
  9. AISDK.node
  10. PluginV2.node
  11. PluginInternal.node
  12. ProjectCopy.node
  13. ProjectCopy.refreshNode
  14. FileSystemSearch.node
  15. FileSystem.node
  16. Watcher.node
  17. Pty.node
  18. SkillV2.node
  19. SystemContextRegistry.node
  20. SystemContextBuiltIns.node
  21. LocationMutation.node
  22. FileMutation.node
  23. PermissionV2.node
  24. ToolOutputStore.node
  25. ToolRegistry.node
  26. ToolRegistry.toolsNode
  27. Image.node
  28. SkillGuidance.node
  29. ReferenceGuidance.node
  30. SessionTodo.node
  31. QuestionV2.node
  32. ReadToolFileSystem.node
  33. BuiltInTools.node
  34. SessionRunnerModel.node
  35. Snapshot.node
  36. SessionRunnerLLM.node
  37. one additional grouped entry was reported by the source count but not present in the preserved visible enumeration; recheck the file before citing the count as definitive.

Database/migration mechanics

• packages/core/src/database/database.ts configures SQLite with:
  • PRAGMA journal_mode = WAL
  • PRAGMA synchronous = NORMAL
  • PRAGMA busy_timeout = 5000
  • PRAGMA cache_size = -64000
  • PRAGMA foreign_keys = ON
  • PRAGMA wal_checkpoint(PASSIVE)
• DatabaseMigration.apply() is serialized only by an in-process Semaphore.makeUnsafe(1); cross-process migration claiming is a known deferred hardening issue.
• Existing databases with session use applyOnly; nonempty databases without session fail with Database is not empty and has no session table.
• Each migration and its journal insert execute atomically in a transaction.
• Migration generator: packages/core/script/migration.ts, 196 lines.
  • --check validates snapshot, schema.gen.ts, and migration.gen.ts.
  • Exact stale-artifact messages:
    • Core schema has ungenerated database migrations. Run \bun script/migration.ts` from packages/core.`
    • Current database schema is stale. Run \bun script/migration.ts` from packages/core.`
    • Database migration registry is stale. Run \bun script/migration.ts` from packages/core.`
• Relevant historical migrations:
  • 20260603141458_session_input_inbox
  • 20260604172448_event_sourced_session_input
  • 20260622170816_reset_v2_session_state
  • 20260622202450_simplify_session_input
• 🔴 [migration aggregation] packages/core/src/database/migration.gen.ts imports 38 migrations in order:
  1. 20260127222353_familiar_lady_ursula
  2. 20260211171708_add_project_commands
  3. 20260213144116_wakeful_the_professor
  4. 20260225215848_workspace
  5. 20260227213759_add_session_workspace_id
  6. 20260228203230_blue_harpoon
  7. 20260303231226_add_workspace_fields
  8. 20260309230000_move_org_to_state
  9. 20260312043431_session_message_cursor
  10. 20260323234822_events
  11. 20260410174513_workspace-name
  12. 20260413175956_chief_energizer
  13. 20260423070820_add_icon_url_override
  14. 20260427172553_slow_nightmare
  15. 20260428004200_add_session_path
  16. 20260501142318_next_venus
  17. 20260504145000_add_sync_owner
  18. 20260507164347_add_workspace_time
  19. 20260510033149_session_usage
  20. 20260511000411_data_migration_state
  21. 20260511173437_session-metadata
  22. 20260601010001_normalize_storage_paths
  23. 20260601202201_amazing_prowler
  24. 20260602002951_lowly_union_jack
  25. 20260602182828_add_project_directories
  26. 20260603001617_session_message_projection_indexes
  27. 20260603040000_session_message_projection_order
  28. 20260603141458_session_input_inbox
  29. 20260603160727_jittery_ezekiel_stane
  30. 20260604172448_event_sourced_session_input
  31. 20260605003541_add_session_context_snapshot
  32. 20260605042240_add_context_epoch_agent
  33. 20260611035744_credential
  34. 20260611192811_lush_chimera
  35. 20260612174303_project_dir_strategy
  36. 20260622142730_simplify_session_context_epoch
  37. 20260622170816_reset_v2_session_state
  38. 20260622202450_simplify_session_input

Schema package constraints

• @opencode-ai/schema owns browser-safe wire/storage contracts; runtime services and side effects remain in owning domain packages.
• Current contracts are unversioned; retained legacy contracts use explicit V1.
• One canonical exported value per contract; Core facades may only re-export the exact Schema identity.
• Public contracts are readonly.
• Optional fields use package optional(...) to omit undefined.
• Avoid Schema.Any; use Schema.Json or Schema.Unknown.
• Contract tests must cover omitted undefined properties, no accidental Schema.Any, stable/unique identifiers, facade identity, and exclusion of V1-only events from current manifests.

Other relevant deferred work

• specs/v2/todo.md says future recovery must jointly model:
  1. promoted input and projected history,
  2. queued-input promotion and steering assignment,
  3. provider preparation versus dispatch ambiguity,
  4. required post-tool continuation across process loss,
  5. explicit retry and abandon decisions,
  6. bounded automatic retries only where idempotent,
  7. retry budget, backoff, visible status, startup discovery, clustered ownership fencing.
• Remaining EventV2 work includes remote cursor APIs while keeping replay claims separate from Session ownership.
• Background bash/agent work must not return without durable status observation, completion delivery, and explicit cancellation/continuation semantics.
• SessionStatusEvent.Info currently has only:
  • { type: "idle" }
  • { type: "retry", attempt, message, action?, next }
  • { type: "busy" } It has no durable startup-recovery/unknown-outcome state.
• SessionStatusEvent.Status is event type "session.status"; deprecated Idle is "session.idle".

---

Session Timeline

Sep 14, 2026

• 08:53

  • User initiated research-only work in /home/byk/Code/opencode.
  • Requested the smallest correct V2 startup-recovery design.
  • Mandated no legacy SessionPrompt, atomic durable claiming, and preserved layering.

• 08:54-08:55

  • Repository and package AGENTS.md guidance collected.
  • Core Session, Schema, Protocol, Server, and test files identified.
  • Tooling restrictions established: package-local tests/typechecks, Effect v4 verification, no aliased/star imports.
  • Existing V2 admission, execution, Location scope, exact-one-stream, coordinator, and delivery policies documented.

• 08:56-08:58

  • Schema Session, Session message, Session input, and durable event contracts inspected.
  • Confirmed absence of durable recovery/ownership fields.
  • Core SQL tables and SessionStore inspected.
  • User established projection invariant: never resume an older assistant projection.
  • Projector ownership behavior confirmed.

• 08:58-09:00

  • Session input admission/promotion internals inspected.
  • SessionRunner and local SessionExecution path inspected.
  • User stated clustered systems must replace local ownership with durable multi-node ownership.
  • LLM history lowering and process-global/local service composition inspected.

• 09:01-09:04

  • Event tables, migration machinery, generated baseline schema, and all 38 migrations inspected.
  • Migration generation/check workflow documented.
  • Event and Prompt schema helpers inspected.

• 09:05-09:07

  • V2 Session HTTP API and durable manifest surfaces inspected.
  • Existing prior-process stale-tool recovery tests found.
  • SessionHistory and SessionRunCoordinator behavior documented.
  • Global-node and cleanup-layer patterns surveyed.

• 09:08-09:09

  • SDK embedded composition and V2 Session specs inspected.
  • User invariants captured: never silently replay abandoned side effects; never loop/replay partial side effects; compaction boundary removes provider-native history.
  • Spec explicitly confirmed post-crash continuation recovery remains deferred.
  • TODO enumerated required recovery concerns and separation from EventV2 replay claims.

• 09:14-09:16

  • Session status event schema inspected.
  • Step event publication/projection references identified.
  • SQLite initialization and Session row-to-schema mapping inspected.

• 09:25

  • User reported the prior response was empty.
  • Reiterated research-only/no-edits.
  • Required a substantive evidence-based answer or exact blocker.
  • Restated exact recovery policy and requested files, symbols, schema/events, startup wiring, tests, and layering constraints.

• 09:27-09:31

  • Confirmed durable Session event version 2.
  • Event manifest tests and manifest composition inspected.

• 09:39-09:48

  • Historical Session input/reset migrations inspected.
  • Migration tests partially inspected; some output was elided.
  • Concrete CLI startup path and app-node architecture inspected.

• 09:59-10:03

  • AppNodeBuilder and Location service map construction inspected.
  • Confirmed global versus Location-scoped dependency mechanics.

• 10:12-10:20

  • Compaction implementation and runner compaction regressions inspected.
  • Confirmed only completed compaction changes active model history.

• 10:28

  • End of the 3,466-line runner test file inspected.
  • Stream fragment failure/interruption regressions and exact ordering defects documented.

• 10:29-10:31

  • HTTP route test reference found.
  • specs/v2/schema-changelog.md source lines identified:
    • lines 80-109: durable cursor and versioning behavior,
    • lines 93-109 / line 97: step settlement version 2,
    • line 413: durable tool success/failure events,
    • line 631: stale local running tools must be durably failed with Tool execution interrupted.