Distillation

Current State

• Repository/task: /home/byk/Code/opencode, baseline commit dc661f30cb feat(core): recover interrupted sessions, on the existing dirty worktree. No commit or service operation has been performed.
• Latest active task, requested Sep 15, 2026 at 20:25: Fix replay loss of ordinary prompt execution intent. Previously, session_input.wake_pending was armed only through EventV2 local commit hooks, which do not replay. The implementation now persists initial intent in PromptAdmitted and persists exact-retry upgrades through a new durable PromptExecutionRequested event.
• Implementation status at 20:56: Code and focused regression coverage appear complete:
  • Initial default-resume admission replays with wake_pending=true.
  • Initial resume:false admission replays with wake_pending=false.
  • An exact retry upgrade emits one idempotent durable execution-request event and replays with wake_pending=true.
  • A conflicting retry does not mutate state or emit execution intent before or after replay.
  • Prompted still clears wake_pending.
• Current validation status for the 20:25 task:
  • Core-focused tests: 205 passed, 0 failed, 579 expect() calls across 8 files in 19.15s at 20:55.
  • Schema manifest tests: 2 passed, 0 failed, 23 expect() calls across 1 file in 264ms at 20:55.
  • Core tsgo --noEmit: passed at 20:55.
  • Schema tsgo --noEmit: passed at 20:43.
  • Migration consistency: passed at 20:54; no incremental changes, full schema regenerated in /tmp/opencode-core-migration-check-5xD4oL/full/20260915205338_schema/migration.sql.
  • A post-task git diff --check result has not been recorded.
  • The full Core suite was last run before the replay-intent change, at 18:59: 1139 passed, 0 failed, 3148 expect() calls across 145 files in 62.34s.
• Current working tree at 20:56:
  • Tracked diff: 31 files changed, 3,193 insertions, 608 deletions.
  • Modified:
    • .lore.md
    • AGENTS.md
    • packages/core/schema.json
    • packages/core/src/database/migration.gen.ts
    • packages/core/src/database/migration/20260914170650_session-recovery.ts
    • packages/core/src/database/schema.gen.ts
    • packages/core/src/session.ts
    • packages/core/src/session/compaction.ts
    • packages/core/src/session/context-epoch.ts
    • packages/core/src/session/execution/local.ts
    • packages/core/src/session/input.ts
    • packages/core/src/session/message-updater.ts
    • packages/core/src/session/projector.ts
    • packages/core/src/session/recovery.ts
    • packages/core/src/session/run-coordinator.ts
    • packages/core/src/session/runner/index.ts
    • packages/core/src/session/runner/llm.ts
    • packages/core/src/session/runner/publish-llm-event.ts
    • packages/core/src/session/sql.ts
    • packages/core/test/database-migration.test.ts
    • packages/core/test/session-execution-local.test.ts
    • packages/core/test/session-projector.test.ts
    • packages/core/test/session-prompt.test.ts
    • packages/core/test/session-runner-recorded.test.ts
    • packages/core/test/session-runner-tool-events.test.ts
    • packages/core/test/session-runner.test.ts
    • packages/schema/src/session-event.ts
    • packages/schema/test/event-manifest.test.ts
    • packages/sdk/js/src/v2/gen/types.gen.ts
  • Deleted:
    • packages/core/src/database/migration/20260914214636_session-execution.ts
    • packages/core/src/database/migration/20260914222526_session-execution-phase.ts
  • Untracked implementation files:
    • packages/core/src/session/execution/claim.ts
    • packages/core/src/session/recovery-id.ts
  • Unrelated untracked files that must remain untouched:
    • perf.data
    • perf.data.old
