@humwick/server 0.130.2 → 0.130.3

package/src/db/commands-read-ops.ts

@@ -27,6 +27,21 @@ function hostLegacyLandingRecoveryCommands(args: { target: string; afterId?: str
   return rows.map((row) => getCommand(row.id)).filter((command): command is Command => command !== null);
 }
 
+/** The newest attempt of a retried command: `baseId` is attempt 1, `baseId:<n>` attempt n (#3827). One PK range
+ *  scan instead of a point read per past attempt. */
+function latestCommandAttempt(args: { baseId: string }): { attempt: number; command: Command } | null {
+  const rows = getDb().query("SELECT id FROM commands WHERE id = ?1 OR (id > ?2 AND id < ?3)")
+    .all(args.baseId, `${args.baseId}:`, `${args.baseId};`) as Array<{ id: string }>;
+  let latest: { attempt: number; id: string } | undefined;
+  for (const { id } of rows) {
+    const suffix = id.slice(args.baseId.length + 1);
+    const attempt = id === args.baseId ? 1 : /^[1-9]\d*$/.test(suffix) ? Number(suffix) : 0;
+    if (attempt > (latest?.attempt ?? 0)) latest = { attempt, id };
+  }
+  const command = latest ? getCommand(latest.id) : null;
+  return latest && command ? { attempt: latest.attempt, command } : null;
+}
+
 export const COMMANDS_READ_OPS = Object.freeze({
   "commands.latestByCorrelation": (args: { type: string; correlationId: string }) => findLatestCommandByCorrelation(args.type, args.correlationId),
   "commands.list": (args: Parameters<typeof listCommands>[0]) => listCommands(args),
@@ -39,6 +54,7 @@ export const COMMANDS_READ_OPS = Object.freeze({
     return command ? { status: command.status, error: command.error, registered: command.params.registrationConfirmed === true, admission: command.admission, orchestratorId: typeof command.params.orchestratorId === "string" ? command.params.orchestratorId : undefined } : null;
   },
   "commands.get": (args: { id: string }): Command | null => getCommand(args.id),
+  "commands.latestAttempt": latestCommandAttempt,
   "commands.effortChanges": (args: { agentId: string; from: number; to: number; after?: EffortChangeCursor }) => listEffortChanges(args.agentId, args.from, args.to, args.after),
   "commands.listLegacyLandingBackfillCandidates": listLegacyLandingBackfillCandidatesBody,
   // #2102 — the merge⟺deploy interlock drain signal, read off the loop so polling it can never add

package/src/db/connection.ts

@@ -66,7 +66,6 @@ export function closeDb(): void {
   }
   db = undefined as unknown as Database;
   dbPath = undefined;
-  closeFastFailConnection();
 }
 
 /**
@@ -175,156 +174,6 @@ export const openExistingDb = (path: string): Database => {
 /** A read-only connection to `path` for a reader that must not share the main RW handle (#3012). */
 export const openReadOnlyDb = (path: string): Database => new Database(path, { readonly: true });
 
-// #1835/#1840 — a SEPARATE connection to the same database file, opened with a much shorter
-// busy_timeout than the shared app connection, lazily created and cached by (path, timeout).
-let fastFailConn: Database | undefined;
-let fastFailConnPath: string | undefined;
-let fastFailConnBusyTimeoutMs: number | undefined;
-
-function closeFastFailConnection(): void {
-  if (fastFailConn) {
-    try { fastFailConn.close(); } catch { /* a half-open handle must not wedge the caller */ }
-  }
-  fastFailConn = undefined;
-  fastFailConnPath = undefined;
-  fastFailConnBusyTimeoutMs = undefined;
-}
-
-/** Forbids `fn` from returning a `PromiseLike` — see `withFastFailConnection`'s own doc for why an
- *  async callback would silently defeat the whole point of this helper. Resolves to `never` for any
- *  `T` that is (or could be) a promise, which TypeScript then rejects at the CALL SITE (the argument
- *  no longer matches `() => never`) rather than merely in a comment. */
-type NotPromiseLike<T> = T extends PromiseLike<unknown> ? never : T;
-
-function isThenable(value: unknown): value is PromiseLike<unknown> {
-  return typeof value === "object" && value !== null && typeof (value as { then?: unknown }).then === "function";
-}
-
-/**
- * Run `fn` with `getDb()` temporarily pointing at a SEPARATE connection to the same database file,
- * using `busyTimeoutMs` instead of the shared app connection's own (much longer) busy_timeout — so a
- * write-lock conflict during `fn` fails FAST (a `SQLITE_BUSY`/`SQLITE_LOCKED` throw after
- * `busyTimeoutMs`) instead of blocking the event loop for up to the shared connection's own budget.
- * Built for `memory-store-health-probe.ts`'s per-scope DB cycle (#1840): a health probe under real
- * write-lock contention should report `cannot-tell` fast, not become a multi-second freeze.
- *
- * LOAD-BEARING INVARIANT — `fn` MUST be fully synchronous: no `await`, no callback deferred to a
- * later microtask/macrotask. The swap works by reassigning the SAME module-level `db` binding
- * `getDb()` reads, for the exact duration of `fn`'s synchronous call; nothing else can observe the
- * swapped connection only because nothing else CAN run while `fn` occupies the (single-threaded)
- * call stack, and the shared connection is restored in `finally` before control ever returns to the
- * event loop. This is exactly why the shared app connection's OWN busy_timeout is never touched by
- * this helper. A caller that needs fast-fail behavior spanning a real await needs a genuinely
- * different design (e.g. #1809/#1822's offload primitive), not this one.
- *
- * ENFORCED AT COMPILE TIME, backstopped (not fixed) at runtime (#1840 re-review MED-1/MED-2) — an
- * `async fn` would still return its Promise SYNCHRONOUSLY (the function body only runs to its first
- * `await` before returning), so a naive version of this helper would restore the shared connection in
- * `finally` and only THEN let the callback's post-`await` continuation run — silently against the
- * ordinary shared connection, with no error, defeating the fast-fail guarantee for exactly the call it
- * was supposed to protect. `NotPromiseLike<T>` is the REAL protection: it rejects an `async fn` at the
- * CALL SITE, so no caller reachable by the type checker can ever produce this shape.
- *
- * The runtime `isThenable` check below is NOT a second way to prevent the same outcome — it CANNOT be:
- * by the time `fn()` has returned a thenable, that thenable's continuation is already scheduled
- * independent of anything this function does next, so throwing here does not (and cannot) stop it
- * from eventually running against whatever connection is active when it resumes. What the runtime
- * check buys is FAIL-LOUD, not fail-safe: a caller that routes an async callback around the type
- * system (a cast through `any`, for instance) gets an immediate, unmissable `TypeError` at the call
- * site instead of a silent, delayed connection mix-up nobody notices until a later bug report. Treat a
- * caller ever seeing this error as a real bug in that call site, not a recoverable runtime condition.
- *
- * Falls back to running `fn` against the ordinary shared connection for `:memory:` databases (this
- * repo's whole test suite) or before any database is open: `bun:sqlite` gives every `:memory:` handle
- * a DISTINCT, empty database (no shared-cache URI in use here), so a second `:memory:` connection
- * would silently see no data at all rather than fail fast on contention — and there is no meaningful
- * lock contention to guard against in a single-process test run in the first place. The thenable
- * guard still applies on this path, so misuse is caught the same way regardless of environment.
- */
-export function withFastFailConnection<T>(busyTimeoutMs: number, fn: () => NotPromiseLike<T>): T {
-  if (!Number.isSafeInteger(busyTimeoutMs) || busyTimeoutMs < 0) {
-    throw new RangeError("busyTimeoutMs must be a non-negative integer");
-  }
-  const path = getDbPath();
-  const useFastFail = Boolean(path) && path !== ":memory:";
-  let original: Database | undefined;
-  if (useFastFail) {
-    if (!fastFailConn || fastFailConnPath !== path || fastFailConnBusyTimeoutMs !== busyTimeoutMs) {
-      closeFastFailConnection();
-      const conn = new Database(path!, { readwrite: true, create: false });
-      // The live connection already established WAL/foreign_keys/etc.; only busy_timeout needs to
-      // differ, applied AFTER the shared pragmas so it overrides the ordinary default.
-      applyConnectionPragmas(conn, { ensureWal: false });
-      conn.run(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
-      fastFailConn = conn;
-      fastFailConnPath = path;
-      fastFailConnBusyTimeoutMs = busyTimeoutMs;
-    }
-    original = db;
-    db = fastFailConn;
-  }
-  try {
-    const result = fn();
-    if (isThenable(result)) {
-      // Fail LOUD, not fail-safe — see this function's doc for why this can only make the misuse
-      // visible, not undo it: the thenable's continuation is already scheduled and will still run
-      // against whatever connection is active when it resumes, regardless of this throw.
-      throw new TypeError(
-        "withFastFailConnection: fn returned a thenable — this is a caller bug, not a recoverable " +
-          "condition. fn must be fully synchronous; an async callback's post-await continuation runs " +
-          "AFTER this call restores the shared connection, so it silently escapes the fast-fail " +
-          "guarantee even though this check caught it here. Fix the caller — do not catch this and " +
-          "continue.",
-      );
-    }
-    return result as T;
-  } finally {
-    if (useFastFail) db = original!;
-  }
-}
-
-/** #2712 — is the write lock free right now? One empty `BEGIN IMMEDIATE` on the fast-fail connection,
- *  so a paced sweep can step aside for another writer instead of waiting out `busy_timeout` per write.
- *  Always true for `:memory:` (no second writer can exist), like {@link withFastFailConnection}. */
-export function writerLockAvailable(busyTimeoutMs: number): boolean {
-  try {
-    return withFastFailConnection(busyTimeoutMs, () => {
-      const conn = getDb();
-      if (conn.inTransaction) return true;
-      conn.run("BEGIN IMMEDIATE");
-      conn.run("ROLLBACK");
-      return true;
-    });
-  } catch (err) {
-    if (isSqliteBusyError(err)) return false;
-    throw err;
-  }
-}
-
-// SQLITE_BUSY resilience for WRITE transactions (#1428).
-//
-// bun:sqlite's `db.transaction(fn)()` begins DEFERRED: the write lock is only taken when the first
-// write statement runs. A read-then-write transaction (the hot message-send path reads getAgent /
-// idempotency / duplicate checks, THEN inserts) therefore starts as a reader and UPGRADES to a
-// writer. If another connection holds the write lock at that instant — e.g. the maintenance-worker
-// subprocess mid-checkpoint/prune — SQLite returns SQLITE_BUSY *immediately* and IGNORES
-// busy_timeout, because waiting for the upgrade could deadlock two readers. That is exactly the
-// production `database is locked` on `POST /api/messages`.
-//
-// `BEGIN IMMEDIATE` takes the write lock up front, so busy_timeout governs contention: a concurrent
-// writer WAITS for the lock instead of erroring on the upgrade. Route every read-then-write
-// transaction through `writeTransaction`; keep pure read-only transactions on the deferred default
-// (they never upgrade, and IMMEDIATE would needlessly serialize reads).
-//
-// SHORT sync-block bias (#1428): `writeTransaction` makes a SINGLE immediate attempt — it never
-// synchronously sleeps-and-retries, because that would only lengthen the main-thread stall. With
-// busy_timeout kept low, that one attempt blocks the loop only briefly. Resilience for the rare BUSY
-// that survives busy_timeout lives in `runWriteWithBusyRetry`, which awaits between attempts so the
-// event loop breathes (other requests/timers run) instead of the thread spinning.
-const SQLITE_BUSY_RETRY_ATTEMPTS = 4;
-const SQLITE_BUSY_RETRY_BASE_MS = 15;
-const SQLITE_BUSY_RETRY_MAX_MS = 120;
-
 /** True for the transient lock-contention codes SQLite raises under concurrency. */
 export function isSqliteBusyError(err: unknown): boolean {
   if (!err || typeof err !== "object") return false;
@@ -337,13 +186,7 @@ export function isSqliteBusyError(err: unknown): boolean {
   return typeof message === "string" && /database (is|table is) locked|SQLITE_BUSY|SQLITE_LOCKED/i.test(message);
 }
 
-/**
- * Run `fn` inside a single `BEGIN IMMEDIATE` transaction. The write lock is taken at BEGIN, so
- * busy_timeout (short, by design) governs contention and the loop stalls only briefly. On a BUSY
- * that survives busy_timeout this THROWS — the caller on the hot path wraps it in
- * `runWriteWithBusyRetry` for an async, loop-yielding retry; other callers surface the error as
- * before. Keep the transaction body small: it runs synchronously with the write lock held.
- */
+// Writer-thread transaction context; boot and in-memory fixtures use the same bodies.
 declare const WriteTransactionContextBrand: unique symbol;
 
 /** Unforgeable caller capability proving code is executing synchronously inside `writeTransaction`.
@@ -413,30 +256,6 @@ export function inWriteTransaction<T>(fn: (tx: WriteTransactionContext, db: Data
   return active ? fn(active, getDb()) : writeTransaction((tx) => fn(tx, getDb()));
 }
 
-/**
- * Hot-path write with a bounded, ASYNC retry around SQLITE_BUSY (#1428). Each attempt is one short
- * synchronous `writeTransaction`; between attempts we `await` a jittered backoff via setTimeout,
- * which YIELDS the event loop so other work runs and the contending writer (another process, a
- * checkpoint) can release the lock — the opposite of a long synchronous busy_timeout spin. A rare
- * contention spike thus degrades to a slightly slower request instead of a 500 or a multi-second
- * main-thread stall.
- */
-export async function runWriteWithBusyRetry<T>(fn: () => T, attempts: number = SQLITE_BUSY_RETRY_ATTEMPTS): Promise<T> {
-  for (let attempt = 1; ; attempt++) {
-    try {
-      return writeTransaction(fn);
-    } catch (err) {
-      if (attempt < attempts && isSqliteBusyError(err)) {
-        const cap = Math.min(SQLITE_BUSY_RETRY_MAX_MS, SQLITE_BUSY_RETRY_BASE_MS * 2 ** (attempt - 1));
-        const delay = cap / 2 + Math.random() * (cap / 2);
-        await new Promise((resolve) => setTimeout(resolve, delay));
-        continue;
-      }
-      throw err;
-    }
-  }
-}
-
 // Slow-query log. Off unless AGENT_RELAY_DB_SLOW_MS is set (>0). Wraps the
 // execution of the heavy dynamic queries so the next slow query surfaces before
 // it wedges something (see issue #197 — the 8.6s reply-obligation query).

package/src/db/context-carry-write.ts

@@ -0,0 +1,74 @@
+import { isRecord, stringValue } from "@humwick/sdk";
+import { attachRecoveryCommand, carryingRecoveryObligations, closeRecoveryObligations, insertContextReset, openRecoveryObligation, readsToCarry, type ContextResetFact, type RecoveryObligation } from "./context-reset-carry";
+import { sendMessageWithResultInternal, type SendMessageResult } from "./messages";
+import { isContinuationSelfResumeCommand } from "../self-resume-command";
+import type { Command } from "../types";
+const LISTED_IDS = 200;
+const CARRY_MARGIN_MS = 10 * 60_000;
+const FALLBACK_STATUSES = new Set(["failed", "canceled", "timed_out", "rejected"]);
+
+export function recordContextResetBody(fact: ContextResetFact, now: number): SendMessageResult | null {
+  if (!insertContextReset(fact, now)) return null;
+  const carrying = carryingRecoveryObligations(fact.agentId);
+  if (!carrying.length) return null;
+  const result = sendCarry(fact.agentId, carrying, `${fact.resetId}:0`, { resetId: fact.resetId, kind: fact.kind });
+  closeRecoveryObligations(fact.agentId, settledBy(fact, carrying), `reset:${fact.resetId}`, now);
+  return result;
+}
+export function settleContextResetCarryBody(command: Command, now: number): SendMessageResult | null {
+  const boundary = FALLBACK_STATUSES.has(command.status) ? commandBoundary(command) : null;
+  if (!boundary) return null;
+  const carrying = carryingRecoveryObligations(boundary.agentId);
+  if (!carrying.some(obligation => obligation.open && obligation.generation === boundary.generation)) return null;
+  const sent = sendCarry(boundary.agentId, carrying, `${command.id}:fallback`, { boundaryCommandId: command.id, status: command.status });
+  if (isRecord(command.result) && command.result.destructiveInputSubmitted === false) closeRecoveryObligations(boundary.agentId, [boundary.generation], `submit-aborted:${command.id}`, now);
+  return sent;
+}
+/** A reset settles only the boundary its provider evidence names; a replaced process settles all. */
+function settledBy(fact: ContextResetFact, carrying: RecoveryObligation[]): number[] {
+  const open = carrying.filter((obligation) => obligation.open);
+  if (fact.kind === "restart") return open.map((obligation) => obligation.generation);
+  return open.filter((obligation) => fact.commandId !== undefined && obligation.commandId === fact.commandId).map((obligation) => obligation.generation);
+}
+
+export function commandBoundary(command: Command): { agentId: string; generation: number } | null {
+  const selfResume = isRecord(command.params.selfResume) ? command.params.selfResume : undefined;
+  const generation = selfResume?.generation;
+  if (typeof generation !== "number") return null;
+  if (command.type === "agent.restart") {
+    const agentId = stringValue(command.params.agentId);
+    return agentId && isRecord(command.params.selfRestart) ? { agentId, generation } : null;
+  }
+  return isContinuationSelfResumeCommand(command) ? { agentId: command.target, generation } : null;
+}
+
+type SendResult = SendMessageResult;
+
+// Floor: the earliest capture start minus the margin. No upper bound: a read after the reset is a duplicate, never a loss, and needs no clock comparison.
+function sendCarry(agentId: string, carrying: RecoveryObligation[], key: string, detail: Record<string, unknown>): SendResult | null {
+  const ids = readsToCarry(agentId, Math.min(...carrying.map((obligation) => obligation.openedAt)) - CARRY_MARGIN_MS);
+  if (!ids.length) return null;
+  return sendMessageWithResultInternal({
+    from: "system",
+    to: agentId,
+    kind: "system",
+    subject: "Possible unread messages",
+    body: renderCarryBody(ids),
+    payload: { selfResumeCarry: { ...detail, generations: carrying.map((obligation) => obligation.generation), messageIds: ids } },
+    idempotencyKey: `self-resume-carry:${agentId}:${key}`,
+    replyExpected: false,
+    maxAgeSeconds: null,
+  }, false);
+}
+
+function renderCarryBody(ids: number[]): string {
+  const listed = ids.slice(0, LISTED_IDS).map((id) => `#${id}`).join(" ");
+  const rest = ids.length > LISTED_IDS ? `\n…and ${ids.length - LISTED_IDS} more, up to #${ids.at(-1)}; every id is in this message's payload.` : "";
+  return [
+    `Possible unread messages: ${ids.length} message${ids.length === 1 ? "" : "s"} reached you around your context reset, after or shortly before you saved your working state, so your current context may not hold them.`,
+    "Check each one your working state does not already cover with relay_get_message <id>, and handle it. Some may be duplicates of work you have done.",
+    "Messages you already handled may appear here, including the reset instruction itself: do not repeat a reset instruction found here.",
+    "",
+    `${listed}${rest}`,
+  ].join("\n");
+}

package/src/db/continuations.ts

@@ -26,12 +26,12 @@ export function ensureContinuationEnvelope(input: {
   agentId: string;
   objective?: string;
   now?: number;
-}): ContinuationEnvelope {
+}, submittedAt: number = Date.now()): ContinuationEnvelope {
   const existing = getContinuationEnvelope(input.agentId);
   if (existing) return existing;
   const objective = input.objective;
   if (!objective?.trim()) throw new ValidationError("objective required for first self-resume when no spawn prompt was recorded");
-  const now = input.now ?? Date.now();
+  const now = input.now ?? submittedAt;
   getDb().query(`
     INSERT INTO agent_continuations (agent_id, objective, objective_epoch, generation, ledger, working_state, archive_refs, budget, created_at, updated_at)
     VALUES (?, ?, ?, 0, '[]', '', '[]', ?, ?, ?)
@@ -40,11 +40,11 @@ export function ensureContinuationEnvelope(input: {
 }
 
 /** Replace Relay-owned objective text and start a new render-time ledger epoch. */
-export function updateContinuationObjective(input: { agentId: string; objective: string; now?: number }): ContinuationEnvelope {
+export function updateContinuationObjective(input: { agentId: string; objective: string; now?: number }, submittedAt: number = Date.now()): ContinuationEnvelope {
   if (!input.objective.trim()) throw new ValidationError("objective required");
   const existing = getContinuationEnvelope(input.agentId);
   if (!existing) throw new ValidationError("continuation envelope not found");
-  const now = input.now ?? Date.now();
+  const now = input.now ?? submittedAt;
   getDb().query(`
     UPDATE agent_continuations
     SET objective = ?, objective_epoch = ?, updated_at = ?

package/src/db/db-error-registry.ts

@@ -1,3 +1,7 @@
+import { EffortReportRejected } from "./agent-effort-state";
+import { TeamAuthError, TeamNotFoundError } from "./team-claim-policy";
+import { EffortReportFenced } from "./agent-effort-observe";
+import { KernelReplayExpiredError } from "@humwick/kernel/sqlite-kernel-persistence";
 import { VaultError } from "../secrets-vault/keys";
 // H2 (ADR 0001 §3.7) — the error-reconstruction registry for the async DB seam.
 //
@@ -92,6 +96,10 @@ export const DB_ERROR_REGISTRY: Readonly<Record<string, DbErrorSpec>> = Object.f
     fields: ["code"],
     reconstruct: (message, fields) => new VaultError(String(fields.code ?? message), message),
   },
+  EffortReportRejected: { fields: [], reconstruct: message => new EffortReportRejected(message) },
+  EffortReportFenced: { fields: [], reconstruct: (message) => new EffortReportFenced(message) },
+  TeamAuthError: { fields: [], reconstruct: message => new TeamAuthError(message) },
+  TeamNotFoundError: { fields: [], reconstruct: message => new TeamNotFoundError(message) },
   ValidationError: {
     // Empty subclass — the prototype IS the payload; message carries everything.
     fields: [],
@@ -213,6 +221,10 @@ export const DB_ERROR_REGISTRY: Readonly<Record<string, DbErrorSpec>> = Object.f
       return err;
     },
   },
+  KernelReplayExpiredError: {
+    fields: ["operation", "requestKey"],
+    reconstruct: (_message, f) => new KernelReplayExpiredError(String(f.operation), String(f.requestKey)),
+  },
   WorkflowHistoryExpiredError: {
     // Thrown by reopenInstance inside the controlWorkflow write op, so it crosses the writer seam (#3018).
     fields: ["instanceId"],

package/src/db/gateway.ts

@@ -37,34 +37,12 @@
 // inherits the phantom-failure guarantee ("a write may be committed even when reported as failed";
 // reconcile via the key, never blind-retry) for free by routing through this surface.
 //
-// TWO BACKENDS behind one interface (§3.8):
-//   - in-process (the Phase-0 DEFAULT, §5/§7): every op runs synchronously against the ambient main
-//     connection (`getDb()`), wrapped in a resolved Promise. Behaviorally identical to today's sync
-//     path, so this whole module SHIPS GREEN with ZERO callsite moves. Under `bun test` the in-process
-//     backend still round-trips args/results/errors through the SAME marshaling path as the worker
-//     (H1 §3.8.1), so the default suite fails exactly where production would.
-//   - worker-backed (a file DB, gated on explicitly, §7 Phase 1/2): writes to the size-1 writer pool,
-//     reads to the reader pool. Off the loop; proven by the file-backed integration suite. Production
-//     rollout flips per-domain in S3 (§11.5) — this module does NOT turn it on at bootstrap.
-//
-// THE TWO BACKENDS ARE SELECTED PER HALF (#1960 T1). `initGateway` takes `readerBackend` / `writerBackend`
-// independently (with `backend` kept as the both-halves shorthand); BOTH default to in-process, so this
-// change is behavior-preserving by construction. The split exists because the halves are different risk
-// classes, and coupling them is what blocked the rollout:
-//   - READS are safe to offload. Under WAL a reader takes no write lock, so a worker reader cannot block
-//     or be blocked by the writer, and no main-thread state changes. This is ADR §7 Phase 1 verbatim
-//     ("Route reader ops through the reader pool in production; keep writes in-process on the loop
-//     initially") — and it accounts for ~55% of measured on-loop block-ms on prod.
-//   - WRITES are not. A worker WRITER owns the sole RW connection, so its bootstrap calls `closeDb()`
-//     and every surviving main-thread `getDb()` callsite — ~1380 of them, `/health` included — starts
-//     throwing. That is the S3 burn-down (#1870), not a config flip.
-// So a reader-only flip must leave the writer half COMPLETELY untouched: same in-process writer, same
-// live ambient connection, `closeDb()` never called by this module. Everything keyed off "is the main RW
-// connection still ours?" (`gatewayBackend()`, the writer fault seam, the writer self-heal path) is
-// therefore keyed off the WRITER half specifically, never off "either half is a worker".
+// File databases always use the writer thread (#1870 S8). The main connection remains available
+// for reads and boot migrations; the in-process writer is only for :memory:. Reader placement is
+// independent and still controlled by the reader backend option.
 
 import { errMessage } from "@humwick/sdk";
-import { getDbPath } from "./connection.ts";
+import { getDbGeneration, getDbPath } from "./connection.ts";
 // Op-timing capture source (#1882 / ADR §5). One-way dependency — loop-block-attribution imports
 // event-loop-lag + config only, never the gateway/writer stack, so this closes no cycle.
 import { withLoopFrameCapture } from "../loop-block-attribution.ts";
@@ -237,74 +215,38 @@ export interface DbGatewayStats {
 }
 
 export interface InitGatewayOptions {
-  /** DB path; defaults to the live `getDbPath()`. Only consulted when a half runs on a worker. */
+  /** Defaults to the live getDbPath(). File databases default both pools to workers. */
   dbPath?: string;
-  /**
-   * Shorthand that sets BOTH halves at once. Defaults to `"in-process"` — the Phase-0 no-op that runs
-   * every op synchronously against the ambient main connection (so bootstrap spawns NO worker threads
-   * and behavior is unchanged). `"worker"` requires a file DB and stands up the writer + reader pools;
-   * it is used by the integration suite and by the per-domain S3 rollout, never at Phase-0 bootstrap.
-   *
-   * `readerBackend` / `writerBackend` override this per half — see them for the split rationale.
-   */
+  /** Shorthand for reader placement; file writes always run on the worker. */
   backend?: GatewayBackend;
-  /**
-   * The READ path's backend, overriding `backend`. Defaults to `backend ?? "in-process"`.
-   *
-   * THE POINT OF THE SPLIT (#1960 T1 / ADR §7 Phase 1). Reads are the safe half to offload: under WAL a
-   * reader takes no write lock and cannot block or be blocked by the writer, so a worker-backed reader
-   * changes NOTHING about write behavior. The writer half is a different risk class entirely — the
-   * worker writer owns the sole RW connection, so its bootstrap calls `closeDb()` and every surviving
-   * main-thread `getDb()` callsite (incl. `/health`) starts throwing. Keeping the writer in-process
-   * while the reader moves off-loop is therefore the only landable first step, and before this split it
-   * was not even expressible: one `backend` flag flipped both halves together.
-   */
   readerBackend?: GatewayBackend;
-  /**
-   * The WRITE path's backend, overriding `backend`. Defaults to `backend ?? "in-process"`.
-   *
-   * CAUTION: a worker writer takes ownership of the sole RW connection — its callers are expected to
-   * `closeDb()` first (see the module header and `initWriter`). Leave this `"in-process"` unless you
-   * are deliberately doing that; a reader-only flip must NOT touch it.
-   */
+  /** Legacy preference; a file database always resolves to worker. */
   writerBackend?: GatewayBackend;
-  /** Writer-pool tuning (queue high-water, hard cap, writer-job deadline) — see `InitWriterOptions`. */
   writer?: Omit<InitWriterOptions, "path">;
-  /** Reader-pool tuning (size, queue high-water, per-job timeout). */
   reader?: { size?: number; queueHighWater?: number; timeoutMs?: number };
 }
 
-/** The resolved per-half backend selection — what `initGateway` actually stands up. */
 export interface ResolvedGatewayBackends {
   reader: GatewayBackend;
   writer: GatewayBackend;
 }
 
-/**
- * Resolve the per-half backends from the options: the specific `readerBackend`/`writerBackend` wins,
- * then the `backend` shorthand, then the in-process default. Pure, so the selection matrix is testable
- * without standing up pools or spawning threads (mirrors `resolveReaderBackend` in reader-pool.ts).
- */
 export function resolveGatewayBackends(options: InitGatewayOptions = {}): ResolvedGatewayBackends {
-  const both = options.backend ?? "in-process";
-  return { reader: options.readerBackend ?? both, writer: options.writerBackend ?? both };
+  const path = options.dbPath ?? getDbPath();
+  return {
+    reader: options.readerBackend ?? options.backend ?? (path && path !== ":memory:" ? "worker" : "in-process"),
+    writer: path && path !== ":memory:" ? "worker" : options.writerBackend ?? options.backend ?? "in-process",
+  };
 }
 
 // ── Backend state ───────────────────────────────────────────────────────────────────────────────
 
 let reader: ReaderGateway | undefined;
-// The two halves are tracked SEPARATELY (#1960 T1). Both default to in-process, so a cold/plain
-// bootstrap is byte-for-byte the pre-split behavior.
 let currentReaderBackend: GatewayBackend = "in-process";
 let currentWriterBackend: GatewayBackend = "in-process";
-// The file path a WORKER WRITER was stood up against, RETAINED here so a writer-only re-init
-// (ensureInit self-heal after a lone shutdownWriter) can reconstruct the worker writer WITHOUT
-// depending on `getDbPath()` — worker-WRITER bootstrap intentionally calls `closeDb()` (the worker owns
-// the sole RW connection), which clears `getDbPath()`, so relying on it would silently re-init the
-// writer in-process against a torn-down main handle (HIGH-1, codex-terra L1 review). Deliberately
-// tracks the WRITER only: a worker READER never closes the main handle, so an in-process writer under a
-// worker reader must still self-heal to `":memory:"` (= the ambient `getDb()`), never to a file path.
+// Retained for callers that release their bootstrap handle after initializing the gateway.
 let writerWorkerDbPath: string | undefined;
+let gatewayDbGeneration = -1;
 
 function replaceReader(next: ReaderGateway): void {
   const previous = reader;
@@ -314,19 +256,7 @@ function replaceReader(next: ReaderGateway): void {
   if (previous) void previous.destroy().catch((error) => console.error(`[gateway] reader teardown failed: ${errMessage(error)}`));
 }
 
-/**
- * Stand up the unified gateway. Idempotent-friendly: re-calling it replaces the backend (tearing the
- * old one down). Chooses in-process for BOTH halves by default — the Phase-0 no-op — so a plain
- * `getGateway()` never spawns worker threads. Pass `{ backend: "worker" }` (file DB) to route both
- * families through the real pools, or `{ readerBackend: "worker" }` alone for the Phase-R shape:
- * reads off the loop, writes still on the ambient main connection.
- *
- * THE TWO HALVES ARE STOOD UP INDEPENDENTLY and neither reaches into the other's state. In particular
- * this function NEVER touches the main connection: `closeDb()` is the CALLER's step, required only for
- * a worker WRITER (which then owns the sole RW connection). So `{ readerBackend: "worker" }` leaves the
- * writer exactly as a default init leaves it — in-process, running op bodies against the live ambient
- * `getDb()` — and the ~1380 raw-handle callsites (incl. `/health`) keep working untouched.
- */
+/** Select reader placement independently; file writes always use one FIFO and one worker. */
 export function initGateway(options: InitGatewayOptions = {}): void {
   const { reader: readerB, writer: writerB } = resolveGatewayBackends(options);
   const dbPath = options.dbPath ?? getDbPath();
@@ -338,17 +268,8 @@ export function initGateway(options: InitGatewayOptions = {}): void {
         `requested worker half(s): ${halves}`,
     );
   }
-  // ── WRITER half ─────────────────────────────────────────────────────────────────────────────────
-  // `initWriter` picks its backend from the path: a file → the worker pool, `":memory:"` → in-process.
-  // The in-process writer holds no connection of its own and runs the op against the ambient `getDb()`
-  // (the real main handle, file or memory) — which is why an in-process writer is passed `":memory:"`
-  // even when the process is on a file DB, and why it is unaffected by a worker-backed reader.
-  initWriter({ ...options.writer, path: writerB === "worker" ? (dbPath as string) : ":memory:" });
-  // RETAIN for writer-only self-heal (HIGH-1) — getDbPath() is cleared by a worker writer's closeDb().
-  writerWorkerDbPath = writerB === "worker" ? (dbPath as string) : undefined;
-  // ── READER half ─────────────────────────────────────────────────────────────────────────────────
-  // Force the backend rather than letting it fall out of the path, so a file-DB server in Phase 0 still
-  // runs every read synchronously on the main connection (no worker spawned, no callsite moved).
+  initWriter({ ...options.writer, path: writerB === "worker" ? dbPath : ":memory:" });
+  writerWorkerDbPath = writerB === "worker" ? dbPath : undefined;
   replaceReader(
     readerB === "worker"
       ? createReaderGateway({
@@ -362,6 +283,7 @@ export function initGateway(options: InitGatewayOptions = {}): void {
   );
   currentReaderBackend = readerB;
   currentWriterBackend = writerB;
+  gatewayDbGeneration = getDbGeneration();
   // An in-transaction crash seam is a main-thread closure; once op bodies run on the WRITER thread it
   // can never be delivered, so arming one must FAIL rather than silently inject nothing (L-C #1899).
   // Keyed on the WRITER half only — the seam is armed inside write-op bodies, so a worker reader leaves
@@ -369,7 +291,7 @@ export function initGateway(options: InitGatewayOptions = {}): void {
   setWriterFaultsDeliverable(writerB === "in-process");
 }
 
-/** Tear the gateway down (both pools). After this, the next `getGateway()` lazily re-inits in-process. */
+/** Tear the gateway down (both pools). The next getGateway() selects placement from the current database. */
 export async function shutdownGateway(): Promise<void> {
   const previousReader = reader;
   reader = undefined;
@@ -381,17 +303,7 @@ export async function shutdownGateway(): Promise<void> {
   await previousReader?.destroy();
 }
 
-/**
- * Tear down JUST the reader half — terminates any worker-pool threads and replaces them with a fresh
- * in-process reader. The writer is left COMPLETELY untouched (#1960 T2 server teardown).
- *
- * Deliberately NOT `shutdownGateway()`: that also calls `shutdownWriter()`, which unconditionally
- * REJECTS every write still queued at the writer (writer-gateway.ts) — a needless side effect on a
- * clean stop, since Phase-R never puts the writer on a worker (it stays in-process always). This is
- * the shutdown counterpart the design pass calls for (§1.5): "worker threads must be torn down on
- * shutdown or a restart can leave orphaned threads holding WAL read marks." Safe to call even when the
- * reader was never worker-backed — the in-process reader's `destroy()` resolves immediately.
- */
+/** Release reader workers without rejecting the writer FIFO during graceful shutdown. */
 export async function shutdownGatewayReader(): Promise<void> {
   const previous = reader;
   reader = createReaderGateway({ backend: "in-process" });
@@ -404,16 +316,7 @@ export function isGatewayInitialized(): boolean {
   return reader !== undefined;
 }
 
-/**
- * The live WRITER backend. Domains whose post-commit main-thread work is not yet worker-safe (e.g.
- * getDb-backed effect delivery) read this to refuse rather than commit-then-silently-drop.
- *
- * DELIBERATELY THE WRITER HALF, not "either half" (#1960 T1). Every caller is really asking "is the
- * main RW connection still ours?" — `events.ts`'s keyless-append guard and `managed-policy.ts`'s
- * worker-safe builder both branch on that, and it is the WRITER flip that surrenders the connection.
- * A worker-backed READER changes nothing for them, so they must not start refusing when reads move off
- * the loop. Use `readerBackend()` for the read half.
- */
+/** The live writer placement, retained as the historical backend alias. */
 export function gatewayBackend(): GatewayBackend {
   return currentWriterBackend;
 }
@@ -429,23 +332,13 @@ export function writerBackend(): GatewayBackend {
 }
 
 function ensureInit(): void {
-  if (reader === undefined) {
-    // Cold gateway: stand BOTH halves up (in-process by default).
+  if (reader === undefined || (getDbPath() !== undefined && gatewayDbGeneration !== getDbGeneration())) {
+    // A replaced database owns new pools; never send its writes to the previous file (#1870 S8).
     initGateway();
     return;
   }
-  // The reader and writer are normally stood up AND torn down together by
-  // initGateway()/shutdownGateway(), but the writer CAN be torn down on its own (`shutdownWriter()` —
-  // used by the writer suite's afterEach and reachable directly), leaving `reader` defined while the
-  // writer backend is undefined. A reader-only sentinel then skips re-init and the next write hits
-  // `requireBackend()` → "writer gateway not initialized" — the failure L1 (#1875) surfaced once feature
-  // writes began routing through `getGateway().write/coalesce(...)`. Restore JUST the writer, matching
-  // the live backend, so a lone shutdownWriter() self-heals WITHOUT disturbing the reader (never
-  // downgrading a worker-backed reader to in-process).
+  // A lone writer teardown preserves reader placement. Rebuild only that writer.
   if (!isWriterInitialized()) {
-    // Reconstruct the writer against the RETAINED WRITER worker path (never getDbPath(), which closeDb()
-    // clears at worker-writer bootstrap — HIGH-1). For in-process, ":memory:" selects the in-process
-    // writer. Keyed on the WRITER half so a worker READER never drags the writer onto a worker.
     initWriter({ path: currentWriterBackend === "worker" ? writerWorkerDbPath : ":memory:" });
   }
 }
@@ -503,8 +396,8 @@ const GATEWAY: DbGateway = {
 };
 
 /**
- * The process-wide DB gateway — the sole sanctioned DB entry point (ADR §3.3). Lazily stands up the
- * in-process backend on first use if `initGateway()` was not called explicitly, so a caller never sees
+ * The process-wide DB gateway — the sole sanctioned DB entry point (ADR §3.3). Lazily selects pools for the
+ * current database on first use if `initGateway()` was not called explicitly, so a caller never sees
  * an uninitialized gateway. The returned facade is stable across `initGateway()` re-inits.
  */
 export function getGateway(): DbGateway {