Distillation

Date: Sep 15, 2026

• 🔴 (16:43) User’s repository dependency rule: runtime dependencies flow 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.
• 🔴 (16:43) User’s repository default branch is dev; local main may not exist, so diffs should use dev or origin/dev.
• 🔴 (16:43) User requires branch names of at most three hyphen-separated words, without slashes or type prefixes such as feat/ or fix/; examples: session-recovery, fix-scroll-state, regenerate-sdk.
• 🔴 (16:43) User requires conventional commit-style commit messages and PR titles in type(scope): summary form. Valid types: feat, fix, docs, chore, refactor, test; optional scopes include core, opencode, tui, app, desktop, sdk, and plugin.
• 🔴 (16:43) User’s code-style rules: keep code in one function unless composable/reusable; do not preemptively extract single-use helpers; avoid try/catch and any; prefer Bun APIs such as Bun.file(); rely on type inference; prefer flatMap, filter, and map over loops; bind Effect services to named variables rather than nested yields; inline values used once to reduce variable count.
• 🔴 (16:43) User prefers dot notation over unnecessary destructuring, const over let, and ternaries or early returns over reassignment; avoid else statements.
• 🔴 (16:43) User requires complex functions to expose the happy path and place genuinely meaningful supporting helpers below the main export; helpers should remain synchronous unless they perform effectful work. For untrusted JSON, prefer Schema.UnknownFromJsonString and Schema.decodeUnknownOption over manual JSON.parse wrapped in Effect.try.
• 🔴 (16:43) User requires comments only for non-obvious constraints or surprising behavior, not obvious assignments or control flow.
• 🔴 (16:43) User requires Drizzle schema fields to use snake_case directly so column names do not need explicit string mappings.
• 🔴 (16:43) User requires src/config modules to follow the self-export pattern, e.g. export * as ConfigAgent from "./agent".
• 🔴 (16:43) User requires the legacy JavaScript SDK to be regenerated with ./packages/sdk/js/script/build.ts.
• 🔴 (16:43) User requires bun run generate from packages/client after changing the public Protocol or Server HttpApi; src/generated and src/generated-effect must not be edited directly.
• 🔴 (16:43) User stated imports must never be aliased; forbidden examples include import { foo as bar } from "..." and resolve as pathResolve.
• 🔴 (16:43) User stated star imports must never be used, including import * as Foo from "..." and import type * as Foo from "...". Namespace-style values should use the module’s own exported namespace, e.g. import { Project } from "@opencode-ai/core/project" followed by Project.ID.
• 🔴 (16:43) User prefers dynamic imports for heavy modules used only on selected paths, especially startup-sensitive entrypoints. Dynamic bindings should be destructured near the top of the narrowest scope; branch-specific imports should stay within that branch. Inline chains such as await import("./module").then((mod) => mod.value()) and (await import("./module")).value() are forbidden.
• 🔴 (16:43) User’s testing rules: avoid mocks and globalThis.* unless they are the only option; test actual implementation without duplicating its logic; tests cannot run from repository root because of the do-not-run-tests-from-root guard and must run from package directories such as packages/opencode.
• 🔴 (16:43) User requires type checking with bun typecheck from package directories such as packages/opencode; never run tsc directly.
• 🔴 (16:43) User’s V2 Session Core rule: SessionV2.prompt(...) must durably admit one session_input row before advisory SessionExecution.wake(sessionID) scheduling, except resume: false requests admit-only behavior; the serialized runner promotes admitted inputs into visible user messages only at safe boundaries.
• 🔴 (16:43) User’s V2 retry semantics: 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; historical projected prompts lazily synthesize promoted inbox records during exact retry.
• 🔴 (16:43) User requires SessionExecution to remain 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 takes a Session ID. V2 interruption targets the active local ownership chain, while idle or missing interruption is a no-op.
• 🔴 (16:43) User requires SessionRunner, model resolution, tool registry, permissions, and filesystem to remain Location-scoped. Missing Location.workspaceID means implicit-local placement; explicit workspace identity is reserved for future placement semantics.
• 🔴 (16:43) User requires exactly one explicit llm.stream(request) call per provider turn and projected-history reload before durable continuation; orchestration must not bridge through legacy SessionPrompt.loop(...) or an in-memory tool loop.
• 🔴 (16:43) User requires local Session drains to remain process-local until clustering exists. SessionRunCoordinator joins explicit same-Session resumes, coalesces prompt wakeups, and allows different Sessions to run concurrently. Advisory wakes drain only eligible durable inbox rows; post-crash provider-work retries require a separate explicit design. A drain has no durable identity or transcript boundary.
• 🔴 (16:43) User’s delivery semantics: prompts default to steer and promote at the next safe provider-turn boundary while continuation is required; explicit queue input remains pending until the Session would otherwise become idle, then one queued input is promoted before continuation is reevaluated. Any promoted user input resets the selected agent’s provider-turn allowance; a batch of steers resets it once.
• 🔴 (16:43) User requires EventV2 replay owner claims to remain separate from clustered Session execution ownership.
• 🔴 (16:43) User requires the System Context algebra, registry, and built-ins to remain in src/system-context; Context Source producers stay with their observed domains; Session History selection and Context Epoch persistence remain Session-owned.
• 🟡 (16:44) packages/core/test/session-run-coordinator.test.ts has tests for: joining wake-started execution without forcing a successor; coalescing wakes during active execution; idle interruption as a no-op; interrupting active execution and clearing its pending wake; running a wake registered during interruption cleanup; starting a resume registered during interruption cleanup; starting one follow-up when wake races with failure; and not cancelling execution when a joined waiter is interrupted.
• 🟡 (16:44) Session recovery is wired through migration packages/core/src/database/migration/20260914170650_session-recovery.ts with ID "20260914170650_session-recovery", dynamically imported by packages/core/src/database/migration.gen.ts; packages/core/src/session/recovery.ts names its node "session-recovery" with dependencies [Database.node, EventV2.node, SessionProjector.node, SessionExecution.node].
• 🟡 (16:45) packages/core/src/session.ts changed durable prompt admission to pass requestExecution: input.resume !== false alongside sessionID, prompt, and delivery, explicitly recording whether admitted input requests execution.
• 🟡 (16:45) packages/server/src/routes.ts includes SessionRecovery.node in applicationServices and builds the service layer with AppNodeBuilder.build(applicationServices, [[SessionExecution.node, SessionExecutionLocal.node]]), binding process-global SessionExecution to its local implementation.
• 🟡 (16:45) packages/server/src/routes.ts route construction provides, in order, handlers, sessionLocationLayer, locationLayer, authorizationLayer, schemaErrorLayer, authentication, and the built service layer to HttpApiBuilder.layer(Api, { openapiPath: "/openapi.json" }); webHandler disables logging via { disableLogger: true }.