• Unrelated files that must remain untouched: .lore.md, AGENTS.md, perf.data, and perf.data.old. They pre-existed the active work and must not be reverted or edited.
• Outstanding reporting/check items: Run or confirm git diff --check; if strict final validation is desired, rerun the full Core suite after the replay-intent changes. A substantive final report for the 20:25 task has not yet been recorded.
• Potential residual audit item: At 18:19 the user stated that local Session ownership must be replaced by durable multi-node ownership when clustered and described this as unchecked in packages/core/src/session/runner/llm.ts. No distinct later validation specifically closing that wording was recorded, although claim fencing and clustered execution ownership are implemented throughout the current worktree.

Key Decisions

• Replayable prompt execution intent
  • Initial execution intent is encoded directly in SessionEvent.PromptAdmitted as required requestExecution: boolean.
  • A later exact-retry upgrade from resume:false to execution intent uses a separate durable SessionEvent.PromptExecutionRequested.
  • The upgrade event has deterministic ID:
    • EventV2.ID.make(\evt_prompt_execution_${input.id}`)`
  • Rationale:
    • Initial admission and initial wake intent remain in one durable event/transaction, avoiding a crash gap.
    • Retry upgrades need an independently replayable transition because the original durable admission cannot be rewritten.
    • Deterministic event identity plus projection no-ops make duplicate concurrent exact upgrades idempotent.
  • Rejected approach: deriving wake intent from “unpromoted input,” because that would incorrectly wake original resume:false admissions.
  • Rejected approach: relying on EventV2 local commit hooks, because they are atomic for live publication but are neither serialized nor replayed.
• Prompt retry ordering
  • Stored-input equivalence is checked before requesting execution.
  • Conflicting reuse raises SessionInput.LifecycleConflict/Session.PromptConflictError without setting wake_pending, publishing PromptExecutionRequested, or advisory-waking execution.
  • Exact retries may upgrade false intent to true; false retries never clear existing true intent.
• Projection ownership
  • SessionInput.projectAdmitted() initializes wake_pending from durable requestExecution.
  • SessionInput.projectExecutionRequested() sets pending intent for the exact unpromoted row.
  • SessionInput.projectPrompted() records promoted_seq, clears wake_pending, and settles matching recovery outbox state.
  • session.next.prompt.admitted remains a message-projection no-op in message-updater.ts; the user message is materialized only by Prompted.
• Recovery continuation protocol
  • Added durable execution phase "continue" to distinguish known-settled work requiring another Step from interrupted/unknown provider work.
  • Successful tool-bearing Step.Ended and successful Compaction.Ended atomically persist "continue" with their terminal event.
  • Recovery of "continue" creates only the canonical queued continuation and does not mark an assistant errored or invent a synthetic assistant message.
  • "safe" remains discardable; "unknown" represents potentially interrupted provider/tool work.
• Declined local tools
  • User-declined tool settlement is collapsed into the durable Step.Interrupted transaction so tool error state, assistant interruption, and exact claim deletion are atomic.
  • Publishing Tool.Failed first was rejected because it created a crash window where execution could remain "unknown" and later synthesize a recovery continuation.
• Recovery outbox validation
  • Recovery rows are fully correlated against deterministic continuation identity, Session ownership, projection/input state, canonical queued "continue" payload, phase, assistant ownership, and pending state.
  • Invalid rows are quarantined with recovery_error rather than repeatedly occupying bounded scans.
  • Recovery processing is serialized with concurrency: 1.
• Older-assistant invariant
  • Recovery never resumes an older assistant projection. getCurrentAssistant() selects the newest assistant by descending message sequence and only returns it when incomplete.
  • An expired execution associated with an assistant superseded by a newer assistant is removed without creating recovery or continuation rows.
• Migration strategy
  • Recovery ownership remains unpublished 0-to-1 work.
  • Keep one squashed migration at packages/core/src/database/migration/20260914170650_session-recovery.ts.
  • Compatibility with discarded intermediate migrations/events is not required.
  • The temporary 20260915193000_session-recovery-fencing.ts migration and earlier intermediate execution migrations were removed.
• Public schema generation
  • Adding PromptExecutionRequested changes the public event manifest, so schema inventory tests and generated SDK V2 types were updated.
  • packages/sdk/js generation was run rather than manually editing generated sources.
• Repository workflow
  • Package tests must run from the relevant package directory, never repository root. Root package.json intentionally fails with "do not run tests from root".
  • Use bun typecheck/the package’s tsgo --noEmit; never invoke tsc directly.
  • Use current Effect v4/effect-smol APIs and nearby repository patterns.
  • Use apply_patch for edits.
  • No commits, builds, service starts/restarts, or live-service operations.
  • Preserve .lore.md, AGENTS.md, and perf artifacts.
• Effect/style conventions
  • Prefer Effect.gen(function* () {}), Effect.fn("Name"), or Effect.fnUntraced(...).
  • Use Effect Schema, branded IDs, Schema.TaggedErrorClass, explicit layers, testEffect(...), and it.live(...) where appropriate.
  • Avoid any, non-null assertions, unchecked casts, stale Effect APIs, star imports, and import aliases.

Technical Changes

• Replayable prompt intent, Sep 15, 2026 20:25–20:55
  • Modified packages/schema/src/session-event.ts:
    • SessionEvent.PromptAdmitted now requires requestExecution: Schema.Boolean.
    • Added durable event:
      • Name: SessionEvent.PromptExecutionRequested
      • Type: "session.next.prompt.execution_requested"
      • Fields: ...Base, messageID: SessionMessage.ID
    • Added the new event to DurableDefinitions and Definitions.
  • Modified packages/core/src/session/input.ts:
    • SessionInput.admit() now publishes requestExecution in PromptAdmitted.
    • Equivalent duplicate admissions call durable requestExecution() only after equivalence succeeds.
    • requestExecution():
      • Reads the exact input.
      • Rejects missing/cross-Session/conflicting rows with LifecycleConflict.
      • No-ops when already promoted or already pending.
      • Publishes deterministic PromptExecutionRequested.
      • Tolerates a publish defect only if rereading confirms wake_pending=true.
    • projectAdmitted() now accepts requestExecution: boolean and initializes wake_pending from it.
    • Added projectExecutionRequested(), which updates only the exact same-Session unpromoted input.
    • projectPrompted() continues to set promoted_seq, clear wake_pending, and call settleRecoveryWake().
    • Exported decode = (value: unknown) => Schema.decodeUnknownOption(Prompt)(value).
  • Modified packages/core/src/session/projector.ts:
    • PromptAdmitted projection passes event.data.requestExecution.
    • Added projector for PromptExecutionRequested.
    • Synthetic recovery continuation admission explicitly uses requestExecution: false; recovery outbox controls its wake.
  • Modified packages/core/src/session/message-updater.ts:
    • New execution-request event does not create a user-visible message.
    • PromptAdmitted remains a no-op for message projection.
  • Modified packages/core/test/session-prompt.test.ts with real EventV2 replay tests:
    1. Default-resume admission survives projection rebuild with pending wake and is redriven.
    2. resume:false survives rebuild with no pending wake.
    3. Two concurrent exact upgrades persist exactly one PromptExecutionRequested; repeated replay remains pending and recovery redrives.
    4. Conflicting retry remains non-pending before and after replay and causes no wake.
  • Specific assertions:
    • "Recover a lost advisory wake" remains { wake_pending: true, promoted_seq: null } after replay.
    • Admit-only exact retry upgrade produces advisory wakeCalls=[sessionID, sessionID] for two callers but exactly one durable upgrade event.
    • "never arms durable wake for a conflicting execution retry" starts with "Original prompt", retries conflicting text with resume:true, receives PromptConflictError, and remains wake_pending:false.
• Public event manifest and generated SDK
  • Modified packages/schema/test/event-manifest.test.ts:
    • ServerDefinitions.length: 55 → 61
    • Definitions.length: 85 → 91
    • Latest.size: 85 → 91
    • Durable.size: 32 → 38
    • Legacy SessionV1.Event.PartDelta, Diff, and Error expected slice moved from 40..43 to 46..49.
    • Added identity assertion for durable key "session.next.prompt.execution_requested.1".
  • Final inventory observed:
    • 35 Session events
    • 10 V1 events
    • 61 Server events
    • 91 definitions/latest definitions
    • 38 durable definitions
  • Ran SDK generation from packages/sdk/js with @hey-api/openapi-ts v0.90.10.
    • Warning: [@hey-api/sdk] instance is deprecated; recommended operations: { strategy: "single", containerName: "OpencodeClient", methods: "instance" }.
    • Final tracked generated change is packages/sdk/js/src/v2/gen/types.gen.ts.
    • Generated types include EventSessionNextPromptExecutionRequested, SyncEventSessionNextPromptExecutionRequested, SessionNextPromptExecutionRequested, and requestExecution: boolean.
• Durable continuation and recovery redesign completed by 19:00
  • packages/core/src/session/sql.ts:
    • SessionExecutionTable.phase: "ready" | "safe" | "unknown" | "continue".
    • SessionRecoveryTable.phase: "ready" | "unknown" | "continue".
    • Recovery primary key is execution_id.
    • Recovery assistant_message_id is nullable.
    • Recovery includes wake_pending, recovery_error, and deterministic continuation identity.
  • packages/core/src/session/runner/llm.ts:
    • Stream start transitions execution to "unknown".
    • Settled continuation transitions to "continue".
    • Terminal no-continuation state is "safe".
    • Final Step commit stores needsContinuation ? "continue" : "safe".
    • Recovery runs only the supplied recovery input and does not process unrelated queued input.
  • packages/core/src/session/execution/local.ts:
    • New executions start "ready".
    • Lease refresh occurs every leaseDuration / 3.
    • Success clears the exact claim.
    • Interrupt exits retain cleanup for the interrupt path.
    • Non-interrupt failure does not clear persisted "unknown" or "continue" claims, allowing startup recovery.
    • Recovery selection chooses the oldest pending, error-free recovery row by time_created, then execution_id.
  • packages/core/src/session/message-updater.ts:
    • Recovered phase "continue" performs no assistant mutation.
    • "unknown" uses "Provider Step outcome unknown after server restart".
    • Other recoverable interruption uses "Session execution interrupted by server restart".
    • Pending/running interrupted tools become errors with "Tool execution outcome unknown after server restart".
  • packages/core/src/session/projector.ts:
    • Step.Recovered requires durable sequence.
    • Validates supplied assistant is the latest assistant in the same Session.
    • Admits canonical Prompt.make({ text: "continue" }) with delivery "queue".
    • Inserts replayable recovery outbox state.
  • packages/core/src/session/recovery.ts:
    • Bounded scan size remains BATCH_SIZE = 100.
    • Expired claims and recovery rows are validated and quarantined.
    • Live leases are never recovered.
    • Superseded assistants are not recovered.
    • More than 100 poison rows cannot indefinitely block a valid row.
    • Cross-Session continuation poison is rejected.
• Atomic declined-tool fix, 18:54
  • Root cause: Tool.Failed was persisted before Step.Interrupted, leaving a crash window where recovery could classify the execution as "unknown".
  • Modified:
    • packages/core/src/session/message-updater.ts
    • packages/core/src/session/runner/llm.ts
  • Tool interruption, assistant interruption, and exact claim deletion now occur atomically with durable Step.Interrupted.
• Execution claim and Context Epoch fencing
  • New packages/core/src/session/execution/claim.ts.
  • Claims match Session ID, execution ID, owner ID, and a live expires_at.
  • SessionExecutionClaim.transaction() wraps lease renewal/verification and guarded work in an immediate SQLite transaction.
  • packages/core/src/session/context-epoch.ts performs claim renewal and epoch mutation in the same transaction.
  • Mutation regression proved split statements leaked renewal from 30_000 to 31_000; fixed code rolls back both.
• Migration consolidation
  • Final squashed migration: packages/core/src/database/migration/20260914170650_session-recovery.ts.
  • Deleted:
    • packages/core/src/database/migration/20260914214636_session-execution.ts
    • packages/core/src/database/migration/20260914222526_session-execution-phase.ts
    • Temporary packages/core/src/database/migration/20260915193000_session-recovery-fencing.ts
  • Final migration:
    • Adds session_input.wake_pending DEFAULT false NOT NULL.
    • Creates session_execution with exact claim/lease fields and phase check allowing 'ready', 'safe', 'unknown', 'continue'.
    • Creates session_recovery keyed by execution_id, nullable assistant, continuation, phase, wake state, quarantine error, and creation time.
    • Creates:
      • session_execution_session_idx
      • session_execution_owner_idx
      • session_input_wake_pending_promoted_time_created_id_idx
      • session_recovery_continuation_message_idx
• Important transient errors resolved
  • 18:04 Core typecheck:
    • src/session/recovery.ts:222:17 and :223:54: TS2339, property value does not exist on Option<"continue" | "ready" | "unknown">.
    • test/session-projector.test.ts:436:16: TS2322, {} not assignable to prompt/SQL value.
  • 18:19 runtime:
    • ReferenceError: SessionExecutionTable is not defined
    • At packages/core/src/session/runner/llm.ts:197.
    • Fixed by importing SessionExecutionTable.
  • 18:20 projection conflict:
    • SessionInput.LifecycleConflict for msg_recovery_continue_execution at packages/core/src/session/input.ts:183.
    • Fixed projection/recovery identity and settlement ordering.
  • 18:24 quarantine diagnostic:
    • Valid row incorrectly received recovery_error: "Invalid recovery projection identity".
    • Fixed deterministic recovery identity handling in projector.ts.
  • 18:32 test type errors:
    • packages/core/test/session-runner.test.ts:1517 and :1943
    • EffectDrizzleQueryError not assignable to never.
    • Fixed test effects.
  • 18:37 test-layer failure:
    • Service not found: @opencode/v2/SessionExecution
    • Service defined at packages/core/src/session/execution.ts:21:38; test reference at packages/core/test/session-prompt.test.ts:619:13.
    • Fixed test environment.
  • 20:33 replay-intent typecheck:
    • packages/core/src/session/projector.ts:374, TS2741
    • Missing required requestExecution: boolean passed to SessionInput.projectAdmitted().
    • Fixed.
  • 20:36 schema manifest failures:
    • Expected ServerDefinitions.length === 55, received 61.
    • Canonical definition inventory structurally mismatched.
    • Fixed packages/schema/test/event-manifest.test.ts.
    • Truncated original output saved at /home/byk/.local/share/opencode/tool-output/tool_0a6c90869001Q65cWkpGAPfoNs.
• Regression coverage now includes
  • Crash after tool-result Step.Ended, recovering exactly one continuation without changing settled assistant/tool state.
  • Crash after Compaction.Ended, recovering one continuation without changing summary or inventing assistant error.
  • Replay of Step.Recovered and continuation Prompted, rebuilding projection and settling outbox.
  • Declined local tool after provider step-finish, with exact claim settlement and no recovery continuation.
  • Conflicting prompt retry never arming durable wake.
  • More than 100 poison rows before valid work.
  • Cross-Session recovery poison.
  • Never recovering a live lease.
  • Never recovering an execution superseded by a newer assistant.
  • Never dispatching provider/local tool or failing interrupted tools after ownership changes.
• Validation history highlights
  • 18:59 full Core before replay-intent work: 1139 passed, 0 failed, 3148 expect(), 145 files.
  • 20:35 prompt tests: 27 passed, 0 failed, 70 expect().
  • 20:43 Core-focused: 74 passed, 0 failed, 196 expect(), 4 files.
  • 20:48 Schema manifest: 2 passed, 0 failed, 23 expect().
  • 20:50 broader focused: 185 passed, 0 failed, 528 expect(), 7 files.
  • 20:54 migration test: 20 passed, 0 failed, 51 expect().
  • 20:55 final Core-focused: 205 passed, 0 failed, 579 expect(), 8 files.
  • 20:55 final Schema manifest: 2 passed, 0 failed, 23 expect().
  • Core and Schema typechecks passed; migration consistency passed.
  • Latest explicit git diff --check success belongs to the 19:00 recovery audit, not the later replay-intent task.

Session Timeline

• Sep 15, 2026 14:42–16:12: Implemented the original interrupted-session ownership/recovery redesign: exact lease-fenced claims, serialized/coalesced Session drains, bounded recovery, deterministic IDs, durable recovery and ordinary wake state, migration consolidation, and runner fencing. Full Core reached 1129/1129; migration/Core/Schema checks passed.
• 16:15–16:29: Fixed Context Epoch check-then-write gap by moving renewal and epoch mutation into one immediate claim transaction. Mutation test demonstrated the old expiry leak from 30_000 to 31_000.
• 17:33–17:45: User requested five parent-audit fixes: durable settled continuation, replay-safe recovery settlement, atomic user-decline cancellation, retry ordering, and poison-row quarantine. Investigation confirmed all five gaps.
• 17:47–18:25: Added "continue" execution/recovery phase, nullable recovery assistant identity, recovery phase/error state, robust validation, projector settlement, and retry ordering. Resolved typecheck, undefined import, lifecycle conflict, and recovery identity failures. Broader focused suite reached 175/175.
• 18:26–18:41: Added direct crash-path tests for settled Step.Ended and Compaction.Ended, corrected tests to pass through real session.resume(...)/SessionExecutionLocal cleanup, strengthened conflicting retry recovery checks, and reached 179/179.
• 18:43–18:52: Strengthened poison-row, recovery redrive, and synthetic-continuation tests. Focused suite remained 179/179; migration and typechecks passed.
• 18:54–18:57: Full Core initially passed 1138/1138; audit then found the declined-tool crash window. Moved decline settlement into atomic Step.Interrupted, added coverage, and expanded focused suite to 180/180.
• 18:59–19:00: Final full Core passed 1139/1139, 3148 assertions, 145 files. Reported all seven recovery durability/liveness changes complete; Core/Schema typechecks, migration check, and git diff --check passed. No commit.
• 20:25: User reported a new confirmed replay defect: ordinary prompt wake intent lived only in non-replayed local commit hooks. Required durable initial intent, durable exact-retry upgrades, four real replay scenarios, and idempotence.
• 20:26–20:31: Inspected current EventV2, prompt admission/projectors, schema, manifest, and tests. Chose PromptAdmitted.requestExecution plus durable PromptExecutionRequested.
• 20:32–20:35: Implemented schema, input service, projector, and message-updater changes. Fixed TS2741 at projector.ts:374. Prompt suite passed 27/27.
• 20:36–20:43: Added replay regressions. Core-focused suite passed 74/74. Updated event-manifest counts after failures caused by the new event; Core and Schema typechecks passed.
• 20:45–20:48: Strengthened concurrent exact-upgrade and conflicting-retry tests. Manifest tests passed. Ran SDK V2 generation; generated types now expose the new event and requestExecution.
• 20:49–20:54: A temporary fencing migration was generated, then removed. Recovery schema was reconsolidated into 20260914170650_session-recovery.ts; intermediate migrations remained deleted. Migration test passed 20/20; consistency check passed.
• 20:55–20:56: Final recorded focused validation passed 205/205 Core tests and 2/2 Schema manifest tests; Core typecheck passed. Working tree ended at 31 tracked files changed, 3,193 insertions, and 608 deletions. No post-task git diff --check, full Core rerun, commit, or service operation was recorded.