Distillation

Date: Sep 16, 2026

• 🔴 (11:12) Repository guidance in /tmp/opencode/session-recovery-v5-review.r03hHL/AGENTS.md requires regenerating the legacy JavaScript SDK with ./packages/sdk/js/script/build.ts; after public Protocol or Server HttpApi changes, run bun run generate from packages/client and never edit src/generated or src/generated-effect directly.
• 🔴 (11:12) Repository dependency direction is 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.
• 🔴 (11:12) The repository default branch is dev; local main may not exist, so diffs should use dev or origin/dev.
• 🔴 (11:12) Branch names must contain at most 3 hyphen-separated words and must not use slashes or type prefixes such as feat/ or fix/; examples are session-recovery, fix-scroll-state, and regenerate-sdk.
• 🔴 (11:12) Commit messages and PR titles must 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.
• 🔴 (11:12) Repository style requires keeping logic in one function unless genuinely composable/reusable; avoiding preemptive single-use helpers, try/catch, any, unnecessary destructuring, reassignment, and else; preferring Bun APIs, inferred types, functional array methods, const, ternaries, and early returns.
• 🔴 (11:12) Never alias imports, including forms such as import { foo as bar } from "..." or resolve as pathResolve.
• 🔴 (11:12) Never use star imports, including import * as Foo from "..." and import type * as Foo from "..."; import a module’s own exported namespace by name, such as import { Project } from "@opencode-ai/core/project", and reference Project.ID.
• 🔴 (11:12) Heavy modules needed only in selected paths should use dynamic imports at the top of the narrowest applicable scope; branch-specific imports remain inside their branch, and inline chains such as await import("./module").then(...) or (await import("./module")).value() are disallowed.
• 🔴 (11:12) Drizzle schema fields must use snake_case so column names do not need explicit string remapping.
• 🔴 (11:12) Tests must not 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. Tests should avoid mocks and globalThis.*, and exercise the actual implementation rather than duplicating logic.
• 🔴 (11:12) Always run bun typecheck from package directories such as packages/opencode; never invoke tsc directly.
• 🔴 (11:12) V2 Session Core guidance requires SessionV2.prompt(...) to durably admit exactly one session_input row before advisory SessionExecution.wake(sessionID), except resume: false requests admit-only behavior; the serialized runner promotes admitted inputs at safe boundaries.
• 🔴 (11:12) Reusing a Session ID adopts the existing Session. Reusing a prompt message ID is an exact retry only when Session, prompt, and delivery mode match; conflicting reuse must fail, while historical projected prompts lazily synthesize promoted inbox records during exact retry.
• 🔴 (11:12) SessionExecution must 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 should take a Session ID. V2 interruption targets the active process-local ownership chain, while idle or missing interruption is a no-op.
• 🔴 (11:12) SessionRunner, model resolution, tool registry, permissions, and filesystem must remain Location-scoped. Omitted Location.workspaceID means implicit-local placement; explicit workspace identity is reserved for future placement semantics.
• 🔴 (11:12) Each provider turn must contain one explicit llm.stream(request) call and reload projected history before durable continuation; orchestration must not bridge through legacy SessionPrompt.loop(...) or an in-memory tool loop.
• 🔴 (11:12) 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; post-crash provider-work continuation requires a separate explicit design. A drain has no durable identity or transcript boundary.
• 🔴 (11:12) Session delivery semantics are explicit: prompts steer by default and promote at the next safe provider-turn boundary when continuation is required; an explicit queue remains pending until the Session would otherwise 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.
• 🔴 (11:12) EventV2 replay owner claims must remain separate from clustered Session execution ownership.
• 🔴 (11:12) 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.
• 🔴 (11:13) CONTRIBUTING.md requires Bun 1.3+; repository setup uses bun install and bun dev. The default headless server port is 4096, overrideable with bun dev serve --port 8080; the web app starts with bun run --cwd packages/app dev and commonly serves at http://localhost:5173.
• 🔴 (11:13) All PRs must reference an existing issue using forms such as Fixes #123 or Closes #123; UI PRs require before/after screenshots or videos, and logic changes must explain verification and reproduction. Net-new functionality requires a design conversation and approval before opening a feature PR.
• 🔴 (11:13) Issues must use the Bug report, Feature request, or Question template. An issue failing automated requirements has 2 hours to be corrected before automatic closure.
• 🔴 (11:13) packages/opencode/AGENTS.md states Drizzle schema lives in packages/core/src/**/*.sql.ts, while migrations live in packages/core and are applied by core.
• 🔴 (11:13) Running bun dev from packages/opencode starts the interactive TUI and must not be left as a blocking foreground process when inspecting results. Required detached workflow: start with tmux new-session -d -s opencode-dev 'bun dev', inspect with tmux capture-pane -pt opencode-dev, and stop with tmux kill-session -t opencode-dev.
• 🔴 (11:13) Module organization must not use export namespace Foo { ... }; use flat top-level exports and a self-reexport such as export * as Foo from "./foo". For a single-namespace directory’s index.ts, use export * as Foo from ".". Multi-sibling directories such as src/session/ and src/config/ must not add barrel index.ts files; consumers import specific siblings.
• 🔴 (11:13) Effect code should use Effect.gen(function* () { ... }), Effect.fn("Domain.method") for named/traced effects, Effect.fnUntraced for internal helpers, Effect.callback for callback APIs, Effect.void instead of Effect.succeed(undefined) or Effect.succeed(void 0), and DateTime.nowAsDate instead of new Date(yield* Clock.currentTimeMillis).
• 🔴 (11:13) Effect schema/error conventions require Schema.Class for multi-field data, Schema.brand for single-value types, Schema.TaggedErrorClass for typed errors, and Schema.Defect rather than unknown for defect-like causes. Direct early failures in Effect.gen/Effect.fn should use yield* new MyError(...).
• 🔴 (11:13) All services should use makeRuntime from src/effect/run-service.ts, which returns { runPromise, runFork, runCallback } backed by a shared memoMap. Per-directory/project state requiring cleanup must use InstanceState from src/effect/instance-state.ts, whose ScopedCache is keyed by directory.
• 🔴 (11:13) InstanceState.make must perform work directly without extra fibers, ensure() callbacks, or started flags. Cleanup uses Effect.addFinalizer or Effect.acquireRelease; background consumers use Effect.forkScoped. Non-blocking init() behavior is controlled at the call site with Effect.forkIn(scope), while src/project/bootstrap.ts already wraps every service init() in Effect.forkDetach.
• 🔴 (11:13) Effect v4 beta has no Effect.fork or Effect.forkDaemon; use Effect.forkIn(scope).
• 🔴 (11:13) Effect services should prefer FileSystem.FileSystem over raw fs/promises, ChildProcessSpawner.ChildProcessSpawner with ChildProcess.make(...) over custom process wrappers, HttpClient.HttpClient over raw fetch, and Effect-provided Path.Path, Config, Clock, and DateTime. Scheduled/background loops use Effect.repeat or Effect.schedule with Effect.forkScoped.
• 🔴 (11:13) Concurrent callers should share in-flight computation via Effect.cached, not manually stored Fiber | undefined or Promise | undefined. Native/external callbacks such as @parcel/watcher, node-pty, native fs.watch, and plugin callbacks should re-enter Effect through EffectBridge, not ambient instance-context shims.
• 🔴 (11:13) packages/schema/AGENTS.md defines @opencode-ai/schema as owner of browser-safe wire/storage contracts; runtime behavior, service layers, side effects, registries, and host-local implementation remain in their domain packages. Dependency direction is @opencode-ai/schema <- @opencode-ai/protocol <- @opencode-ai/server.
• 🔴 (11:13) Current Schema contracts are unversioned (Session, Permission, Question); retained legacy contracts use explicit V1 names. V2 must not remain as the permanent replacement-architecture name. New/current code must not depend on the future isolated src/v1/ subtree.
• 🔴 (11:13) Public event definitions must be classified as current, shared transitional, or V1-only. V1-only events such as message.updated and message.part.* stay out of current Protocol/SDK Next unless a current-client requirement is documented; definitions must remain canonical rather than duplicated for generation.
• 🔴 (11:13) Public Schema contracts are readonly by default and must not use Schema.mutable(...); mutation belongs at runtime boundaries through Types.DeepMutable, a dedicated draft type, or another explicit mutable API.
• 🔴 (11:13) Current public Schema contracts avoid Schema.Any; use Schema.Json for JSON-serializable values and Schema.Unknown for opaque values needing consumer narrowing. Schema.Any is allowed only at explicitly unsafe compatibility boundaries with a documented reason.
• 🔴 (11:13) New generated ID schemas must validate exactly their emitted prefix, including the underscore. Legacy loose validators must not be tightened without an explicit compatibility and migration decision. Reusable public schemas require stable, unique, domain-qualified identifiers such as Model.Ref or Agent.Color.
• 🔴 (11:13) Contract/generated-surface changes require focused tests covering optional properties omitting undefined, absence of accidental current-contract Schema.Any, stable and unique public identifiers, exact facade/schema identity, and exclusion of V1-only events from current Protocol manifests.
• 🔴 (11:13) packages/opencode/src/server/routes/instance/httpapi/AGENTS.md requires HttpApiBuilder.group(...) for normal and SSE HTTP endpoints; SSE handlers return HttpServerResponse.stream(...) and annotate success with HttpApiSchema.asText({ contentType: "text/event-stream" }).
• 🔴 (11:13) Declared endpoints requiring raw request/response access, including WebSocket upgrades, use HttpApiBuilder.group(...) with handleRaw(...). Raw HttpRouter.use(...) is only for routes outside the declared API, such as catch-all UI fallback.
• 🔴 (11:13) HTTP handlers must not call Effect.provide(SomeLayer) to rebuild stable layers per request. Stable services are yielded once while constructing the handler layer. HttpRouter.provideRequest(...) is reserved for intentional request-level dependencies; Effect.provideService(...) in middleware is only for request-derived context such as WorkspaceRouteContext, InstanceRef, or WorkspaceRef.
• 🔴 (11:13) Public JSON errors must be explicit endpoint-declared Schema.ErrorClass contracts. Built-in HttpApiError.* is only appropriate when its empty/tagged body is the intended wire shape; SDK-visible errors with messages require an exact declared schema such as ApiNotFoundError. Domain/storage services remain free of HttpApi types, with expected errors translated at the handler boundary.
• 🔴 (11:13) Root package.json identifies package manager bun@1.3.14, root typecheck as bun turbo typecheck, root test as echo 'do not run tests from root' && exit 1, Prettier configuration semi: false and printWidth: 120, TypeScript 5.8.2, and Effect 4.0.0-beta.83.
• 🔴 (11:13) packages/core/package.json identifies @opencode-ai/core version 1.18.30; its test script is bun test --only-failures, and its typecheck script is tsgo --noEmit.
• 🔴 (11:13) packages/schema/package.json identifies @opencode-ai/schema; its typecheck script is tsgo --noEmit.
• 🔴 (11:13) packages/server/package.json identifies @opencode-ai/server version 1.18.30; its typecheck script is tsgo --noEmit, and its dependencies include @opencode-ai/core, @opencode-ai/protocol, drizzle-orm, and effect.