Distillation

Date: Sep 14, 2026

• 🔴 (08:53) User directed research-only work in /home/byk/Code/opencode; no files may be edited or implementation performed.
• 🟡 (08:53) User asked for the smallest correct V2 startup-recovery design: after process restart, discover Sessions that were active/unfinished; durably mark abandoned provider/tool work as interrupted/unknown so it is model-visible; admit a fresh synthetic user prompt equivalent to continue; then wake through the normal path.
• 🔴 (08:53) User mandated that V2 startup recovery must never call or bridge through legacy SessionPrompt.
• 🔴 (08:53) User required durable atomic claiming to prevent duplicate recovery by concurrent server processes.
• 🔴 (08:53) User required the recovery design to preserve layering.
• 🟡 (08:53) User asked whether current durable facts can identify active unfinished Sessions, which new durable facts are essential, and for exact proposed symbols, files, schema, events, and tests with source references.
• 🟡 (08:53) Repository instruction files discovered include /home/byk/Code/opencode/AGENTS.md, /home/byk/Code/opencode/CONTRIBUTING.md, and package-specific AGENTS.md files under packages/codemode, packages/session-ui, packages/schema, packages/effect-drizzle-sqlite, packages/llm, packages/opencode, packages/stats, packages/core/src/tool, packages/ui, packages/app, packages/desktop, and relevant test/server/session subdirectories.
• 🟡 (08:54) V2 Session Core implementation files identified for inspection: packages/core/src/session/projector.ts, compaction.ts, todo.ts, store.ts, sql.ts, schema.ts, run-coordinator.ts, revert.ts, prompt.ts, message.ts, message-updater.ts, input.ts, info.ts, history.ts, execution.ts, event.ts, error.ts, context-epoch.ts, execution/local.ts, and runner files runner/index.ts, runner/llm.ts, runner/model.ts, runner/max-steps.ts, runner/to-llm-message.ts, runner/publish-llm-event.ts.
• 🟡 (08:54) Existing Core Session tests identified: packages/core/test/session-runner.test.ts, session-projector.test.ts, session-compaction.test.ts, session-runner-tool-registry.test.ts, session-runner-recorded.test.ts, session-prompt.test.ts, session-history.test.ts, session-create.test.ts, move-session.test.ts, session-tool-progress.test.ts, session-todo.test.ts, session-runner-tool-events.test.ts, session-runner-model.test.ts, session-runner-message.test.ts, and session-run-coordinator.test.ts.
• 🟡 (08:54) Server startup/API candidates identified: packages/server/src/routes.ts, auth.ts, pty-environment.ts, location.ts, handlers.ts, api.ts, cors.ts, middleware/session-location.ts, middleware/schema-error.ts, middleware/authorization.ts, and handlers under packages/server/src/handlers/, including session.ts, message.ts, and event.ts.
• 🔴 (08:54) User requires current Effect v4 / effect-smol APIs to be verified against .opencode/references/effect-smol and nearby repository code rather than answered from memory; reusable workflows should use Effect.gen(function* () { ... }) and Effect.fn("Name") or Effect.fnUntraced(...) where appropriate.
• 🔴 (08:54) User requires tests involving Effect services to use repository patterns such as testEffect(...) from packages/opencode/test/lib/effect.ts, with it.live(...) for live platform behavior and explicit test layers/scoped fixtures.
• 🔴 (08:54) User stated package tests must never be run from the repository root; run them from package directories such as packages/opencode. This is enforced by the root package.json script "test": "echo 'do not run tests from root' && exit 1" and /home/byk/Code/opencode/AGENTS.md:141-145.
• 🔴 (08:54) User stated type checking must always use bun typecheck from package directories such as packages/opencode, never tsc directly (/home/byk/Code/opencode/AGENTS.md:147-149).
• 🔴 (08:54) User requires runtime dependency direction from Schema to Core and Protocol, then Core and Protocol to Server; Client runtime code may depend on Schema and Protocol but never Core or Server; sdk-next composes Client, Core, and Server (/home/byk/Code/opencode/AGENTS.md:3).
• 🔴 (08:54) User stated imports must never be aliased: do not use forms such as import { foo as bar } from "..." or resolve as pathResolve (/home/byk/Code/opencode/AGENTS.md:59-64).
• 🔴 (08:54) User also requires no star imports, including import * as Foo from "..." and import type * as Foo from "..."; namespace-style usage must import the module’s own named namespace, e.g. import { Project } from "@opencode-ai/core/project" and then Project.ID.
• 🔴 (08:54) User prefers dynamic imports for heavy modules needed only on selected paths, especially startup-sensitive entrypoints; bindings should be destructured near the top of the narrowest scope, branch-specific imports should remain inside their branch, and inline chains such as await import("./module").then((mod) => mod.value()) or (await import("./module")).value() should be avoided.
• 🔴 (08:54) Current V2 policy separates durable admission from execution: SessionV2.prompt(...) admits one durable session_input row before scheduling advisory SessionExecution.wake(sessionID), unless resume: false requests admit-only behavior; the serialized runner promotes admitted inputs at safe boundaries (/home/byk/Code/opencode/AGENTS.md:151-154).
• 🔴 (08:54) Current V2 policy makes SessionExecution process-global and Session-ID based. Its local implementation owns the process-local Session coordinator and discovers placement via SessionStore plus LocationServiceMap.get(session.location) only when a drain starts; no layer should take a Session ID. Interruption targets the active process-local ownership chain, and idle or missing interruption is a no-op (/home/byk/Code/opencode/AGENTS.md:155).
• 🔴 (08:54) SessionRunner, model resolution, tool registry, permissions, and filesystem must remain Location-scoped; omitted Location.workspaceID means implicit-local placement, while explicit workspace identity is reserved for future placement semantics (/home/byk/Code/opencode/AGENTS.md:156).
• 🔴 (08:54) V2 execution must preserve exactly one explicit llm.stream(request) call per provider turn and reload projected history before durable continuation; orchestration must not bridge through SessionPrompt.loop(...) or delegate to an in-memory tool loop (/home/byk/Code/opencode/AGENTS.md:157).
• 🔴 (08:54) Current local Session drains remain process-local until clustering exists. SessionRunCoordinator joins explicit same-Session resumes, coalesces prompt wakeups, and permits different Sessions to run concurrently. Advisory wakes drain only eligible durable inbox rows. Existing policy explicitly states that post-crash continuation recovery requires a separate explicit design before provider work may be retried, and that a drain has no durable identity or transcript boundary (/home/byk/Code/opencode/AGENTS.md:158).
• 🔴 (08:54) Delivery semantics must remain explicit: default prompts steer and promote at the next safe provider-turn boundary while continuation is required; explicit queue inputs remain pending until the Session would otherwise idle; one queued input is promoted at that boundary before continuation is reevaluated; promoting new user input resets the selected agent’s provider-turn allowance, with a batch of steers resetting it once (/home/byk/Code/opencode/AGENTS.md:159).
• 🔴 (08:54) EventV2 replay-owner claims must remain separate from clustered Session-execution ownership (/home/byk/Code/opencode/AGENTS.md:160).
• 🔴 (08:54) Repository style requires snake_case Drizzle fields; Effect generators must bind services to named variables before method calls rather than nested service yields; avoid any, unnecessary try/catch, non-null assertions, unchecked casts, unnecessary destructuring, reassignment, and else where early returns suffice.
• 🟡 (08:54) Public schema/event surfaces available for investigation include packages/schema/src/session.ts, session-id.ts, session-event.ts, session-message.ts, session-input.ts, session-delivery.ts, session-status-event.ts, event.ts, event-manifest.ts, durable-event-manifest.ts, and packages/protocol/src/groups/session.ts plus packages/protocol/src/groups/message.ts.
• 🟡 (08:55) Package scripts relevant to verification: packages/core/package.json defines "test": "bun test --only-failures" and "typecheck": "tsgo --noEmit"; packages/server/package.json defines "typecheck": "tsgo --noEmit". The repository uses Bun 1.3.14, Effect 4.0.0-beta.83, Drizzle ORM 1.0.0-rc.2, and TypeScript 5.8.2.