Distillation

Date: Sep 17, 2026

• 🔴 (09:05) User stated repository type-checking convention: always run bun typecheck from package directories such as packages/opencode; never run tsc directly.
• 🔴 (09:05) User stated runtime dependency direction: Schema → Core and Protocol, then Core and Protocol → Server. Client runtime code may depend on Schema and Protocol, but never Core or Server; sdk-next composes Client, Core, and Server.
• 🔴 (09:05) User stated import-style rule: never alias imports, including forms such as import { foo as bar } from "..." or resolve as pathResolve.
• 🔴 (09:05) User stated import-style rule: never use star imports, including import * as Foo from "..." and import type * as Foo from "..."; namespace-style use should import a module’s own named namespace export.
• 🟡 (09:05) Read-only verification showed /tmp/opencode/session-recovery-v21-review at detached HEAD ab9408c81cc9916177641ae8e9f08624fc27b5b9, matching the required base commit. SHA-256 values matched for /tmp/opencode/session-recovery-final-v21.patch (2ae4eea72024cafe8b69c0461063ee25cbf54608856cd258866b7f3b86620b36) and /home/byk/Code/opencode/packages/opencode/dist/server/opencode-server (aa98d64abb3bf6ac0ef88a940f9c41c6eb14ffeab3c3a7846921ba01ef46643d).
• 🟡 (09:05) Review workspace contained 29 tracked modified paths plus 5 untracked paths, totaling the expected 34 changed paths. Untracked files were packages/core/src/database/migration/20260914170650_session-recovery.ts, packages/core/src/session/execution/claim.ts, packages/core/src/session/recovery-id.ts, packages/core/src/session/recovery.ts, and packages/core/test/session-execution-local.test.ts.
• 🔴 (09:05) User stated tests cannot run from the repository root because of the do-not-run-tests-from-root guard; tests must run from package directories such as packages/opencode.
• 🔴 (09:05) User stated generated-code workflow: after changing public Protocol or Server HttpApi, run bun run generate from packages/client; do not edit src/generated or src/generated-effect directly. Legacy JavaScript SDK regeneration uses ./packages/sdk/js/script/build.ts.
• 🔴 (09:05) User stated V2 Session Core semantics: SessionV2.prompt(...) durably admits one session_input row before advisory SessionExecution.wake(sessionID), unless resume: false requests admit-only behavior; the serialized runner promotes admitted inputs at safe boundaries.
• 🔴 (09:05) User stated SessionExecution must remain process-global and Session-ID based; its local implementation owns the process-local Session coordinator, discovers placement only when a drain starts, and V2 interruption targets the active process-local ownership chain while idle or missing interruption is a no-op.
• 🔴 (09:05) User stated SessionRunCoordinator joins explicit same-Session resumes, coalesces prompt wakeups, permits different Sessions to run concurrently, and keeps local drains process-local until clustering exists.
• 🔴 (09:05) User stated one explicit llm.stream(request) call must be preserved per provider turn, projected history must be reloaded before durable continuation, and orchestration must not bridge through legacy SessionPrompt.loop(...) or an in-memory tool loop.
• 🔴 (09:05) User stated delivery semantics: steering prompts promote at the next safe provider-turn boundary while continuation is required; explicit queue inputs remain pending until otherwise idle, then exactly one queued input is promoted before continuation is reevaluated; promoting new user input resets the selected agent’s provider-turn allowance, with a steer batch resetting it once.
• 🔴 (09:05) User stated Effect module-shape convention: do not use export namespace Foo; use flat top-level exports and a self-reexport such as export * as Foo from "./foo" or export * as Foo from "." for an index.ts. Multi-sibling directories must not add barrel index.ts files.
• 🔴 (09:05) User stated Effect concurrency convention: use Effect.cached for concurrent in-flight deduplication rather than manually storing Fiber | undefined or Promise | undefined; Effect.fork and Effect.forkDaemon do not exist in Effect v4 beta, so use Effect.forkIn(scope).
• 🔴 (09:05) User stated HTTP route conventions: use HttpApiBuilder.group(...) for declared endpoints, handleRaw(...) for declared raw/WebSocket routes, and raw HttpRouter.use(...) only outside the declared API surface. Stable services/layers must be provided at assembly boundaries rather than via Effect.provide(...) inside request handlers.
• 🔴 (09:05) User stated schema dependency boundary: @opencode-ai/schema <- @opencode-ai/protocol <- @opencode-ai/server; Schema owns browser-safe serializable contracts, while runtime behavior, services, side effects, and host-local implementation remain in their owning domain package.
• 🔴 (09:05) User stated current contracts must be unversioned, retained legacy contracts explicitly use V1, and V2 must not remain the permanent naming for replacement architecture. Clearly V1-only events such as message.updated and message.part.* must stay out of current Protocol/SDK Next surfaces absent a documented current-client requirement.
• 🟡 (09:06) packages/core/package.json defines typecheck as tsgo --noEmit and test as bun test --only-failures; root package.json defines test as echo 'do not run tests from root' && exit 1 and uses package manager bun@1.3.14.
• 🟡 (09:06) packages/core/src/session/execution/claim.ts defines SessionExecutionClaim.Claim with sessionID, executionID, and ownerID; Lost; and operations update, renew, settleCancellation, clear, and transaction.
• 🟡 (09:06) packages/core/src/session/execution/claim.ts fences claim operations by matching session_id, execution id, owner_id, and expires_at > now. update renews expiry to now + SESSION_EXECUTION_LEASE_MS; phase guards allow "cancelled" only from "cancelling", prevent "cancelling" from updating already "cancelled" claims, and prevent ordinary updates in "cancelling" or "cancelled" phases. Missing updates/deletes die with SessionExecutionClaim.Lost.
• 🟡 (09:06) SessionExecutionClaim.settleCancellation only updates a live claim whose phase is "cancelling". SessionExecutionClaim.transaction uses an immediate database transaction and performs update(db, claim) before the supplied effect.
• 🟡 (09:06) packages/core/src/session/recovery-id.ts deterministically generates recovery assistant IDs as msg_recovery_${executionID} unless an existing assistant message ID is supplied, and continuation IDs as msg_recovery_continue_${executionID}.
• 🟡 (09:06) Migration packages/core/src/database/migration/20260914170650_session-recovery.ts has ID 20260914170650_session-recovery; it adds session_input.wake_pending (integer DEFAULT false NOT NULL) and session.wake_attempts (integer DEFAULT 0 NOT NULL, constrained from 0 through 9007199254740991).
• 🟡 (09:06) Migration 20260914170650_session-recovery creates session_execution with fields id, session_id, owner_id, nullable assistant_message_id, phase, assistant_seq DEFAULT -1, time_created, expires_at, and nullable recovery_error. Allowed phases are 'ready', 'safe', 'unknown', 'continue', 'cancelling', and 'cancelled'; session_id references session(id) with ON DELETE CASCADE.
• 🟡 (09:06) Migration 20260914170650_session-recovery creates session_recovery with session_id, execution_id primary key, nullable assistant_message_id, continuation_message_id, phase, wake_pending DEFAULT true, wake_attempts DEFAULT 0 constrained through 9007199254740991, nullable recovery_error, and time_created. Foreign keys cascade from session, session_message, and session_input.
• 🟡 (09:06) Migration 20260914170650_session-recovery creates unique indexes session_execution_session_idx and session_recovery_continuation_message_idx, plus session_execution_owner_idx, session_execution_recovery_scan_idx, session_input_wake_pending_promoted_session_idx, and session_recovery_wake_pending_error_attempts_created_execution_idx.