Distillation

Date: Sep 14, 2026

• 🔴 (23:21) User directed that AI cassettes always replay by default. Intentional recording requires RECORD=true, the listed provider credentials, and CI unset; CI forces replay. Cassettes must remain pretty-printed JSON because compact output makes multi-interaction changes difficult to audit.
• 🔴 [enforced-workflow] (23:21) User requires evidence-driven, safety-first workflows for correctness-critical changes: inspect exact repository state, authoritative local source, architecture, and lifecycle boundaries first; preserve unrelated work; avoid mutations during research or frozen reviews; prove defects with deterministic failing-first tests exercising real preconditions and observable behavior; verify fixes with package-scoped tests, typecheck, lint, format, and relevant smoke tests.
• 🔴 [enforced-workflow] (23:21) User requires uncertain provider calls, tool side effects, interrupted execution, and ownership to be treated as unknown rather than silently retried or replayed. User prefers durable state, explicit typed boundaries, real integrations, controlled asynchronous sequencing, cleanup, and idempotence/concurrency coverage over mocks or assumptions.
• 🔴 [requested-review] (23:21) User requires independent correctness and security reviews with precise file-and-line evidence, inspection of every changed file, exact blocker reporting, and an explicit merge/no-merge verdict.
• 🔴 (23:21) User requires unknown values to be validated exactly once at their owning boundary and then passed inward as typed values; revalidation is rejected because it obscures ownership and creates inconsistent failures.
• 🔴 (23:21) User requires synchronous parsing to remain synchronous. For untrusted JSON strings, use Schema.UnknownFromJsonString with Schema.decodeUnknownOption rather than manual JSON.parse wrapped in Effect.try.
• 🔴 (23:21) User requires scheduled or repeating Effect background work to use Effect.repeat or Effect.schedule, forked via Effect.forkScoped inside the owning layer definition. Ad hoc promises and handler-started loops are rejected because they escape layer lifetime and cleanup; layer-scoped fibers preserve process-global ownership and deterministic shutdown.
• 🔴 (23:21) User requires the checkout’s Effect v4 / effect-smol source to be treated as authoritative rather than memory or Effect v2/v3 examples. If .opencode/references/effect-smol is absent, clone https://github.com/Effect-TS/effect-smol there and inspect nearby source and tests.
• 🔴 (23:21) User chose Effect.gen(function* () {}) for multi-step workflows and named Effect.fn/Effect.fnUntraced for reusable methods over ad hoc Promise chains because they preserve typed composition, tracing, and house style.
• 🔴 (23:21) User requires snake_case Drizzle schema field names so SQL columns do not need repeated string-name overrides. Camel-case TypeScript properties are rejected because they duplicate database mapping and make schema definitions less direct.
• 🔴 (23:21) User requires every Effect-version plugin domain to extend its corresponding API client interface from @opencode/client/effect/api, never redefine inherited functions, and add only operations meaningful in plugin context. Parallel bespoke interfaces are rejected because they duplicate contracts and permit Promise, Effect, and generated-client surfaces to drift.
• 🔴 (23:21) V2 PluginModule.load() requires one default { id, setup } or { id, effect } definition. Configured local targets must be directories with discoverable server or index entrypoints; standalone files work only through auto-discovery. Exporting a legacy async plugin function is not sufficient despite compatibility with older OpenCode loaders.
• 🔴 (23:21) bun-pty@0.4.10 can pass Bun typechecks and smoke tests but is not Node SEA-compatible because its runtime main is src/index.ts; Node SEA refuses TypeScript stripping inside node_modules with ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING. The stated fix is to use the script(1) process adapter or another compiled Node-safe PTY API; @opencode-ai/pty is not an in-process replacement because it exports only binaryPath.
• 🔴 (23:21) A git push to a fork such as BYK/opencode can fail with failed to push some refs and Volta’s Node is not available because the husky pre-push hook runs turbo typecheck (tsgo -b) in a shell whose PATH cannot resolve Volta’s Node shim, causing exit code 126. The fix is to prepend the real Volta Node bin directory to PATH; the pre-push hook then completes all turbo tasks successfully or from cache and the push proceeds.
• 🔴 (23:21) OpenCode auto-discovers project icons by globbing **/favicon.{ico,png,svg,jpg,jpeg,webp} in the worktree, selecting the shortest path, base64-encoding it, and storing it in icon.url. Discovery runs once on first load and is skipped when icon.override or icon.url exists; the OpenCode repository has a hardcoded fallback. For existing projects, force discovery by editing through the dialog or clearing cached layout data; for new projects, place favicon.svg at the repository root before first open.
• 🔴 (23:21) packages/core/schema.json remains schema version "7" with dialect "sqlite", but its schema ID changed from f14a9b18-8207-487e-a3d3-227e629ba9ad to 57591e35-6f8f-4cda-932c-6a08e85caae7.
• 🔴 (23:21) The packages/core/schema.json diff adds schema entities for tables session_execution and session_recovery, including a session_execution_pk primary-key entry and additional foreign-key/index metadata involving session_id.