Distillation

Date: Sep 17, 2026

• 🟡 (08:36) packages/core/src/session/execution/local.ts implements process-local session execution using SessionRunCoordinator.make; it generates a per-process ownerID, tracks claims in activeClaims: Map<SessionSchema.ID, SessionExecutionClaim.Claim>, and derives leaseDuration from SESSION_EXECUTION_LEASE_MS.
• 🟡 (08:36) The drain path in packages/core/src/session/execution/local.ts claims a session inside an immediate database transaction by inserting a "ready" row into SessionExecutionTable with a new executionID, owner_id, latest assistant-message seq (or -1), time_created, and expires_at; .onConflictDoNothing() makes an unsuccessful concurrent claim return without running.
• 🟡 (08:36) After claiming a session, packages/core/src/session/execution/local.ts selects the oldest valid pending recovery by SessionRecoveryTable.time_created and execution_id, requiring wake_pending=true and recovery_error IS NULL, then passes its continuation_message_id to input.run(claim, force, recovery?.continuationMessageID).
• 🟡 (08:36) Active local executions race the runner against repeated SessionExecutionClaim.renew(db, claim) calls scheduled every leaseDuration / 3; non-interrupt-only failures are logged as "Failed to drain Session" with sessionID.
• 🟡 (08:36) Drain exit handling in packages/core/src/session/execution/local.ts removes matching entries from activeClaims; successful runs clear the claim, while failed/interrupted runs inspect the persisted phase and preserve claims in cancellation or unsafe interruption cases. Claims are otherwise cleared unless their phase is "unknown" or "continue".
• 🟡 (08:36) settleCancellation in packages/core/src/session/execution/local.ts renews the claim and handles phases explicitly: "cancelled" clears immediately; any phase other than "cancelling" dies with Interrupted Session settlement failed: ${claim.sessionID}; a null assistantMessageID also clears immediately.
• 🟡 (08:36) Cancellation settlement checks whether the claimed assistant message already has data.time.completed; if completed, it calls SessionExecutionClaim.settleCancellation(db, claim, { phase: "cancelled", assistant_message_id: null }) and clears the claim. Otherwise it publishes SessionEvent.Step.Interrupted with error { type: "unknown", message: "Provider Step outcome unknown after interruption" }, committing the same cancelled state before clearing.
• 🟡 (08:36) Local interruption in packages/core/src/session/execution/local.ts first updates the claim to { phase: "cancelling" }, then races coordinator interruption/settlement against lease renewal. A SessionExecutionClaim.Lost defect is tolerated only when no current SessionExecutionTable row remains for the session.
• 🟡 (08:36) The local SessionExecution.Service maps active to coordinator.active, resume to coordinator.run, and wake to coordinator.wake; its runner loads the session from SessionStore.Service, dies with Session not found: ${claim.sessionID} if absent, and runs runner.run({ ...claim, force, recoveryInputID }) under the location-specific service layer from LocationServiceMap.
• 🟡 (08:36) packages/core/src/session/execution/local.ts exports a global app node for SessionExecution.Service with dependencies Database.node, EventV2.node, SessionStore.node, and LocationServiceMap.node.
• 🟡 (08:36) packages/core/src/session/run-coordinator.ts defines SessionRunCoordinator as a per-key serializer: different keys can execute concurrently, while each key has one Entry containing done, optional owner, optional exit, pendingWake, and stopping.
• 🟡 (08:36) SessionRunCoordinator.run(key) starts a drain with force=true when idle, joins the existing execution when active, and—if the entry is stopping—waits for its done deferred before recursively running again.
• 🟡 (08:36) SessionRunCoordinator.wake(key) coalesces follow-up work by setting pendingWake=true on an existing entry; when idle it creates an entry and starts a drain with force=false.
• 🟡 (08:36) Successful coordinator settlement with pendingWake=true reuses the current entry and starts one yielded successor drain with force=false. Other settlements either remove the key or replace the entry with a successor before completing the original done deferred with the drain’s exact Exit.
• 🟡 (08:36) SessionRunCoordinator.interrupt(key, cleanup) marks the entry as stopping, clears the preexisting pendingWake, interrupts its owner fiber, runs cleanup, and then either removes the entry or starts a successor for any wake that arrived during stopping. The operation is uninterruptible and throws "Interrupted Session execution did not settle" if the interrupted owner did not record an exit; cleanup failures are re-emitted with their original cause.
• 🟡 (08:36) packages/core/src/session/runner/index.ts defines SessionRunner.Interface.run for one local continuation from recorded session history, accepting sessionID, force, executionID, ownerID, and optional recoveryInputID; explicit runs are documented to perform one provider attempt even when no durable work is eligible.
• 🟡 (08:36) SessionRunner.RunError is the union of LLMError, SessionRunnerModel.Error, MessageDecodeError, ContextSnapshotDecodeError, SystemContext.InitializationBlocked, and ToolOutputStore.Error; the service identifier is @opencode/v2/SessionRunner.