Distillation

Date: Sep 17, 2026

• 🔴 (08:33) User requires runtime dependencies to flow Schema → Core and Protocol → Server; Client runtime may depend on Schema and Protocol but never Core or Server; sdk-next composes Client, Core, and Server.
• 🔴 (08:33) User requires imports never be aliased, including forms such as import { foo as bar } from "..." and resolve as pathResolve.
• 🔴 (08:33) User requires never using star imports, including import * as Foo from "..." and import type * as Foo from "..."; namespace-style values should instead import a module’s own exported namespace by name, such as import { Project } from "@opencode-ai/core/project" and Project.ID.
• 🔴 (08:33) User requires always running bun typecheck from package directories such as packages/opencode, never running tsc directly.
• 🔴 (08:33) User’s repository guidance says 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.
• 🔴 (08:33) User’s repository guidance says public Protocol or Server HttpApi changes require bun run generate from packages/client; src/generated and src/generated-effect must not be edited directly.
• 🔴 (08:33) User’s repository guidance defines V2 session execution semantics: SessionV2.prompt(...) durably admits one session_input before scheduling advisory SessionExecution.wake(sessionID), except resume: false is admit-only; explicit Session-ID reuse adopts the existing Session; prompt message-ID reuse reconciles only exact retries matching Session, prompt, and delivery mode.
• 🔴 (08:33) User’s repository guidance requires SessionExecution to be process-global and Session-ID based; SessionRunner, model resolution, tool registry, permissions, and filesystem remain Location-scoped; V2 interruption targets only the active process-local ownership chain, while idle or missing interruption is a no-op.
• 🔴 (08:33) User’s repository guidance requires one explicit llm.stream(request) call per provider turn and reloading projected history before durable continuation; orchestration must not bridge through legacy SessionPrompt.loop(...) or an in-memory tool loop.
• 🔴 (08:33) User’s repository guidance says local Session drains remain process-local until clustering exists; SessionRunCoordinator joins explicit same-Session resumes, coalesces prompt wakeups, and permits different Sessions concurrently; advisory wakes drain eligible durable inbox rows only, and post-crash provider-work retry requires a separate explicit design.
• 🔴 (08:33) User’s repository guidance defines delivery semantics: default steer inputs promote at the next safe provider-turn boundary while continuation is needed; explicit queue inputs remain pending until otherwise idle, then one queued input promotes before continuation is reevaluated; any promoted user input resets the selected agent’s provider-turn allowance, with a steer batch resetting it once.
• 🟡 (08:34) Frozen review provenance was verified read-only: worktree /tmp/opencode/session-recovery-v20-review was detached at base ab9408c81cc9916177641ae8e9f08624fc27b5b9; patch SHA-256 matched 24352107c74d8245fcba7f8571ba0be4b7fc514e6c73cfbf0498f0c25f29f9ba and size was 419965 bytes; SEA SHA-256 matched d0c78e881892d4f894fab7f6be00643c133ca21f9d2c88ae0d5ff31215393021 and size was 157879104 bytes.
• 🟡 (08:34) Worktree inspection initially showed 29 tracked modified paths plus 5 untracked paths, totaling the expected 34 changed paths; no paths were staged. Patch-to-worktree verification later reported patch_paths=34, worktree_paths=34, path_set_match=True, and blob_mismatches=0.
• 🟡 (08:34) The 5 new files in frozen v20 are 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.
• 🟡 (08:35) An attempted inspection command using python failed with /usr/bin/bash: line 1: python: command not found; subsequent provenance comparison nevertheless completed successfully with all 34 paths matching and zero blob mismatches.
• 🔴 (08:35) User’s packages/opencode/AGENTS.md guidance prohibits export namespace Foo { ... }; modules must use flat top-level exports and a self-reexport such as export * as Foo from "./foo", or export * as Foo from "." for a single-namespace index.ts.
• 🔴 (08:35) User’s packages/opencode/AGENTS.md guidance prohibits barrel index.ts files in multi-sibling directories such as src/session/; each sibling must self-reexport and consumers must import the specific sibling, e.g. import { SessionRetry } from "@/session/retry".
• 🔴 (08:35) User’s Effect guidance requires Effect.gen(function* () { ... }) for composition, Effect.fn("Domain.method") for named/traced effects, Effect.fnUntraced for internal helpers, Effect.callback for callback APIs, and Effect.void instead of Effect.succeed(undefined) or Effect.succeed(void 0).
• 🔴 (08:35) User’s Effect v4 beta guidance says Effect.fork and Effect.forkDaemon do not exist; use Effect.forkIn(scope).
• 🔴 (08:35) User’s service guidance requires makeRuntime from src/effect/run-service.ts for all services and InstanceState from src/effect/instance-state.ts for per-directory or per-project state requiring per-instance cleanup.
• 🔴 (08:35) User’s HTTP API guidance requires normal and SSE endpoints to use HttpApiBuilder.group(...); declared raw request/response or WebSocket routes must use HttpApiBuilder.group(...) with handleRaw(...); raw HttpRouter.use(...) is reserved for routes outside the declared API surface.
• 🔴 (08:35) User’s HTTP API guidance prohibits Effect.provide(SomeLayer) inside request handlers or raw callbacks; stable layers belong at the application/layer boundary, while Effect.provideService(...) in middleware is only for request-derived context such as WorkspaceRouteContext, InstanceRef, or WorkspaceRef.
• 🔴 (08:36) User’s Schema guidance requires @opencode-ai/schema to contain browser-safe wire/storage contracts only, preserving dependency direction @opencode-ai/schema <- @opencode-ai/protocol <- @opencode-ai/server; runtime behavior, services, side effects, and host-local implementation stay in their owning domain packages.
• 🔴 (08:36) User’s Schema guidance requires current contracts to be unversioned, legacy compatibility contracts to use V1, and replacement architecture not to retain V2 permanently in namespaces, brands, or identifiers.
• 🔴 (08:36) User’s Schema guidance requires optional object properties to use the package optional(...) helper so encoded objects omit undefined; raw Schema.optional(...) is allowed only when explicitly preserving encoded undefined is intentional and documented.
• 🔴 (08:36) User’s Schema guidance requires public Schema contracts to be readonly by default and prohibits Schema.mutable(...) for runtime convenience; mutation must be explicitly introduced at the runtime boundary with Types.DeepMutable, a purpose-built draft type, or another mutable API.
• 🔴 (08:36) User’s Schema guidance requires current public contracts to avoid Schema.Any; use Schema.Json for JSON-serializable values and Schema.Unknown for genuinely opaque values requiring consumer narrowing.