Distillation

Date: Sep 9, 2026

• 🔴 (10:24) /home/byk/Code/opencode-lore/packages/gateway/test/shutdown-sqlite-readers.test.ts is a 342-line regression suite for issue #1599: graceful gateway shutdown must close vector/read worker-pool SQLite readers before writer close, and core close() must run exactly once on the normal path.
• 🔴 (10:24) Issue #1599 root cause: SQLite WAL TRUNCATE requires zero concurrent readers, but each vector worker holds a read-mark through reader.db; the pre-#1599 synchronous shutdownVectorPool() posted shutdown and terminate() in the same tick without awaiting, allowing readers to outlive writer close and causing a busy checkpoint, busy-timeout hang, stranded -wal, and recovery on the next boot.
• 🔴 (10:24) The required gateway shutdown order is exactly: 1. stopTemporalEmbeddingScheduler, 2. settleTemporalEmbeddingScheduler with a finite positive deadline, 3. settleDocumentEmbeds, 4. resetProvider, 5. shutdownVectorPoolAsync, 6. core close.
• 🔴 (10:24) Gateway shutdown must handle vector-pool variants with no workers, healthy workers, and a stuck worker. If a worker never acks shutdown, the helper must still resolve within its deadline so bounded shutdown can proceed to writer close.
• 🔴 (10:24) Core close() must run exactly once on the graceful path: zero calls leave WAL uncheckpointed, while two calls indicate a logic bug or leaked cleanup hook.
• 🔴 (10:24) Core close() is idempotent and must be a true no-op when the DB was never opened (does not open it); repeated calls after gateway shutdown must not throw or close an already-closed handle again.
• 🔴 (10:24) A core close() failure, such as Error("checkpoint busy"), must never propagate and block the forced-exit path; the gateway shutdown closure catches the error and still resolves successfully.
• 🔴 (10:24) The issue #1599 lifecycle regression test sets LORE_DB_PATH to a temporary lore.db, writes shutdown_canary(id="canary-1", payload="before-shutdown"), shuts down, reopens through a fresh DatabaseSync, requires PRAGMA integrity_check to return "ok", and verifies the accepted write remains readable.
• 🔴 (10:24) /home/byk/Code/opencode-lore/packages/gateway/test/shutdown-sqlite-readers.test.ts snapshots and restores the process-start LORE_DB_PATH, closes any opened DB before deleting temporary directories for Windows file-lock compatibility, and uses best-effort cleanup.
• 🔴 (10:24) Claude Code billing-header logic in /home/byk/Code/opencode-lore/packages/gateway/test/cch.test.ts relies on the real header being always system[0] and nothing serializing before it; tests also warn when a sentinel-shaped block serializes before the real header in both signBody and resignBody.
• 🔴 (10:24) /home/byk/Code/opencode-lore/packages/gateway/test/lifecycle-lock.test.ts tests acquireLifecycleLock, withLifecycleLock, LifecycleLockBusyError, LifecycleLockLostError, uninstall tombstones, verified package invocation, and stableUnixProcessIdentity.
• 🔴 (10:24) Lifecycle locks use an owner-only generation record at owner.json with version, 43-character token, pid, operation, createdAt, processStartedAt, and processIdentity; Unix permissions are 0o700 for parent/lock directories and 0o600 for owner.json, and release removes only the releasing generation.
• 🔴 (10:24) stableUnixProcessIdentity distinguishes same-second Unix PID generations using procfs boot ID plus start ticks, producing values such as unix-procfs:boot-generation:10001 and unix-procfs:boot-generation:10002; lstart-only second-resolution metadata is rejected with null.
• 🔴 (10:24) Lifecycle-lock SIGKILL tests invoke /home/byk/Code/opencode-lore/packages/gateway/test/lifecycle-lock-sigkill-child.ts using process.execPath --import tsx, with phases crash-initialize, crash-recovery, crash-release, and acquire-release, and a 90_000 ms child timeout.
• 🔴 (10:24) Non-Windows lifecycle-lock recovery must survive SIGKILL between lock-directory creation and owner publication, SIGKILL between owner removal and directory removal, and a second SIGKILL during incomplete-generation recovery.
• 🔴 (10:24) Lifecycle-lock recovery may reclaim only an empty directory backed by a dead initialization generation; an ambiguous empty directory, a live initializer’s directory, or a replacement directory targeted by a delayed release claim must remain busy and must not be stolen.
• 🔴 (10:25) Effect-specific work must use the current Effect v4 / effect-smol source rather than memory or Effect v2/v3 examples. If .opencode/references/effect-smol is absent, clone https://github.com/Effect-TS/effect-smol into the project, then search it and nearby repository code for exact APIs and local style before answering or implementing.
• 🔴 (10:25) Effect workflows should use Effect.gen(function* () { ... }); reusable service methods or important workflows should use Effect.fn("Name") or Effect.fnUntraced(...).
• 🔴 (10:25) Effect API/domain modeling should prefer Schema, branded schemas for IDs, and Schema.TaggedErrorClass for typed domain errors. HTTP handlers should remain thin—decode input, read request context, call services, and map transport errors—while business rules belong in services.
• 🔴 (10:25) Effect service code should prefer Effect-aware platform abstractions where surrounding code does, keep layer composition and dependency provisioning explicit, and avoid any, non-null assertions, unchecked casts, old Effect APIs, and broad hidden provisioning.
• 🔴 [enforced-workflow] (10:25) Effect tests should use testEffect(...) from packages/opencode/test/lib/effect.ts for services, layers, runtime context, scoped resources, or platform integrations; use it.live(...) for filesystem, git, child processes, locks, timing, HTTP servers, sockets, and other live platform behavior.
• 🔴 [enforced-workflow] (10:25) Run package tests from package directories such as packages/opencode; never run package tests from the repo root.
• 🔴 (10:25) Effect tests should use explicit test layers and scoped fixtures/finalizers for temporary directories, flags, databases, fibers, servers, and global state rather than ad hoc managed runtimes.
• 🔴 (10:25) /home/byk/Code/opencode/packages/plugin/src/v2/effect/plugin.ts defines Plugin<R = Scope.Scope> with readonly id: string and effect: (context: PluginContext) => Effect.Effect<void, never, R>; define<R = Scope.Scope>(plugin: Plugin<R>) returns the plugin unchanged.
• 🔴 (10:25) /home/byk/Code/opencode/packages/plugin/src/v2/effect/plugin.ts defines PluginDomain with readonly add: (plugin: Plugin) => Effect.Effect<void> and remove: (id: string) => Effect.Effect<void>.
• 🔴 (10:25) /home/byk/Code/opencode-lore/packages/gateway/test/start-gateway-reuse.test.ts verifies authenticated gateway reuse: a second startGateway handle has owned: false, reuses the existing port and exact managementToken, and avoids EADDRINUSE.
• 🔴 (10:25) Gateway reuse authenticates an owned gateway even on forbidden port 6669: unauthenticated health remains "healthy", a wrong token yields { kind: "rejected" }, the correct token yields { kind: "authenticated", identity: { pid: process.pid } }, and reuse returns owned: false on port 6669.
• 🔴 (10:25) Gateway probes preserve Fetch transport for non-loopback URLs such as https://gateway.example.test/health; loopback probes use bounded behavior and classify a hanging HTTP server with a 10 ms deadline as "timeout".
• 🔴 (10:25) With no explicit port, gateway startup reuses an authenticated process record’s random port, including test port 49152, its management token, and the authenticated host; it can also reuse an existing gateway when the requested interface does not overlap, normalizing to the authenticated host.
• 🔴 (10:25) A public /health response claiming { status: "ok", service: "lore" } is insufficient proof of identity; a spoofing HTTP service and a non-HTTP foreign process both produce a friendly error matching not an authenticated lore gateway.
• 🔴 (10:25) If process-record publication fails after writing state, startGateway removes both port and PID records. If listener cleanup itself fails, it retains discovery evidence instead, reports that evidence was retained, and does not call record-removal hooks.
• 🔴 (10:25) Concurrent startGateway calls are serialized through process-record publication: after a stale owner probe is released, the first caller owns the new gateway and the second reuses its port and management token with owned: false.
• 🔴 (10:25) A successor gateway start must wait until predecessor shutdown removes its process records; all successor record reads occur after removal, and the successor then starts with owned: true.
• 🔴 (10:26) /home/byk/Code/opencode/packages/core/test/plugin/provider-openai-compatible.test.ts verifies the OpenAI-compatible plugin sets options.includeUsage to true, uses provider ID custom-provider to produce language-model provider "custom-provider.chat", and does not overwrite an SDK sentinel installed by an earlier provider-specific plugin.