Distillation

Date: Sep 14, 2026

• 🔴 [requested-research-only] (08:14) User instructed research only in /home/byk/Code/opencode; do not edit files.
• 🟡 (08:14) User asked for a very thorough investigation of V2 session durable admission/execution and restart recovery behavior, specifically whether V2 resumes active sessions after a server restart or only preserves queued prompts.
• 🟡 (08:14) User requested exact files, symbols, tests, concise evidence with file:line references, guarantees and gaps concerning provider-call duplication and tool-side-effect duplication, plus reusable design concepts for legacy v1.
• 🔴 (08:14) Repository package manager is bun@1.3.14; root package.json deliberately prevents root test execution via "test": "echo 'do not run tests from root' && exit 1".
• 🔴 [enforced-workflow] (08:14) User requires tests to be run from package directories such as packages/opencode, never from the repository root.
• 🔴 [enforced-workflow] (08:14) User requires bun typecheck to be run from package directories (for example, packages/opencode), never tsc directly.
• 🔴 (08:14) Runtime dependency direction must remain Schema → 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.
• 🔴 [corrected-style] (08:14) User requires imports never to be aliased; prohibited forms include import { foo as bar } from "..." and renamed imports such as resolve as pathResolve.
• 🔴 [corrected-style] (08:14) User requires never using star imports, including import * as Foo from "..." and import type * as Foo from "...".
• 🔴 (08:14) When namespace-style access is needed, import the module’s own exported namespace by name—for example, import { Project } from "@opencode-ai/core/project"—and reference members such as Project.ID.
• 🔴 (08:14) For heavy modules needed only on selected paths, prefer dynamic imports inside the narrowest relevant branch/scope; destructure bindings near the top of that scope and avoid inline chains such as await import("./module").then((mod) => mod.value()) or (await import("./module")).value().
• 🔴 (08:14) Public Protocol or Server HttpApi changes require running bun run generate from packages/client; never edit src/generated or src/generated-effect directly.
• 🔴 (08:14) Legacy JavaScript SDK regeneration uses ./packages/sdk/js/script/build.ts.
• 🔴 (08:14) Repository default branch is dev; local main may not exist, so diffs should use dev or origin/dev.
• 🔴 (08:14) Branch names must contain at most 3 short hyphen-separated words and must not use slashes or type prefixes such as feat/ or fix/; examples include session-recovery, fix-scroll-state, and regenerate-sdk.
• 🔴 (08:14) Commits and PR titles use type(scope): summary; valid types are feat, fix, docs, chore, refactor, and test, with optional scopes such as core, opencode, tui, app, desktop, sdk, or plugin.
• 🔴 (08:14) V2 durable prompt admission must remain separate from model 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 into visible user messages only at safe boundaries.
• 🔴 (08:14) Reusing a Session ID adopts the existing Session. Reusing a prompt message ID reconciles an exact retry only when Session, prompt, and delivery mode match; conflicting reuse fails. Exact retries of historical projected prompts lazily synthesize promoted inbox records.
• 🔴 (08:14) SessionExecution must stay process-global and Session-ID based. Its local implementation owns the process-local Session coordinator and discovers placement through SessionStore plus LocationServiceMap.get(session.location) only when a drain starts; no layer should take a Session ID.
• 🔴 (08:14) V2 interruption targets the active process-local ownership chain for the Session; interruption of an idle or missing Session is a no-op.
• 🔴 (08:14) SessionRunner, model resolution, tool registry, permissions, and filesystem must remain Location-scoped. An omitted Location.workspaceID means implicit-local placement; explicit workspace identity is reserved for future placement semantics.
• 🔴 (08:14) V2 must preserve exactly one explicit llm.stream(request) call per provider turn and reload projected history before durable continuation; it must not bridge through legacy SessionPrompt.loop(...) or delegate orchestration to an in-memory tool loop.
• 🔴 (08:14) Local Session drains remain process-local until clustering is implemented. SessionRunCoordinator joins explicit same-Session resumes, coalesces prompt wakeups, and permits different Sessions to run concurrently.
• 🔴 (08:14) Advisory wakes drain only eligible durable inbox rows. Post-crash continuation recovery needs a separate explicit design before provider work may be retried; a drain has neither a durable identity nor a transcript boundary.
• 🔴 (08:14) V2 delivery semantics are explicit: prompts steer by default and promote at the next safe provider-turn boundary while the current drain requires continuation; an explicit queue input stays pending until the Session would otherwise become idle, at which point one queued input is promoted and continuation is reevaluated before another is promoted.
• 🔴 (08:14) Promoting any new user input resets the selected agent’s provider-turn allowance; a batch of steer inputs resets it once.
• 🔴 (08:14) EventV2 replay owner claims must remain separate from clustered Session execution ownership.
• 🔴 (08:14) The System Context algebra, registry, and built-ins belong in src/system-context; Context Source producers remain with their observed domains; Session History selection and Context Epoch persistence remain Session-owned.