Distillation

Date: Sep 16, 2026

• 🟡 (15:54) Patch search found the same 4 added files in 5 patch versions: /tmp/opencode/session-recovery-final-v7.patch at lines 892, 2289, 9075, 9147; /tmp/opencode/session-recovery-final-v6.patch at lines 877, 2267, 8698, 8770; /tmp/opencode/session-recovery-final-v8.patch at lines 892, 2289, 9451, 9523; /tmp/opencode/session-recovery-final-v5.patch at lines 878, 1327, 2322, 2334; and /tmp/opencode/session-recovery-final-v4.patch at lines 881, 1330, 2319, 2331. The files are packages/core/src/database/migration/20260914170650_session-recovery.ts, packages/core/src/session/recovery.ts, packages/core/src/session/execution/claim.ts, and packages/core/src/session/recovery-id.ts.
• 🟡 (15:54) Exact-delta validation succeeded with output EXACT_DELTA_OK base=HEAD changed_paths=33.
• 🟡 (15:54) Tool found 17 nested instruction files: packages/stats/AGENTS.md, packages/schema/AGENTS.md, packages/app/AGENTS.md, packages/core/src/tool/AGENTS.md, packages/desktop/AGENTS.md, packages/session-ui/AGENTS.md, packages/app/e2e/AGENTS.md, packages/app/e2e/performance/AGENTS.md, packages/ui/AGENTS.md, packages/effect-drizzle-sqlite/AGENTS.md, packages/llm/AGENTS.md, packages/codemode/AGENTS.md, packages/opencode/AGENTS.md, packages/opencode/src/server/routes/instance/httpapi/AGENTS.md, packages/opencode/src/session/llm/AGENTS.md, packages/opencode/test/AGENTS.md, and packages/opencode/test/server/AGENTS.md.
• 🔴 (15:54) User stated the standalone executable is built with ./packages/opencode/script/build.ts --single, then run as ./packages/opencode/dist/opencode-<platform>/bin/opencode; replace <platform> with the target platform, e.g. darwin-arm64 or linux-x64.
• 🟡 (15:54) CONTRIBUTING.md says OpenCode requires Bun 1.3+, installs/runs with bun install then bun dev, defaults bun dev to packages/opencode, supports bun dev <directory> and bun dev ., and maps development commands to production equivalents: bun dev --help/opencode --help, bun dev serve/opencode serve, bun dev web/opencode web, and bun dev <directory>/opencode <directory>.
• 🟡 (15:54) CONTRIBUTING.md documents server/UI/desktop workflows: headless API server bun dev serve on port 4096 by default or bun dev serve --port 8080; web app bun run --cwd packages/app dev at http://localhost:5173 or a nearby reported port; desktop development bun run --cwd packages/desktop dev; desktop production commands bun run --cwd packages/desktop build and bun run --cwd packages/desktop package; API or SDK changes require ./script/generate.ts.
• 🟡 (15:54) CONTRIBUTING.md debugging guidance recommends manually running bun run --inspect=<url> dev ...; for TUI breakpoints in server code it suggests bun dev spawn; separate debugging uses bun run --inspect=ws://localhost:6499/ --cwd packages/opencode ./src/index.ts serve --port 4096, opencode attach http://localhost:4096, and bun run --inspect=ws://localhost:6499/ --cwd packages/opencode ./src/index.ts. Alternatives include --inspect-wait, --inspect-brk, and export BUN_OPTIONS=--inspect=ws://localhost:6499/; VSCode "request": "launch" and JavaScript Debug Terminal may map breakpoints incorrectly.
• 🟡 (15:54) CONTRIBUTING.md PR policy requires every PR to reference an existing issue via forms such as Fixes #123 or Closes #123, asks for small focused changes and verification details, requires before/after screenshots or videos for UI changes, rejects long AI-generated descriptions, and uses conventional title prefixes in this order: feat:, fix:, docs:, chore:, refactor:, test:; optional scopes include feat(app):, fix(desktop):, and chore(opencode):.
• 🟡 (15:54) packages/schema/AGENTS.md defines dependency direction @opencode-ai/schema <- @opencode-ai/protocol <- @opencode-ai/server; Schema owns browser-safe serializable wire/storage contracts, while runtime behavior and service layers remain in owning domain packages. Current contracts are unversioned, retained legacy contracts use V1, V2 must not remain the permanent replacement-architecture name, and new/current code must not depend on the future isolated src/v1/ subtree.
• 🟡 (15:54) packages/schema/AGENTS.md event rules classify events as current, shared transitional, or V1-only; V1 emission alone does not justify inclusion in Protocol/SDK Next, and events such as message.updated and message.part.* stay out of current Protocol/SDK Next absent a documented current-client requirement. Definitions must remain canonical rather than duplicated for generation.
• 🟡 (15:54) packages/schema/AGENTS.md contract conventions require one canonical value rather than bridge aliases such as PluginID, PluginEvent, PtyInfo, PtyEvent, or SessionTodoInfo; prefer namespace members such as Plugin.ID and SessionTodo.Info; use flat exports plus projections such as export * as SessionMessage from "./session-message"; exported schemas use PascalCase, combinators use camelCase, and the static combinator is statics(...).
• 🟡 (15:54) packages/schema/AGENTS.md schema rules: optional properties use optional(...); raw Schema.optional(...) is only for intentionally encoded undefined; convenience defaults use Schema.withDecodingDefault(...); public Schema.Struct records get same-name interfaces; public contracts are readonly and must not use Schema.mutable(...); use Schema.Json for JSON values and Schema.Unknown for opaque values, avoiding Schema.Any except documented unsafe compatibility boundaries.
• 🟡 (15:54) packages/schema/AGENTS.md ID/testing rules: current ID constructors expose create(); ascending()/descending() remain only for ordering semantics or compatibility; generated ID schemas validate the exact emitted prefix including _; legacy validators are not tightened without compatibility/migration decisions; public identifiers must be stable, unique, and domain-qualified. Tests should cover omitted undefined, absence of accidental current-contract Schema.Any, identifier uniqueness/stability, exact facade/schema identity, and exclusion of V1-only events from current Protocol manifests.
• 🟡 (15:54) packages/opencode/AGENTS.md says Drizzle schemas live in packages/core/src/**/*.sql.ts and migrations live in and are applied by packages/core. Interactive bun dev from packages/opencode should run via tmux new-session -d -s opencode-dev 'bun dev', be inspected with tmux capture-pane -pt opencode-dev, and stopped with tmux kill-session -t opencode-dev.
• 🟡 (15:54) packages/opencode/AGENTS.md rejects export namespace Foo { ... }; modules use flat exports and a self-reexport such as export * as Foo from "./foo", or export * as Foo from "." in index.ts. Multi-sibling directories such as src/session/ and src/config/ should not gain barrel index.ts files; consumers import specific siblings such as @/session/retry and @/session/status.
• 🟡 (15:54) packages/opencode/AGENTS.md Effect conventions include Effect.gen, named Effect.fn("Domain.method"), internal Effect.fnUntraced, Effect.callback, Effect.void, and DateTime.nowAsDate; use Schema.Class, Schema.brand, Schema.TaggedErrorClass, and Schema.Defect; direct failures in generators prefer yield* new MyError(...).
• 🟡 (15:54) packages/opencode/AGENTS.md service decisions: use makeRuntime for all services; use InstanceState for per-directory/project state and cleanup; do work directly in InstanceState.make; clean up with Effect.addFinalizer or Effect.acquireRelease; use Effect.forkScoped for background consumers; fork InstanceState.get(state) at the init() caller with Effect.forkIn(scope) rather than inside the closure. src/project/bootstrap.ts already wraps service init() calls in Effect.forkDetach.
• 🟡 (15:54) packages/opencode/AGENTS.md notes Effect v4 beta has no Effect.fork or Effect.forkDaemon; use Effect.forkIn(scope). Preferred services are FileSystem.FileSystem, ChildProcessSpawner.ChildProcessSpawner with ChildProcess.make(...), HttpClient.HttpClient, Path.Path, Config, Clock, and DateTime; loops use Effect.repeat or Effect.schedule with Effect.forkScoped; concurrent in-flight work uses Effect.cached; native/external callbacks re-enter through EffectBridge.
• 🟡 (15:54) packages/opencode/src/server/routes/instance/httpapi/AGENTS.md requires normal and SSE endpoints to use HttpApiBuilder.group(...); SSE handlers return HttpServerResponse.stream(...) and annotate success with HttpApiSchema.asText({ contentType: "text/event-stream" }). Declared raw/WebSocket routes use handleRaw(...); raw HttpRouter.use(...) is reserved for undeclared surfaces such as catch-all UI fallback.
• 🟡 (15:54) HTTP API route guidance says stable services are yielded once while constructing the handler layer; avoid per-request Effect.provide(SomeLayer) and avoid HttpRouter.provideRequest(...) unless truly request-level. Effect.provideService(...) middleware is for request-derived context such as WorkspaceRouteContext, InstanceRef, or WorkspaceRef. SDK-visible JSON errors must be explicit endpoint Schema.ErrorClass contracts, with expected domain errors translated at the handler boundary.
• 🟡 (15:55) Root package.json identifies package manager bun@1.3.14; key scripts are dev, dev:desktop, dev:web, dev:console, dev:stats, dev:storybook, lint, typecheck, upgrade-opentui, postinstall, prepare, random, sso, translate:app, and a deliberately failing root test script: echo 'do not run tests from root' && exit 1. Formatting is semi: false, printWidth: 120.
• 🟡 (15:55) Root workspaces are packages/*, packages/console/*, packages/stats/*, packages/sdk/js, and packages/slack. Important catalog versions include effect/Effect platform packages 4.0.0-beta.83, drizzle-kit and drizzle-orm 1.0.0-rc.2, ai 6.0.168, Bun types 1.3.13, Node types 24.12.2, TypeScript 5.8.2, native-preview TypeScript 7.0.0-dev.20251207.1, Zod 4.1.8, Vite 7.1.4, and SolidJS 1.9.10.
• 🟡 (15:55) Package manifests show @opencode-ai/core version 1.18.30 with scripts db, migration, fix-node-pty, test: bun test --only-failures, and typecheck: tsgo --noEmit; @opencode-ai/schema exports "." as ./src/index.ts and "./*" as ./src/*.ts, with only effect as a runtime dependency; @opencode-ai/server version 1.18.30 depends on @opencode-ai/core, @opencode-ai/protocol, drizzle-orm, and effect; packages/opencode version 1.18.30 uses test: bun test --timeout 30000 --only-failures and test:httpapi runs coverage, auth, and effect modes with --fail-on-missing --fail-on-skip.
• 🟡 (15:55) New 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.
• 🟡 (15:55) Migration 20260914170650_session-recovery creates session_execution with columns id, session_id, owner_id, nullable assistant_message_id, phase, time_created, expires_at, and nullable recovery_error; primary key session_execution_pk; allowed phases 'ready', 'safe', 'unknown', and 'continue'; and cascading foreign key from session_id to session.id.
• 🟡 (15:55) Migration 20260914170650_session-recovery creates session_recovery with columns session_id, execution_id, nullable assistant_message_id, continuation_message_id, phase, wake_pending DEFAULT true, wake_attempts DEFAULT 0, nullable recovery_error, and time_created; primary key is execution_id; wake attempts are constrained from 0 through 9007199254740991; cascading foreign keys target session.id, session_message.id, and session_input.id.
• 🟡 (15:55) Migration indexes are: unique session_execution_session_idx on session_execution(session_id); session_execution_owner_idx on owner_id; session_input_wake_pending_promoted_session_idx on (wake_pending, promoted_seq, session_id); unique session_recovery_continuation_message_idx on continuation_message_id; and session_recovery_wake_pending_error_attempts_created_execution_idx on (wake_pending, recovery_error, wake_attempts, time_created, execution_id).
• 🔴 (15:55) User stated lease timestamps use node wall clocks; the lease interval must exceed maximum deployment clock skew plus one renewal interval, execution IDs immediately fence a node after takeover, and an expired claim never renews itself.
• 🟡 (15:55) New packages/core/src/session/execution/claim.ts self-exports SessionExecutionClaim; Claim contains readonly sessionID: SessionSchema.ID, executionID: string, and ownerID: string; Values optionally selects assistant_message_id and phase; Lost extends Error with message Session execution claim lost: ${claim.executionID}.
• 🟡 (15:55) SessionExecutionClaim.where() validates matching session_id, execution id, owner_id, and expires_at > now. update() refreshes expires_at to now + SESSION_EXECUTION_LEASE_MS, optionally updates assistant_message_id/phase, and dies with Lost if no active row matches. clear() deletes only a still-valid matching claim and likewise dies with Lost. transaction() starts an immediate database transaction, renews the claim first, then runs the supplied effect, with failures converted via Effect.orDie.
• 🟡 (15:55) New packages/core/src/session/recovery-id.ts defines message(executionID, assistantMessageID?), which preserves an existing assistant message ID or creates SessionMessage.ID.make(\msg_recovery_${executionID}`), and continuation(executionID), which creates SessionMessage.ID.make(`msg_recovery_continue_${executionID}`)`.