Distillation

Date: Sep 16, 2026

• 🔴 (13:23) User established jj workflow rules for repositories containing .jj/: use jj rather than git for mutations; never use interactive flags (-i, --interactive) or jj resolve; always pass -m "msg" when describing/committing; verify mutations with jj st and jj log; prefer stable letter-based change IDs over hexadecimal commit IDs; never rebase or describe immutable commits; use jj undo, jj op log, or jj op restore <op-id> for recovery.
• 🔴 (13:23) User stated that jj operations never fail on merge conflict; the conflict is recorded in the resulting commit and should be detected with jj st, resolved by manually editing conflict markers, and confirmed cleared with another jj st.
• 🔴 (13:23) User stated jj’s working copy is commit @, its parent is @-, file edits automatically amend @, and there is no staging area, git add, or stash.
• 🔴 (13:23) User stated jj bookmarks do not automatically advance; they must be moved with jj bookmark set or jj bookmark move.
• 🔴 (13:23) User stated x..y means set difference while x::y means a DAG path, and these revsets are not interchangeable.
• 🔴 (13:23) User provided recovery patch /tmp/opencode/session-recovery-final-v6.patch with SHA-256 a5c1bace440d1b6acb383c4fcffc52714a9373892e75b4f23bdbbf2dfdad8e16.
• 🔴 (13:23) User provided built server binary /home/byk/Code/opencode/packages/opencode/dist/server/opencode-server with SHA-256 d09c992a0f4cce15e73dd158fe60413420109c821afed6e121d11cdad9c7b583.
• 🔴 (13:23) User provided commit metadata: ab9408c81cc9916177641ae8e9f08624fc27b5b9, 2e9407768d1401a25b69febb36657638a779053a, d3323b963b9ef2de41a7ff9884299c74b93886ba, timestamp 1789377773, description feat(app): adapt vertical tab density, and ancestry_exit=0.
• 🔴 (13:23) User’s patch /tmp/opencode/session-recovery-final-v6.patch contains session-recovery changes across 33 files, including new files packages/core/src/database/migration/20260914170650_session-recovery.ts, packages/core/src/session/recovery.ts, packages/core/src/session/execution/claim.ts, and packages/core/src/session/recovery-id.ts.
• 🔴 (13:23) User’s session-recovery patch modifies contracts/generated artifacts and runtime code including packages/core/schema.json, packages/core/src/database/migration.gen.ts, packages/core/src/database/schema.gen.ts, packages/core/src/session.ts, packages/core/src/session/compaction.ts, packages/core/src/session/context-epoch.ts, packages/core/src/session/execution/local.ts, packages/core/src/session/input.ts, packages/core/src/session/message-updater.ts, packages/core/src/session/projector.ts, packages/core/src/session/run-coordinator.ts, packages/core/src/session/runner/index.ts, packages/core/src/session/runner/llm.ts, packages/core/src/session/runner/publish-llm-event.ts, packages/core/src/session/sql.ts, packages/opencode/src/server/routes/instance/httpapi/server.ts, packages/schema/src/session-event.ts, packages/sdk/js/src/v2/gen/types.gen.ts, packages/sdk/openapi.json, and packages/server/src/routes.ts.
• 🔴 (13:23) User’s session-recovery patch modifies tests including packages/core/test/database-migration.test.ts, new packages/core/test/session-execution-local.test.ts, packages/core/test/session-projector.test.ts, packages/core/test/session-prompt.test.ts, packages/core/test/session-run-coordinator.test.ts, packages/core/test/session-runner-recorded.test.ts, packages/core/test/session-runner-tool-events.test.ts, packages/core/test/session-runner.test.ts, and packages/schema/test/event-manifest.test.ts.
• 🔴 (13:23) User stated OpenCode development requires Bun 1.3+; from the repository root, install and start with bun install and bun dev.
• 🔴 (13:23) User stated a standalone OpenCode executable is built with ./packages/opencode/script/build.ts --single and run as ./packages/opencode/dist/opencode-<platform>/bin/opencode.
• 🔴 (13:23) User directed replacing <platform> with the actual platform, for example darwin-arm64 or linux-x64.
• 🔴 (13:23) User stated bun dev <directory> starts the TUI against a specified directory, bun dev . targets the OpenCode repository root, bun dev serve starts the headless API server on port 4096 by default, and bun dev serve --port 8080 uses port 8080.
• 🔴 (13:23) User stated UI development uses bun run --cwd packages/app dev, normally at http://localhost:5173, with the OpenCode server running for full functionality.
• 🔴 (13:23) User stated SDK-related files must be regenerated with ./script/generate.ts after API or SDK changes such as changes to packages/opencode/src/server/server.ts.
• 🔴 (13:23) User stated OpenCode PRs must reference an existing issue using wording such as Fixes #123 or Closes #123; UI PRs should include before/after screenshots or videos; logic changes must explain verification and reproduction; descriptions should be short and focused rather than AI-generated walls of text.
• 🔴 (13:23) User stated OpenCode style preferences: keep logic in one function unless extraction adds reuse/composition; avoid unnecessary destructuring and else; prefer .catch(...) over try/catch; use precise types and avoid any; favor immutable patterns and avoid let; use concise descriptive single-word names; use Bun helpers such as Bun.file() when suitable.
• 🔴 (13:23) User stated @opencode-ai/core is version 1.18.30, is private and ESM ("type": "module"), uses bun test --only-failures for test, tsgo --noEmit for typecheck, and exports ./session/runner from ./src/session/runner/index.ts.
• 🔴 (13:23) User stated the repository has package-specific guidance files including packages/schema/AGENTS.md, packages/opencode/AGENTS.md, packages/opencode/src/server/routes/instance/httpapi/AGENTS.md, packages/core/src/tool/AGENTS.md, packages/app/AGENTS.md, and packages/desktop/AGENTS.md.
• 🔴 (13:24) User stated @opencode-ai/schema owns browser-safe wire and storage contracts; runtime behavior, service layers, side effects, and host-local implementation details stay in the owning domain package.
• 🔴 (13:24) User stated schema dependency direction must remain @opencode-ai/schema <- @opencode-ai/protocol <- @opencode-ai/server; current contracts are unversioned, retained legacy contracts are explicitly V1, and V2 must not remain the permanent name for replacement architecture contracts.
• 🔴 (13:24) User stated V1-only events such as message.updated and message.part.* should remain outside the current Protocol/SDK Next event surface unless a current-client requirement is documented, and there must be one canonical event definition rather than duplicates for generation convenience.
• 🔴 (13:24) User stated schema modules should use flat top-level exports plus namespace projection such as export * as SessionMessage from "./session-message"; bridge aliases such as PluginID, PluginEvent, PtyInfo, PtyEvent, and SessionTodoInfo should be avoided.
• 🔴 (13:24) User stated optional object properties should use the package optional(...) helper so encoded objects omit undefined; raw Schema.optional(...) is only for intentionally preserved, documented undefined properties; convenience defaults should normally use Schema.withDecodingDefault(...).
• 🔴 (13:24) User stated public Schema contracts are readonly by default, should avoid Schema.mutable(...), should use Schema.Json for JSON-serializable values and Schema.Unknown for opaque values, and should avoid Schema.Any except at explicitly unsafe documented compatibility boundaries.
• 🔴 (13:24) User stated current generated ID constructors expose create(), generated ID schemas must validate the exact emitted prefix including the underscore, and public schema identifiers/brands must be unique and stable.
• 🔴 (13:24) User requires focused tests for contract changes covering omission of optional undefined properties, 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.
• 🔴 (13:24) User stated normal and SSE HTTP endpoints should use HttpApiBuilder.group(...); SSE handlers should return HttpServerResponse.stream(...) and annotate success with HttpApiSchema.asText({ contentType: "text/event-stream" }).
• 🔴 (13:24) User stated declared endpoints requiring raw request/response access, including WebSocket upgrades, should use HttpApiBuilder.group(...) with handleRaw(...); raw HttpRouter.use(...) is reserved for routes outside the declared API surface such as catch-all UI fallbacks.
• 🔴 (13:24) User stated stable services should be yielded once while constructing HTTP handler layers and closed over by handlers; avoid Effect.provide(SomeLayer) inside request handlers and avoid HttpRouter.provideRequest(...) unless a dependency is intentionally request-level.
• 🔴 (13:24) User stated public JSON errors should be explicit Schema.ErrorClass endpoint contracts; SDK-visible errors requiring messages should use an exact declared API error such as ApiNotFoundError; domain/storage services should remain free of HttpApi types, with expected errors translated at the handler boundary.
• 🔴 (13:24) User stated OpenCode database schemas live in packages/core/src/**/*.sql.ts, while migrations live in packages/core and are applied by core.
• 🔴 (13:24) User directed running the interactive bun dev process in tmux rather than as a blocking foreground process: 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.
• 🔴 (13:24) User prohibited export namespace Foo { ... }; modules should expose flat top-level exports and a self-reexport such as export * as Foo from "./foo", or export * as Foo from "." in a single-namespace index.ts.
• 🔴 (13:24) User stated multi-sibling directories such as src/session/ and src/config/ should not gain barrel index.ts files; consumers should import specific siblings such as @/session/retry or @/session/status.
• 🔴 (13:24) User established Effect conventions: compose with Effect.gen(function* () { ... }); use Effect.fn("Domain.method") for named/traced effects and Effect.fnUntraced for internal helpers; use Effect.callback for callback APIs; use Effect.void instead of Effect.succeed(undefined); prefer DateTime.nowAsDate when a Date is needed.
• 🔴 (13:24) User established schema/error conventions in Effect code: use Schema.Class for multi-field data, Schema.brand for single-value types, Schema.TaggedErrorClass for typed errors, Schema.Defect for defect-like causes, and direct yield* new MyError(...) for early failures instead of yield* Effect.fail(new MyError(...)).
• 🔴 (13:24) User stated all services should use makeRuntime from src/effect/run-service.ts; per-directory/project state should use InstanceState from src/effect/instance-state.ts, with cleanup via Effect.addFinalizer or Effect.acquireRelease and scoped background consumers via Effect.forkScoped.
• 🔴 (13:24) User stated Effect v4 beta has no Effect.fork or Effect.forkDaemon; use Effect.forkIn(scope).
• 🔴 (13:24) User stated effectified services should prefer FileSystem.FileSystem, ChildProcessSpawner.ChildProcessSpawner with ChildProcess.make(...), HttpClient.HttpClient, Path.Path, Config, Clock, and DateTime over ad hoc platform APIs.
• 🔴 (13:24) User stated concurrent callers should share in-flight computations via Effect.cached rather than manually storing Fiber | undefined or Promise | undefined.
• 🔴 (13:24) User stated native/external callbacks such as @parcel/watcher, node-pty, native fs.watch, and plugin callbacks should use EffectBridge when re-entering Effect services with instance/workspace context; plain async code should pass explicit context or remain inside an Effect fiber rather than using ambient instance-context shims.