@humwick/server 0.130.1 → 0.130.3

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/continuation-archives-async.ts

@@ -3,6 +3,7 @@ import { getDbPath, runDbMaintenanceWorker } from "./connection.ts";
 import { purgeContinuationArchives, type ContinuationArchivePurgeInput, type ContinuationArchivePurgeResult } from "./continuation-archive-purge.ts";
 import { syncInMemoryContinuationArchiveSearchIndex, type ContinuationArchiveSearchSyncInput, type ContinuationArchiveSearchSyncResult } from "./continuation-archive-search.ts";
 import { getGateway } from "./gateway.ts";
+import type { appendContinuationArchiveRefs } from "./continuations.ts";
 import type { archiveAndAdvanceContinuation, archiveContinuationSegment, getContinuationArchiveByRef, searchContinuationArchives } from "./continuation-archives.ts";
 
 // Anything left after the budget is still removed, by the agent delete's cascade.
@@ -24,6 +25,10 @@ export function archiveAndAdvanceContinuationAsync(input: Parameters<typeof arch
   return getGateway().write("continuationArchives.compact", { input }, { idempotencyKey: requestId }) as unknown as Promise<ReturnType<typeof archiveAndAdvanceContinuation>>;
 }
 
+export function appendContinuationArchiveRefsAsync(agentId: string, refs: string[]): Promise<ReturnType<typeof appendContinuationArchiveRefs>> {
+  return getGateway().write("continuationArchives.appendRefs", { agentId, refs }) as unknown as Promise<ReturnType<typeof appendContinuationArchiveRefs>>;
+}
+
 /**
  * #3012 — catch the side FTS index up. A lock-free reader probe gates the run; the work runs in the
  * maintenance subprocess against the side file's own write lock, never on the hub's loop. An

package/src/db/continuation-archives-write-ops.ts

@@ -1,4 +1,5 @@
 import { archiveAndAdvanceContinuation, archiveContinuationSegment } from "./continuation-archives.ts";
+import { appendContinuationArchiveRefs } from "./continuations.ts";
 import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
 
 export const CONTINUATION_ARCHIVES_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
@@ -14,4 +15,10 @@ export const CONTINUATION_ARCHIVES_WRITE_OPS: Readonly<Record<string, WriterOpSp
     fn: (args: { input: Parameters<typeof archiveAndAdvanceContinuation>[0] }, ctx: WriterOpContext) =>
       archiveAndAdvanceContinuation({ ...args.input, now: args.input.now ?? ctx.now }),
   },
+  // #1870 S7: the envelope's ref list is a set, so a replay converges.
+  "continuationArchives.appendRefs": {
+    offLoop: true,
+    idempotent: true,
+    fn: (args: { agentId: string; refs: string[] }, ctx: WriterOpContext) => appendContinuationArchiveRefs(args.agentId, args.refs, ctx.now),
+  },
 });

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 = ?
@@ -143,7 +143,7 @@ function mergeLedger(
   return { ledger: merged.slice(start), dropped: merged.slice(0, start) };
 }
 
-export function appendContinuationArchiveRefs(agentId: string, archiveRefs: string[]): ContinuationEnvelope | null {
+export function appendContinuationArchiveRefs(agentId: string, archiveRefs: string[], now: number = Date.now()): ContinuationEnvelope | null {
   if (archiveRefs.length === 0) return getContinuationEnvelope(agentId);
   const existing = getContinuationEnvelope(agentId);
   if (!existing) return null;
@@ -155,7 +155,7 @@ export function appendContinuationArchiveRefs(agentId: string, archiveRefs: stri
     UPDATE agent_continuations
     SET archive_refs = ?, updated_at = ?
     WHERE agent_id = ?
-  `).run(JSON.stringify(refs), Date.now(), agentId);
+  `).run(JSON.stringify(refs), now, agentId);
   return getContinuationEnvelope(agentId);
 }
 

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/db-writer-worker.ts

@@ -14,12 +14,19 @@
 // It default-exports the offload task function; `createWorkerPool` invokes it via the offload
 // worker-runtime bootstrap.
 
+import { relayEnv } from "@humwick/sdk/env";
 import type { OffloadWorkerTask } from "@humwick/offload/worker";
 import { Database } from "bun:sqlite";
 import { applyConnectionPragmas, closeDb, getDbPath, setDb } from "./connection.ts";
 import { serializeDbError } from "./db-error-registry.ts";
 import { runWriterBatch, runWriterOp, type SerializedBatchEntry, type WriterJobInput, type WriterJobResult } from "./write-ops.ts";
 
+// A lock-contention test may shorten the wait; production keeps 4 s.
+function writerBusyTimeoutMs(): number {
+  const override = Number(relayEnv(process.env, "AGENT_RELAY_WRITER_BUSY_TIMEOUT_MS")?.trim() || Number.NaN);
+  return Number.isSafeInteger(override) && override >= 0 ? override : 4000;
+}
+
 /** Ensure this worker's thread-local RW connection points at `dbPath`, opening it once and reusing
  *  it across jobs. A path change (never expected in production) reopens — cheap and defensive. */
 function ensureConnection(dbPath: string): void {
@@ -33,7 +40,7 @@ function ensureConnection(dbPath: string): void {
   // per-connection pragmas before it begins executing serialized write operations.
   applyConnectionPragmas(conn, { ensureWal: false });
   // #1870: external 1.2 s holds wait here, below the gateway's 5 s deadline, never on the loop.
-  conn.run("PRAGMA busy_timeout = 4000");
+  conn.run(`PRAGMA busy_timeout = ${writerBusyTimeoutMs()}`);
   setDb(conn, dbPath);
 }
 

package/src/db/deploy-events-async.ts

@@ -25,6 +25,7 @@ export function tryBeginDeployEventAsync(input: TryBeginDeployEventInput): Promi
 export function backfillDeployEventVersionAsync(id: string, version: string): Promise<DeployEvent | null> {
   return write("deployEvents.backfillVersion", { id, version });
 }
+export function getDeployEventForCommitAsync(commitSha: string): Promise<DeployEvent | null> { return read("deployEvents.forCommit", { commitSha }); }
 export function getDeployEventAsync(id: string): Promise<DeployEvent | null> { return read("deployEvents.get", { id }); }
 export function listDeployEventsAsync(limit: number, offset: number): Promise<DeployEvent[]> {
   return read("deployEvents.list", { limit, offset });

package/src/db/deploy-events-read-ops.ts

@@ -3,7 +3,7 @@
 import {
   currentPendingDeployEvent,
   deployChangesForCommits,
-  getDeployEvent,
+  getDeployEvent, getDeployEventForCommit,
   latestFailedDeployForCommit,
   latestSuccessfulDeploy,
   listDeployEvents,
@@ -14,6 +14,7 @@ import {
 } from "./deploy-events.ts";
 
 export const DEPLOY_EVENTS_READ_OPS = {
+  "deployEvents.forCommit": (args: { commitSha: string }): DeployEvent | null => getDeployEventForCommit(args.commitSha),
   "deployEvents.get": (args: { id: string }): DeployEvent | null => getDeployEvent(args.id),
   "deployEvents.list": (args: { limit: number; offset: number }): DeployEvent[] => listDeployEvents(args.limit, args.offset),
   "deployEvents.needingChanges": (args: { limit: number }): DeployEvent[] => listDeployEventsNeedingChanges(args.limit),

package/src/db/deploy-events.ts

@@ -1,14 +1,16 @@
+import { defaultTaskIssueRelation } from "./task-issue-relation";
+import { parseJson, type TaskDispatch } from "@humwick/sdk";
 import { randomUUID } from "node:crypto";
 import { getDb, writeTransaction } from "./connection.ts";
 import { setTaskStageBody } from "./task-entity.ts";
 import { insertTaskEvent } from "./task-core.ts";
 import { listIssuesForEntity } from "./issue-associations.ts";
-import type { IssueRef } from "../types";
+import type { IssueRef, IssueRefRelation } from "../types";
 
 export type DeployStatus = "pending" | "succeeded" | "failed" | "rolled-back";
 export type DeployHost = { id: string; fromVersion?: string; toVersion?: string; status: string; reason?: string };
 export type DeployCommit = { sha: string; subject: string };
-export type DeployTaskChange = { id: number; label: string; issues: IssueRef[] };
+export type DeployTaskChange = { id: number; label: string; issues: Array<IssueRef & { relation?: IssueRefRelation }>; onDeploy?: string };
 export type DeployChangesSummary = {
   range: { previousSha?: string; commitSha: string };
   tasks: DeployTaskChange[];
@@ -219,6 +221,24 @@ export function getDeployEvent(id: string): DeployEvent | null {
   return row ? rowToDeployEvent(row) : null;
 }
 
+/** The running artifact may boot while its deploy ledger is still pending (#3761). */
+export function getDeployEventForCommit(commitSha: string): DeployEvent | null {
+  const row = getDb().query("SELECT * FROM deploy_events WHERE commit_sha = ? ORDER BY started_at DESC LIMIT 1").get(commitSha);
+  const event = row ? rowToDeployEvent(row) : null;
+  if (event?.changes?.state === "ready" && event.changes.tasks.length) {
+    const notes = getDb().query("SELECT id, on_deploy, dispatch, owner_agent_id FROM tasks WHERE id IN (SELECT value FROM json_each(?))")
+      .all(JSON.stringify(event.changes.tasks.map(task => task.id))) as Array<{ id: number; on_deploy: string | null; dispatch: string | null; owner_agent_id: string | null }>;
+    const byId = new Map(notes.map(task => [task.id, task]));
+    event.changes.tasks = event.changes.tasks.map(task => {
+      const { onDeploy, ...snapshot } = task;
+      const current = byId.get(task.id);
+      const note = current ? current.on_deploy : onDeploy;
+      return { ...snapshot, ...(current ? { issues: deployTaskIssues(task.id, current.dispatch, current.owner_agent_id) } : {}), ...(note ? { onDeploy: note } : {}) };
+    });
+  }
+  return event;
+}
+
 /** Newest-first page of the deploy ledger for the dashboard timeline (#1327). */
 export function listDeployEvents(limit: number, offset: number): DeployEvent[] {
   const rows = getDb()
@@ -250,6 +270,11 @@ export function listDeployEventsNeedingChanges(limit: number): DeployEvent[] {
   return rows.map(rowToDeployEvent);
 }
 
+function deployTaskIssues(id: number, dispatch: string | null, ownerAgentId: string | null): DeployTaskChange["issues"] {
+  const relation = defaultTaskIssueRelation(parseJson<TaskDispatch | undefined>(dispatch, undefined), ownerAgentId ?? undefined);
+  return listIssuesForEntity("task", String(id)).map(item => ({ ...item.issueRef, relation: item.association.relation ?? relation }));
+}
+
 /**
  * Match a deploy's ordered commit list to every durable Task with an exact stored
  * commit SHA. This CD-only query loads the task commit payload once; the HTTP
@@ -258,7 +283,7 @@ export function listDeployEventsNeedingChanges(limit: number): DeployEvent[] {
 export function deployChangesForCommits(commits: DeployCommit[]): Pick<DeployChangesSummary, "tasks" | "unmatchedCommits"> {
   const rangeShas = new Set(commits.map((commit) => commit.sha));
   const matchedShas = new Set<string>();
-  const rows = getDb().query("SELECT id, title, commits FROM tasks WHERE kind = 'deliverable' AND commits IS NOT NULL ORDER BY id ASC").all() as any[];
+  const rows = getDb().query("SELECT id, title, commits, on_deploy, dispatch, owner_agent_id FROM tasks WHERE kind = 'deliverable' AND commits IS NOT NULL ORDER BY id ASC").all() as any[];
   const tasks: DeployTaskChange[] = [];
   for (const row of rows) {
     let taskCommits: Array<{ sha?: unknown }>;
@@ -268,7 +293,8 @@ export function deployChangesForCommits(commits: DeployCommit[]): Pick<DeployCha
     tasks.push({
       id: Number(row.id),
       label: String(row.title),
-      issues: listIssuesForEntity("task", String(row.id)).map((item) => item.issueRef),
+      issues: deployTaskIssues(Number(row.id), row.dispatch, row.owner_agent_id),
+      ...(row.on_deploy ? { onDeploy: String(row.on_deploy) } : {}),
     });
   }
   return { tasks, unmatchedCommits: commits.filter((commit) => !matchedShas.has(commit.sha)) };
@@ -316,6 +342,11 @@ export function renewDeployEventLease(input: { id: string; now?: number }): bool
   return writeTransaction(() => renewDeployEventLeaseBody(input, input.now ?? Date.now()));
 }
 
+/** Migration progress shares the existing deploy row and dashboard surface (#3470). */
+export function recordDeployEventHosts(id: string, hosts: DeployHost[]): boolean {
+  return getDb().query("UPDATE deploy_events SET hosts = ? WHERE id = ? AND status = 'pending'").run(JSON.stringify(hosts), id).changes > 0;
+}
+
 /**
  * Emergency operator recovery for a genuinely stranded deploy owner:
  * `bun run scripts/release.ts --clear-deploy-lease <event-id>` (→ `failed`), or

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 {

package/src/db/history-retention-ops.ts

@@ -0,0 +1,13 @@
+import { pruneKernelReplayResults } from "@humwick/kernel/sqlite-kernel-persistence";
+import { getDb } from "./connection";
+import { pruneTerminalCommands } from "./command-retention";
+import { pruneTokenUsage } from "./token-usage-retention";
+import type { WriterOpSpec } from "./write-ops";
+
+// One gateway call is one small transaction; never drain a backlog inside the writer job (#3619).
+const BATCH = 25;
+export const HISTORY_RETENTION_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = {
+  "historyRetention.kernel": { offLoop: true, idempotent: true, fn: (_args, ctx) => pruneKernelReplayResults(getDb(), ctx.now, BATCH) },
+  "historyRetention.tokens": { offLoop: true, idempotent: true, fn: (_args, ctx) => pruneTokenUsage(ctx.now - 90 * 24 * 60 * 60_000, BATCH) },
+  "historyRetention.commands": { offLoop: true, idempotent: true, fn: (_args, ctx) => pruneTerminalCommands(ctx.now - 30 * 24 * 60 * 60_000, 1_000, ctx.now - 60 * 60_000) },
+};

package/src/db/hosts-registration.ts

@@ -139,8 +139,16 @@ export type HardwareReconciliation =
 
 /** Capacity is an observed, runtime-varying property, not host identity. WSL2 in particular can
  * report less RAM after a reboot, and swap may appear/disappear with zram configuration. Keep the
- * latest value for placement without making a legitimate capacity change an anti-spoof conflict. */
-const TOLERANT_CAPACITY_HARDWARE_FIELDS = new Set(["totalMemMb", "totalStorageMb", "totalSwapMb"]);
+ * latest value for placement without making a legitimate capacity change an anti-spoof conflict.
+ * `osVersion` (the kernel string) changes on every OS patch; it is not hardware identity (#3770). */
+const TOLERANT_CAPACITY_HARDWARE_FIELDS = new Set(["totalMemMb", "totalStorageMb", "totalSwapMb", "osVersion"]);
+
+/** The identity-defining keys present on both sides with different values: what a conflict notice names. */
+export function conflictingHardwareFields(stored: HostHardware, reported: HostHardware): string[] {
+  const a = stored as unknown as Record<string, unknown>;
+  const b = reported as unknown as Record<string, unknown>;
+  return Object.keys(a).filter((key) => !TOLERANT_CAPACITY_HARDWARE_FIELDS.has(key) && a[key] !== undefined && b[key] !== undefined && a[key] !== b[key]).sort();
+}
 
 export function reconcileHardwareFields(stored: HostHardware, reported: HostHardware): HardwareReconciliation {
   const storedRec = stored as unknown as Record<string, unknown>;