@humwick/server 0.130.2 → 0.130.4

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

@@ -9,8 +9,8 @@ import type {
   setInboxThreadState,
 } from "./inbox.ts";
 
-export function getInboxStateAsync(operatorId: string): Promise<ReturnType<typeof getInboxState>> {
-  return getGateway().read("inbox.state", { operatorId }) as unknown as Promise<ReturnType<typeof getInboxState>>;
+export function getInboxStateAsync(operatorId: string, options: { excludeOffline?: boolean } = {}): Promise<ReturnType<typeof getInboxState>> {
+  return getGateway().read("inbox.state", { operatorId, ...(options.excludeOffline ? { excludeOffline: true } : {}) }) as unknown as Promise<ReturnType<typeof getInboxState>>;
 }
 export function listChatHistoryImportsAsync(input: Parameters<typeof listChatHistoryImports>[0] = {}): Promise<ReturnType<typeof listChatHistoryImports>> {
   return getGateway().read("inbox.historyImports", input) as unknown as Promise<ReturnType<typeof listChatHistoryImports>>;

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

@@ -3,6 +3,6 @@
 import { getInboxState, listChatHistoryImports } from "./inbox.ts";
 
 export const INBOX_READ_OPS = {
-  "inbox.state": (args: { operatorId: string }) => getInboxState(args.operatorId),
+  "inbox.state": (args: { operatorId: string; excludeOffline?: boolean }) => getInboxState(args.operatorId, { excludeOffline: args.excludeOffline }),
   "inbox.historyImports": (args: Parameters<typeof listChatHistoryImports>[0]) => listChatHistoryImports(args),
 };

package/src/db/inbox.ts

@@ -10,12 +10,18 @@ import type {
   InboxThreadState,
 } from "../types";
 
-export function getInboxState(operatorId: string): InboxState {
+/**
+ * #2410 — `excludeOffline` (opt-in, the #2396 contract) keeps only peers whose agent is registered
+ * and not offline: the dashboard's "Show offline" switch hides every other thread, and the table
+ * accrues a row per agent id ever chatted with, so the full read is mostly long-dead peers.
+ */
+export function getInboxState(operatorId: string, options: { excludeOffline?: boolean } = {}): InboxState {
+  const live = options.excludeOffline ? " AND peer_id IN (SELECT id FROM agents WHERE status <> 'offline')" : "";
   const threads = (getDb().query(
-    "SELECT * FROM inbox_thread_state WHERE operator_id = ? ORDER BY updated_at DESC",
+    `SELECT * FROM inbox_thread_state WHERE operator_id = ?${live} ORDER BY updated_at DESC`,
   ).all(operatorId) as any[]).map(rowToInboxThreadState);
   const drafts = (getDb().query(
-    "SELECT * FROM inbox_drafts WHERE operator_id = ? ORDER BY updated_at DESC",
+    `SELECT * FROM inbox_drafts WHERE operator_id = ?${live} ORDER BY updated_at DESC`,
   ).all(operatorId) as any[]).map(rowToInboxDraft);
   return { operatorId, threads, drafts };
 }

package/src/db/issue-associations.ts

@@ -40,13 +40,13 @@ function cleanText(value: string | undefined, field: string, max: number): strin
   return cleaned;
 }
 
-export function associateIssue(issueRefId: string, entityType: IssueAssociationEntityType, entityId: string, relation?: IssueRefRelation): IssueAssociation {
+export function associateIssue(issueRefId: string, entityType: IssueAssociationEntityType, entityId: string, relation?: IssueRefRelation, submittedAt: number = Date.now()): IssueAssociation {
   const cleanedIssueRefId = cleanText(issueRefId, "issueRefId", 120);
   if (!getIssueRef(cleanedIssueRefId)) throw new ValidationError(`issue ref ${cleanedIssueRefId} not found`);
   const cleanedEntityType = cleanEntityType(entityType);
   const cleanedEntityId = cleanText(entityId, "entityId", 240);
   const cleanedRelation = optionalEnum(relation, "relation", ISSUE_REF_RELATIONS);
-  const now = Date.now();
+  const now = submittedAt;
   getDb().query(`
     INSERT INTO issue_associations (issue_ref_id, entity_type, entity_id, created_at, relation)
     VALUES (?, ?, ?, ?, ?)

package/src/db/issue-refs-async.ts

@@ -3,11 +3,14 @@ import { randomUUID } from "node:crypto";
 import { getGateway } from "./gateway.ts";
 import type { IssueRef } from "../types";
 import type { IssueTrackerIssueSummary } from "../issue-tracker/adapter";
-import type { ResolveIssueRefByExternalKeyInput, ResolveIssueRefFromStringInput, UpdateIssueRefInput, UpsertIssueRefInput } from "./issue-refs.ts";
+import type { ListIssueRefsOptions, ResolveIssueRefByExternalKeyInput, ResolveIssueRefFromStringInput, UpdateIssueRefInput, UpsertIssueRefInput } from "./issue-refs.ts";
 import type { IssueLifecycleActionRecord, UpsertIssueLifecycleActionInput } from "./issue-lifecycle.ts";
 
 const write = <T>(op: string, args: unknown, opts?: { idempotencyKey?: string }) => getGateway().write(op, args as never, opts) as unknown as Promise<T>;
 
+const read = <T>(op: string, args: unknown = {}) => getGateway().read(op as never, args as never) as unknown as Promise<T>;
+
+export const listIssueRefsAsync = (opts: ListIssueRefsOptions = {}) => read<IssueRef[]>("issueRefs.list", opts);
 export const upsertIssueRefAsync = (input: UpsertIssueRefInput) => write<IssueRef>("issueRefs.upsert", input);
 export const resolveIssueRefByExternalKeyAsync = (input: ResolveIssueRefByExternalKeyInput) => write<IssueRef>("issueRefs.resolveExternalKey", input);
 export const resolveIssueRefFromStringAsync = (input: ResolveIssueRefFromStringInput) => write<IssueRef>("issueRefs.resolveFromString", input);

package/src/db/issue-refs-read-ops.ts

@@ -0,0 +1,6 @@
+// #3799 — the issue-ref listing on the reader pool (it ran as a cold main-thread scan, 10 s on swap-bound I/O).
+import { listIssueRefs, type ListIssueRefsOptions } from "./issue-refs.ts";
+
+export const ISSUE_REFS_READ_OPS = {
+  "issueRefs.list": (args: ListIssueRefsOptions) => listIssueRefs(args),
+};

package/src/db/issue-refs.ts

@@ -252,7 +252,8 @@ export function resolveIssueRefFromString(input: ResolveIssueRefFromStringInput,
   }, now);
 }
 
-export function listIssueRefs(opts: ListIssueRefsOptions = {}): IssueRef[] {
+/** Listing SQL, exported so the query-plan gate pins the production statement (#3799). */
+export function buildListIssueRefsQuery(opts: ListIssueRefsOptions = {}): { sql: string; params: Array<string | number> } {
   const conditions: string[] = [];
   const params: Array<string | number> = [];
   if (opts.provider) {
@@ -271,13 +272,12 @@ export function listIssueRefs(opts: ListIssueRefsOptions = {}): IssueRef[] {
   if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 500) throw new ValidationError("limit must be between 1 and 500");
   params.push(limit);
   const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
-  const rows = getDb().query(`
-    SELECT * FROM issue_refs
-    ${where}
-    ORDER BY updated_at DESC, created_at DESC, id DESC
-    LIMIT ?
-  `).all(...params) as IssueRefRow[];
-  return rows.map(rowToIssueRef);
+  return { sql: `SELECT * FROM issue_refs ${where} ORDER BY updated_at DESC, created_at DESC, id DESC LIMIT ?`, params };
+}
+
+export function listIssueRefs(opts: ListIssueRefsOptions = {}): IssueRef[] {
+  const { sql, params } = buildListIssueRefsQuery(opts);
+  return (getDb().query(sql).all(...params) as IssueRefRow[]).map(rowToIssueRef);
 }
 
 export function updateIssueRef(id: string, input: UpdateIssueRefInput, now: number = Date.now()): IssueRef | null {

package/src/db/kernel-event-log-schema.ts

@@ -1,4 +1,5 @@
 import { ensureEventLogSchema } from "@humwick/kernel/event-log";
+import { ensureKernelReplayRetentionSchema } from "@humwick/kernel/sqlite-kernel-persistence";
 import { getDb } from "./connection.ts";
 
 /**
@@ -11,4 +12,5 @@ import { getDb } from "./connection.ts";
  */
 export function ensureKernelEventLogSchema(): void {
   ensureEventLogSchema(getDb());
+  ensureKernelReplayRetentionSchema(getDb(), Date.now());
 }

package/src/db/land-boundaries.ts

@@ -1,7 +1,8 @@
 // #3363 — reads of the Kernel landing boundary and incident entities (kernel/landing-incident.ts) for
 // the red-main controller. Writes go through the Kernel ops (src/services/red-main-incident.ts).
 import type { LandBoundary, RedMainIncident } from "@humwick/kernel/landing-incident";
-import type { ShippingRedMain } from "@humwick/sdk";
+import { ciRunUrl, type ShippingFailingTest, type ShippingRedMain } from "@humwick/sdk";
+import type { BaseKnownFailure } from "@humwick/sdk/base-known-failures";
 import { getDb } from "./connection.ts";
 import { LAND_INCIDENT_TABLE, OPEN_INCIDENT_STATES } from "./land-incident-eligibility.ts";
 
@@ -81,12 +82,57 @@ export function openRedMainIncidentForRemote(remote: string): RedMainIncident |
   return row ? incident(row) : null;
 }
 
-/** The Shipping page's "lane stopped" lines: each open incident with its red sha. */
-export function openRedMainLines(): ShippingRedMain[] {
+type OpenIncidentRow = Record<string, unknown> & { redRemote: string; redSha: string };
+
+/** Open incidents with their red boundary. `i.*`: the Kernel adds a newer field's column only when the
+ *  landing module starts, so a read right after deploy must not name it (#3362 §11 failingTests). */
+function openIncidentRows(remote?: string): OpenIncidentRow[] {
   if (!tablesReady()) return [];
-  return getDb().query(`SELECT i.id AS incidentId, i.laneKey, i.state, i.mainFailurePolicy, b.remote, b.landedTipSha AS sha
+  return getDb().query(`SELECT i.*, b.remote AS redRemote, b.landedTipSha AS redSha
     FROM ${LAND_INCIDENT_TABLE} i JOIN ${BOUNDARY_TABLE} b ON b.id = i.redBoundaryId
-    WHERE i.state IN ${OPEN_STATES_SQL} ORDER BY i.openedAt, i.id`).all() as ShippingRedMain[];
+    WHERE i.state IN ${OPEN_STATES_SQL} AND (? IS NULL OR b.remote = ?) ORDER BY i.openedAt, i.id`).all(remote ?? null, remote ?? null) as OpenIncidentRow[];
+}
+
+function failingTestsOf(row: Record<string, unknown>): ShippingFailingTest[] {
+  if (typeof row.failingTests !== "string") return [];
+  try {
+    const parsed: unknown = JSON.parse(row.failingTests);
+    return Array.isArray(parsed) ? parsed.filter((entry): entry is ShippingFailingTest =>
+      typeof entry?.file === "string" && typeof entry?.name === "string") : [];
+  } catch {
+    console.warn(`[red-main] incident ${String(row.id)} has unreadable failingTests; showing none`);
+    return [];
+  }
+}
+
+function culpritTaskIds(row: Record<string, unknown>): number[] {
+  const ids = JSON.parse(String(row.culpritBoundaryIds ?? "[]")) as string[];
+  if (!ids.length) return [];
+  const rows = getDb().query(`SELECT DISTINCT taskId FROM ${BOUNDARY_TABLE} WHERE taskId IS NOT NULL AND id IN (${ids.map(() => "?").join(",")}) ORDER BY taskId`)
+    .all(...ids) as { taskId: number }[];
+  return rows.map((entry) => entry.taskId);
+}
+
+/** The Shipping page's red-main lines: each open incident with its red sha, failing cases, owners and run. */
+export function openRedMainLines(): ShippingRedMain[] {
+  return openIncidentRows().map((row) => {
+    const failingTests = failingTestsOf(row);
+    const ownerTaskIds = culpritTaskIds(row);
+    return {
+      incidentId: String(row.id), laneKey: String(row.laneKey), state: String(row.state),
+      ...(row.mainFailurePolicy ? { mainFailurePolicy: row.mainFailurePolicy as "stop" | "advisory" } : {}),
+      remote: row.redRemote, sha: row.redSha,
+      runUrl: ciRunUrl(row.redRemote, Number(row.ciRunId), Number(row.ciAttempt)),
+      ...(failingTests.length ? { failingTests } : {}),
+      ...(ownerTaskIds.length ? { ownerTaskIds } : {}),
+    };
+  });
+}
+
+/** #3362 §11: failing cases already present on `remote`'s main, which delivery gates hold out of unrelated runs. */
+export function baseKnownFailures(remote: string): BaseKnownFailure[] {
+  return openIncidentRows(remote).flatMap((row) =>
+    failingTestsOf(row).map((test) => ({ ...test, incidentId: String(row.id), sha: row.redSha })));
 }
 
 /** #3381 — whether any partial land happened (for `remote`, or anywhere when omitted): a boundary or a

package/src/db/land-gate-attestations.ts

@@ -110,7 +110,7 @@ export interface InsertLandGateAttestationInput extends Omit<LandGateAttestation
  * can legitimately land twice (a revert-and-reland, a retried push), and the FIRST green attestation
  * is as true as the second — so a conflict keeps the original rather than churning the row.
  */
-export function insertLandGateAttestation(input: InsertLandGateAttestationInput): LandGateAttestationRecord {
+export function insertLandGateAttestation(input: InsertLandGateAttestationInput, submittedAt: number = Date.now()): LandGateAttestationRecord {
   const record = decodeLandGateAttestationRow({
     repo: input.repo,
     tree_sha: input.treeSha,
@@ -121,7 +121,7 @@ export function insertLandGateAttestation(input: InsertLandGateAttestationInput)
     gate_names: JSON.stringify(input.gateNames),
     gates_ran: input.gatesRan,
     workspace_id: input.workspaceId ?? null,
-    attested_at: input.attestedAt ?? Date.now(),
+    attested_at: input.attestedAt ?? submittedAt,
     suite_coverage: input.suiteCoverage ?? null,
   });
   getDb().query(`

package/src/db/landing-receipts.ts

@@ -110,7 +110,7 @@ function receiptId(input: InsertLandingReceiptInput): string {
   return `landing_${createHash("sha256").update(key).digest("hex").slice(0, 24)}`;
 }
 
-export function insertLandingReceipt(input: InsertLandingReceiptInput): LandingReceipt {
+export function insertLandingReceipt(input: InsertLandingReceiptInput, submittedAt: number = Date.now()): LandingReceipt {
   const receipt: LandingReceipt = decodeLandingReceiptRow({
     id: receiptId(input),
     project_id: input.projectId ?? null,
@@ -127,7 +127,7 @@ export function insertLandingReceipt(input: InsertLandingReceiptInput): LandingR
     team_id: input.teamId ?? null,
     orchestrator_id: input.orchestratorId ?? null,
     host: input.host ?? null,
-    landed_at: input.landedAt ?? Date.now(),
+    landed_at: input.landedAt ?? submittedAt,
   });
   getDb().query(`
     INSERT INTO landing_receipts (

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

@@ -0,0 +1,5 @@
+import { getDb } from "./connection";
+import type { ContextState } from "../types";
+export function persistAdvisoryContext(agentId: string, context: ContextState): void {
+  getDb().query("UPDATE agents SET context_state = ? WHERE id = ?").run(JSON.stringify(context), agentId);
+}

package/src/db/lifecycle-tail-async.ts

@@ -0,0 +1,76 @@
+import { randomUUID } from "node:crypto";
+import { getGateway } from "./gateway";
+import type { clearAgentNotice, recordTerminalEvent } from "./terminal-events";
+import type { recordCrashReport } from "./crash-reports";
+import type { stampSpawnPrincipal } from "./agent-ownership";
+import type { markSpawnRegistrationConfirmed } from "../commands-db";
+import type { seedSpawnPromptMirror } from "./message-reads";
+import type { resolveQueuedPolicyMessages, resolveQueuedDirectMessages } from "./delivery";
+import type { resolveQueuedCoordinatorMessages } from "./coordinator-delivery";
+import type { updateManagedAgentState } from "../config-store";
+import type { deleteWorkspace } from "./workspaces";
+import type { addSubscription, removeSubscription, removeSubscriptionsForTask } from "./notification-subscriptions";
+
+export function clearAgentNoticeAsync(...args: Parameters<typeof clearAgentNotice>): Promise<ReturnType<typeof clearAgentNotice>> {
+  return getGateway().write("lifecycleTail.clearAgentNotice", args) as unknown as Promise<ReturnType<typeof clearAgentNotice>>;
+}
+
+export function recordTerminalEventAsync(...args: Parameters<typeof recordTerminalEvent>): Promise<ReturnType<typeof recordTerminalEvent>> {
+  return getGateway().write("lifecycleTail.recordTerminalEvent", args, { idempotencyKey: randomUUID() }) as unknown as Promise<ReturnType<typeof recordTerminalEvent>>;
+}
+
+export function recordCrashReportAsync(...args: Parameters<typeof recordCrashReport>): Promise<ReturnType<typeof recordCrashReport>> {
+  return getGateway().write("lifecycleTail.recordCrashReport", args, { idempotencyKey: randomUUID() }) as unknown as Promise<ReturnType<typeof recordCrashReport>>;
+}
+
+export function stampSpawnPrincipalAsync(...args: Parameters<typeof stampSpawnPrincipal>): Promise<ReturnType<typeof stampSpawnPrincipal>> {
+  return getGateway().write("lifecycleTail.stampSpawnPrincipal", args) as unknown as Promise<ReturnType<typeof stampSpawnPrincipal>>;
+}
+
+export function markSpawnRegistrationConfirmedAsync(...args: Parameters<typeof markSpawnRegistrationConfirmed>): Promise<ReturnType<typeof markSpawnRegistrationConfirmed>> {
+  return getGateway().write("lifecycleTail.markSpawnRegistrationConfirmed", args) as unknown as Promise<ReturnType<typeof markSpawnRegistrationConfirmed>>;
+}
+
+export function seedSpawnPromptMirrorAsync(...args: Parameters<typeof seedSpawnPromptMirror>): Promise<ReturnType<typeof seedSpawnPromptMirror>> {
+  return getGateway().write("lifecycleTail.seedSpawnPromptMirror", args) as unknown as Promise<ReturnType<typeof seedSpawnPromptMirror>>;
+}
+
+export function resolveQueuedPolicyMessagesAsync(...args: Parameters<typeof resolveQueuedPolicyMessages>): Promise<ReturnType<typeof resolveQueuedPolicyMessages>> {
+  return getGateway().write("lifecycleTail.resolveQueuedPolicyMessages", args) as unknown as Promise<ReturnType<typeof resolveQueuedPolicyMessages>>;
+}
+
+export function resolveQueuedDirectMessagesAsync(...args: Parameters<typeof resolveQueuedDirectMessages>): Promise<ReturnType<typeof resolveQueuedDirectMessages>> {
+  return getGateway().write("lifecycleTail.resolveQueuedDirectMessages", args) as unknown as Promise<ReturnType<typeof resolveQueuedDirectMessages>>;
+}
+
+export function resolveQueuedCoordinatorMessagesAsync(...args: Parameters<typeof resolveQueuedCoordinatorMessages>): Promise<ReturnType<typeof resolveQueuedCoordinatorMessages>> {
+  return getGateway().write("lifecycleTail.resolveQueuedCoordinatorMessages", args) as unknown as Promise<ReturnType<typeof resolveQueuedCoordinatorMessages>>;
+}
+
+export function updateManagedAgentStateAsync(...args: Parameters<typeof updateManagedAgentState>): Promise<ReturnType<typeof updateManagedAgentState>> {
+  return getGateway().write("lifecycleTail.updateManagedAgentState", args) as unknown as Promise<ReturnType<typeof updateManagedAgentState>>;
+}
+
+export function deleteWorkspaceAsync(...args: Parameters<typeof deleteWorkspace>): Promise<ReturnType<typeof deleteWorkspace>> {
+  return getGateway().write("lifecycleTail.deleteWorkspace", args) as unknown as Promise<ReturnType<typeof deleteWorkspace>>;
+}
+
+export function addSubscriptionAsync(...args: Parameters<typeof addSubscription>): Promise<ReturnType<typeof addSubscription>> {
+  return getGateway().write("lifecycleTail.addSubscription", args, { idempotencyKey: randomUUID() }) as unknown as Promise<ReturnType<typeof addSubscription>>;
+}
+
+export function removeSubscriptionAsync(...args: Parameters<typeof removeSubscription>): Promise<ReturnType<typeof removeSubscription>> {
+  return getGateway().write("lifecycleTail.removeSubscription", args) as unknown as Promise<ReturnType<typeof removeSubscription>>;
+}
+
+export function removeSubscriptionsForTaskAsync(...args: Parameters<typeof removeSubscriptionsForTask>): Promise<ReturnType<typeof removeSubscriptionsForTask>> {
+  return getGateway().write("lifecycleTail.removeSubscriptionsForTask", args) as unknown as Promise<ReturnType<typeof removeSubscriptionsForTask>>;
+}
+
+export function addSubscriptionsAsync(inputs: Array<Parameters<typeof addSubscription>[0]>): Promise<Array<ReturnType<typeof addSubscription>>> {
+  return getGateway().write("notifications.subscriptions.addBatch", { inputs }, { idempotencyKey: randomUUID() }) as unknown as Promise<Array<ReturnType<typeof addSubscription>>>;
+}
+
+export function upsertManagedAgentStateAsync(...args: Parameters<typeof import("../config-store").upsertManagedAgentState>): Promise<ReturnType<typeof import("../config-store").upsertManagedAgentState>> {
+  return getGateway().write("lifecycleTail.upsertManagedAgentState", args) as unknown as Promise<ReturnType<typeof import("../config-store").upsertManagedAgentState>>;
+}