@humwick/server 0.0.0-stage → 0.130.1

package/src/db/reply-obligations.ts

@@ -0,0 +1,265 @@
+import { humanAgentIdSql } from "./human-address";
+// #3054 — pending reply obligations as a disposable, trigger-maintained projection of messages and
+// message_reads (both stay authoritative). A read pays O(log pending + limit), never the agent's settled
+// history; triggers cover every write path except the message insert (#3060, see closeReplyObligationsOnInsert),
+// and a rule change rebuilds it.
+import { isHumanAgentId, MECHANICAL_MESSAGE_KINDS } from "@humwick/sdk";
+import { getDb } from "./connection.ts";
+import { replyCoversObligationSql } from "./report-suppression.ts";
+
+const VERSION_KEY = "reply-obligations";
+const MECHANICAL = MECHANICAL_MESSAGE_KINDS.map((kind) => `'${kind}'`).join(", ");
+
+/** `m` is a table alias; empty means the bare column, as an index expression requires. Payloads are always
+ *  JSON: the json_extract expression index on messages rejects any other write. */
+function payloadSql(m: string): string {
+  return m ? `${m}.payload` : "payload";
+}
+
+function nonBlankTextSql(m: string, path: string): string {
+  const doc = payloadSql(m);
+  return `CASE WHEN json_type(${doc}, '${path}') = 'text' AND trim(json_extract(${doc}, '${path}')) <> '' THEN json_extract(${doc}, '${path}') END`;
+}
+
+/** The relay conversation a message belongs to: replyContext.conversationId, else conversation.id (a non-blank string). */
+export function replyConversationSql(m: string): string {
+  return `COALESCE(${nonBlankTextSql(m, "$.replyContext.conversationId")}, ${nonBlankTextSql(m, "$.conversation.id")})`;
+}
+
+/** JS truthiness of payload.source, as messageCarriesReplyObligation reads it. */
+function sourceTruthySql(m: string): string {
+  const doc = payloadSql(m);
+  return `(CASE json_type(${doc}, '$.source') WHEN 'text' THEN json_extract(${doc}, '$.source') <> ''
+    WHEN 'integer' THEN json_extract(${doc}, '$.source') <> 0 WHEN 'real' THEN json_extract(${doc}, '$.source') <> 0
+    WHEN 'true' THEN 1 WHEN 'object' THEN 1 WHEN 'array' THEN 1 ELSE 0 END)`;
+}
+
+/** SQL form of the SDK's messageCarriesReplyObligation, for a recipient other than the sender. */
+export function replyObligationCandidateSql(m: string, agent: string): string {
+  return `(${m}.from_agent <> ${agent} AND ${m}.reply_expected <> 0 AND ${m}.kind NOT IN (${MECHANICAL})
+    AND (${humanAgentIdSql(`${m}.from_agent`)} OR ${m}.kind IN ('task', 'channel.event') OR ${sourceTruthySql(m)}))`;
+}
+
+/** The conversation key only counts on a non-blank channel. */
+function conversationKeySql(m: string): string {
+  return `CASE WHEN ${m}.channel <> '' THEN ${replyConversationSql(m)} END`;
+}
+
+export function directReplyCoversSql(m: string, agent: string): string {
+  return `EXISTS (SELECT 1 FROM messages reply WHERE reply.reply_to = ${m}.id AND reply.from_agent = ${agent} AND ${replyCoversObligationSql("reply")})`;
+}
+
+/** A later covering response from the agent in the same thread, or the same channel conversation. Both probes
+ *  are keyed equality seeks, so they visit only that thread's or conversation's rows from the agent. */
+export function laterResponseCoversSql(m: string, agent: string): string {
+  return `(EXISTS (SELECT 1 FROM messages later INDEXED BY idx_msg_thread_from_id
+      WHERE later.thread_id = ${m}.thread_id AND later.from_agent = ${agent} AND later.id > ${m}.id AND ${replyCoversObligationSql("later")})
+    OR EXISTS (SELECT 1 FROM messages later INDEXED BY idx_msg_reply_conversation
+      WHERE ${m}.channel <> '' AND later.channel <> '' AND later.channel = ${m}.channel
+        AND ${replyConversationSql("later")} IS NOT NULL AND ${replyConversationSql("later")} = ${conversationKeySql(m)}
+        AND later.from_agent = ${agent} AND later.id > ${m}.id AND ${replyCoversObligationSql("later")}))`;
+}
+
+function pendingSql(m: string, agent: string): string {
+  return `${replyObligationCandidateSql(m, agent)} AND NOT ${directReplyCoversSql(m, agent)} AND NOT ${laterResponseCoversSql(m, agent)}`;
+}
+
+const COLUMNS = "message_id, agent_id, created_at, thread_id, channel, conversation";
+const projectRow = (m: string, agent: string) => `${m}.id, ${agent}, ${m}.created_at, ${m}.thread_id, ${m}.channel, ${conversationKeySql(m)}`;
+
+// A response row `r` reaches the asks it settles by reply_to, by thread, or by channel conversation; each pass
+// is a keyed seek over that scope. Reopen re-derives them after `r` stops settling them; close drops what `r` now settles.
+const REOPEN_SCOPES: Array<{ from: string; key: (r: string) => string[]; where: (r: string) => string }> = [
+  { from: "messages m", key: (r) => [`${r}.reply_to`], where: (r) => `m.id = ${r}.reply_to` },
+  { from: "messages m INDEXED BY idx_msg_thread_from_id", key: (r) => [`${r}.thread_id`], where: (r) => `m.thread_id = ${r}.thread_id AND m.id < ${r}.id` },
+  { from: "messages m INDEXED BY idx_msg_reply_conversation", key: (r) => [`${r}.channel`, replyConversationSql(r)],
+    where: (r) => `${r}.channel <> '' AND m.channel <> '' AND m.channel = ${r}.channel
+      AND ${replyConversationSql("m")} IS NOT NULL AND ${replyConversationSql("m")} = ${replyConversationSql(r)} AND m.id < ${r}.id` },
+];
+
+function reopenPasses(r: string): Array<{ from: string; where: string }> {
+  return REOPEN_SCOPES.map((scope) => ({
+    from: scope.from,
+    where: `${replyCoversObligationSql(r)} AND ${scope.where(r)} AND ${pendingSql("m", `${r}.from_agent`)}`,
+  }));
+}
+
+/** Per reopen pass: does the update `before` → `after` remove that scope's coverage? Only then does the pass
+ *  run, so a change that keeps a scope (a root threading itself) never rescans its conversation. */
+export function reopenRemovedScopeSql(before: string, after: string): string[] {
+  const lost = `${before}.id IS NOT ${after}.id OR ${before}.from_agent IS NOT ${after}.from_agent OR NOT ${replyCoversObligationSql(after)}`;
+  return REOPEN_SCOPES.map((scope) => {
+    const [was, now] = [scope.key(before), scope.key(after)];
+    return `(${lost} OR ${was.map((key, i) => `${key} IS NOT ${now[i]}`).join(" OR ")})`;
+  });
+}
+
+function closeWheres(r: string): string[] {
+  const ro = "reply_obligations";
+  return [
+    `${ro}.agent_id = ${r}.from_agent AND ${ro}.message_id = ${r}.reply_to`,
+    `${ro}.agent_id = ${r}.from_agent AND ${ro}.thread_id = ${r}.thread_id AND ${ro}.message_id < ${r}.id`,
+    `${ro}.agent_id = ${r}.from_agent AND ${ro}.channel = ${r}.channel AND ${ro}.conversation = ${conversationKeySql(r)} AND ${ro}.message_id < ${r}.id`,
+  ].map((where) => `${where} AND ${replyCoversObligationSql(r)}`);
+}
+
+const readerJoin = (r: string) => `JOIN message_reads mr ON mr.message_id = m.id AND mr.agent_id = ${r}.from_agent`;
+
+/** Only a row that settled something reopens; `after` (an update's NEW) further limits each pass to the scopes the
+ *  update removed. The guard is a 0-or-1-row outer loop: SQLite does not hoist an OLD/NEW-only term out of a scan. */
+function reopenSql(r: string, after?: string): string {
+  const removed = after ? reopenRemovedScopeSql(r, after) : [];
+  return reopenPasses(r).map(({ from, where }, i) => `INSERT OR IGNORE INTO reply_obligations (${COLUMNS})
+    SELECT ${projectRow("m", `${r}.from_agent`)} FROM (SELECT 1 WHERE ${replyCoversObligationSql(r)}${removed[i] ? ` AND ${removed[i]}` : ""}) AS settled
+    CROSS JOIN ${from} ${readerJoin(r)} WHERE ${where};`).join("\n");
+}
+
+function closeSql(r: string): string {
+  return closeWheres(r).map((where) => `DELETE FROM reply_obligations WHERE ${where};`).join("\n");
+}
+
+/** Exported for the plan test: every response-driven trigger pass as a SELECT over a one-row table `r`. */
+export function responseTriggerPassesForPlan(r: string): string[] {
+  return [
+    ...reopenPasses(r).map(({ from, where }) => `SELECT m.id FROM ${r} CROSS JOIN ${from} ${readerJoin(r)} WHERE ${where}`),
+    ...closeWheres(r).map((where) => `SELECT message_id FROM ${r} CROSS JOIN reply_obligations WHERE ${where}`),
+  ];
+}
+
+function deriveForMessageSql(id: string): string {
+  return `INSERT OR IGNORE INTO reply_obligations (${COLUMNS})
+    SELECT ${projectRow("m", "mr.agent_id")} FROM message_reads mr JOIN messages m ON m.id = mr.message_id
+    WHERE mr.message_id = ${id} AND ${pendingSql("m", "mr.agent_id")};`;
+}
+
+const SEMANTIC_COLUMNS = ["id", "from_agent", "to_target", "kind", "reply_expected", "reply_to", "thread_id", "channel", "created_at"];
+const semanticChangeSql = `${SEMANTIC_COLUMNS.map((column) => `OLD.${column} IS NOT NEW.${column}`).join(" OR ")}
+  OR (OLD.payload IS NOT NEW.payload AND (${replyConversationSql("OLD")} IS NOT ${replyConversationSql("NEW")}
+    OR ${sourceTruthySql("OLD")} IS NOT ${sourceTruthySql("NEW")} OR ${replyCoversObligationSql("OLD")} IS NOT ${replyCoversObligationSql("NEW")}))`;
+
+const MESSAGE_INDEXES = [
+  `CREATE INDEX IF NOT EXISTS idx_msg_reply_conversation ON messages(channel, (${replyConversationSql("")}), from_agent, id)
+    WHERE channel <> '' AND ${replyConversationSql("")} IS NOT NULL`,
+];
+
+const PROJECTION_DDL = [
+  `CREATE TABLE reply_obligations (
+    message_id INTEGER NOT NULL, agent_id TEXT NOT NULL, created_at INTEGER NOT NULL,
+    thread_id INTEGER, channel TEXT, conversation TEXT,
+    PRIMARY KEY (message_id, agent_id)
+  ) WITHOUT ROWID`,
+  "CREATE INDEX idx_reply_obligations_order ON reply_obligations(agent_id, created_at, message_id)",
+  "CREATE INDEX idx_reply_obligations_thread ON reply_obligations(agent_id, thread_id, message_id) WHERE thread_id IS NOT NULL",
+  "CREATE INDEX idx_reply_obligations_conversation ON reply_obligations(agent_id, channel, conversation, message_id) WHERE conversation IS NOT NULL",
+  `CREATE TRIGGER trg_reply_obligations_read_insert AFTER INSERT ON message_reads BEGIN
+    INSERT OR IGNORE INTO reply_obligations (${COLUMNS}) SELECT ${projectRow("m", "NEW.agent_id")} FROM messages m
+    WHERE m.id = NEW.message_id AND ${pendingSql("m", "NEW.agent_id")};
+  END`,
+  `CREATE TRIGGER trg_reply_obligations_read_delete AFTER DELETE ON message_reads BEGIN
+    DELETE FROM reply_obligations WHERE message_id = OLD.message_id AND agent_id = OLD.agent_id;
+  END`,
+  `CREATE TRIGGER trg_reply_obligations_read_update AFTER UPDATE OF message_id, agent_id ON message_reads BEGIN
+    DELETE FROM reply_obligations WHERE message_id = OLD.message_id AND agent_id = OLD.agent_id;
+    INSERT OR IGNORE INTO reply_obligations (${COLUMNS}) SELECT ${projectRow("m", "NEW.agent_id")} FROM messages m
+    WHERE m.id = NEW.message_id AND ${pendingSql("m", "NEW.agent_id")};
+  END`,
+  `CREATE TRIGGER trg_reply_obligations_message_delete AFTER DELETE ON messages BEGIN
+    DELETE FROM reply_obligations WHERE message_id = OLD.id;
+    ${reopenSql("OLD")}
+  END`,
+  `CREATE TRIGGER trg_reply_obligations_message_update AFTER UPDATE OF ${[...SEMANTIC_COLUMNS, "payload"].join(", ")} ON messages
+  WHEN ${semanticChangeSql} BEGIN
+    DELETE FROM reply_obligations WHERE message_id IN (OLD.id, NEW.id);
+    ${reopenSql("OLD", "NEW")}
+    ${closeSql("NEW")}
+    ${deriveForMessageSql("NEW.id")}
+  END`,
+];
+
+// #3060 — retired: any AFTER INSERT trigger on messages costs every send a statement journal; the rebuild drops it.
+const RETIRED_TRIGGERS = ["trg_reply_obligations_message_insert"];
+const TRIGGERS = [...RETIRED_TRIGGERS, ...PROJECTION_DDL.flatMap((ddl) => /^CREATE TRIGGER (\w+)/.exec(ddl)?.[1] ?? [])];
+
+/** Every pending (message, agent) pair, derived from the source tables only. */
+const REPLY_OBLIGATION_SOURCE_SQL = `SELECT ${projectRow("m", "mr.agent_id")}
+  FROM message_reads mr JOIN messages m ON m.id = mr.message_id WHERE ${pendingSql("m", "mr.agent_id")}`;
+
+/** Any change to the rules, indexes or triggers changes this, and the next start rebuilds the projection. */
+export const REPLY_OBLIGATIONS_VERSION = Bun.hash([...MESSAGE_INDEXES, ...PROJECTION_DDL, REPLY_OBLIGATION_SOURCE_SQL].join("\n")).toString(36);
+
+/** Drop and re-derive the projection from messages and message_reads, in one transaction. */
+export function rebuildReplyObligations(): void {
+  const db = getDb();
+  db.transaction(() => {
+    for (const trigger of TRIGGERS) db.run(`DROP TRIGGER IF EXISTS ${trigger}`);
+    db.run("DROP TABLE IF EXISTS reply_obligations");
+    db.run("DROP INDEX IF EXISTS idx_msg_reply_conversation");
+    for (const ddl of [...MESSAGE_INDEXES, ...PROJECTION_DDL]) db.run(ddl);
+    db.run(`INSERT INTO reply_obligations (${COLUMNS}) ${REPLY_OBLIGATION_SOURCE_SQL}`);
+    db.query(`INSERT INTO config (namespace, key, value, version, updated_at, updated_by) VALUES ('_migration', ?, ?, 1, ?, 'migration')
+      ON CONFLICT (namespace, key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`)
+      .run(VERSION_KEY, JSON.stringify({ version: REPLY_OBLIGATIONS_VERSION }), new Date().toISOString());
+  }).immediate();
+}
+
+/** Startup, after every source migration and backfill, before the server binds. A crash mid-build rolls back
+ *  with its marker, so the next start rebuilds. */
+export function installReplyObligations(): boolean {
+  const marker = getDb().query("SELECT value FROM config WHERE namespace = '_migration' AND key = ?").get(VERSION_KEY) as { value: string } | null;
+  const installed = marker ? (JSON.parse(marker.value) as { version?: string }).version : undefined;
+  if (installed === REPLY_OBLIGATIONS_VERSION) return false;
+  rebuildReplyObligations();
+  return true;
+}
+
+const CLOSE_ON_INSERT_SQL = `DELETE FROM reply_obligations WHERE (message_id, agent_id) IN (${closeWheres("r")
+  .map((where) => `SELECT reply_obligations.message_id, reply_obligations.agent_id FROM messages r CROSS JOIN reply_obligations WHERE r.id = ? AND ${where}`)
+  .join(" UNION ALL ")})`;
+
+/** #3060 — the close a new message owes, run by the one message INSERT (src/db/messages.ts) in its transaction.
+ *  An AFTER INSERT trigger makes every insert open a statement journal (~27 dirty pages, spilled to a temp file),
+ *  which doubled the send write. `threadId` is the inherited thread: a root's own new id is named by no earlier row,
+ *  so a root outside a channel settles nothing. */
+export function closeReplyObligationsOnInsert(row: { id: number; from: string; replyTo: number | null; threadId: number | null; channel: string | null }): void {
+  if (row.replyTo === null && row.threadId === null && !row.channel) return;
+  const db = getDb();
+  if (!db.query("SELECT 1 FROM reply_obligations WHERE agent_id = ? LIMIT 1").get(row.from)) return;
+  db.query(CLOSE_ON_INSERT_SQL).run(row.id, row.id, row.id);
+}
+
+/** Re-derive one (message, agent) pair from the source tables: the repair for a parity mismatch. */
+export function reconcileReplyObligation(messageId: number, agentId: string): void {
+  const db = getDb();
+  db.query("DELETE FROM reply_obligations WHERE message_id = ? AND agent_id = ?").run(messageId, agentId);
+  db.query(`INSERT OR IGNORE INTO reply_obligations (${COLUMNS}) SELECT ${projectRow("m", "mr.agent_id")}
+    FROM message_reads mr JOIN messages m ON m.id = mr.message_id
+    WHERE mr.message_id = ? AND mr.agent_id = ? AND ${pendingSql("m", "mr.agent_id")}`).run(messageId, agentId);
+}
+
+export type ReplyObligationDrift = { messageId: number; agentId: string; kind: "missing" | "stale" };
+
+/** Both directions in ONE statement, so one read snapshot. O(reads + probes): run it off the loop, rarely.
+ *  MATERIALIZED: SQLite otherwise inlines the CTE as one co-routine per use and pays the full source scan twice (#3733). */
+export const REPLY_OBLIGATION_PARITY_SQL = `
+  WITH source AS MATERIALIZED (SELECT m.id AS message_id, mr.agent_id FROM message_reads mr JOIN messages m ON m.id = mr.message_id
+    WHERE ${pendingSql("m", "mr.agent_id")})
+  SELECT message_id AS messageId, agent_id AS agentId, 'missing' AS kind FROM (SELECT * FROM source EXCEPT SELECT message_id, agent_id FROM reply_obligations)
+  UNION ALL
+  SELECT message_id, agent_id, 'stale' FROM (SELECT message_id, agent_id FROM reply_obligations EXCEPT SELECT * FROM source)
+  LIMIT ?`;
+
+/** The read branch: the agent's oldest pending obligations, hydrated by primary key. */
+export const PENDING_READ_OBLIGATIONS_FROM = `FROM reply_obligations ro INDEXED BY idx_reply_obligations_order
+  CROSS JOIN messages m ON m.id = ro.message_id WHERE ro.agent_id = ? ORDER BY ro.created_at, ro.message_id LIMIT ?`;
+
+/** The unread branch: asks addressed to the agent since `floor`, settled in SQL so LIMIT never hides one. */
+export function pendingAddressedObligationsFrom(agentId: string): string {
+  const direct = isHumanAgentId(agentId)
+    ? `EXISTS (SELECT 1 FROM messages reply WHERE (reply.reply_to = m.id OR (reply.id > m.id AND reply.to_target = m.from_agent))
+        AND reply.from_agent = ?3 AND ${replyCoversObligationSql("reply")})`
+    : directReplyCoversSql("m", "?3");
+  return `FROM messages m INDEXED BY idx_msg_to_id
+    WHERE m.to_target = ?3 AND m.id > ?1 AND m.created_at >= ?2 AND m.reply_expected = 1 AND ${replyObligationCandidateSql("m", "?3")}
+      AND NOT ${direct} AND NOT ${laterResponseCoversSql("m", "?3")}
+    ORDER BY m.id LIMIT ?4`;
+}

package/src/db/report-suppression.ts

@@ -0,0 +1,126 @@
+import { humanAgentIdSql } from "./human-address";
+// #2831 — a turn-final captured while the sender waits on its own relay_run is not a report. Decided
+// ONCE in the capture writer transaction and persisted as `payload.reportSuppression`, so lineage
+// hold/flush, startup recovery, outbox retries and obligation coverage read the stored fact instead
+// of re-deciding. The completion wake resumes the agent; only its next final goes up.
+import { isMechanicalMessageKind, isRecord, isTurnFinalSession, parseJson, stringValue, type MessageReportSuppression } from "@humwick/sdk";
+import { getDb } from "./connection.ts";
+import { currentCoordinatorOf } from "./coordinator-seat.ts";
+import { pendingOwnRelayRuns, pendingOwnRelayRunIds } from "./pending-relay-runs.ts";
+import type { AgentCard, Message, ReplyObligation, SendMessageInput } from "../types";
+
+export const REPORT_SUPPRESSION_REASON = "report suppressed (#2831): the sender was waiting on its own pending relay_run";
+
+type CaptureInput = Pick<SendMessageInput, "to" | "payload" | "replyTo"> & { messageType?: string };
+
+type AutomaticCapture = { kind: "mirror" | "report"; meta: Record<string, unknown> };
+
+/** `mirror` — the session-mirror turn-final every provider writes; `report` — the runner's direct
+ * captured reply to an obligation originator. The server's own lineage forward (`final-turn`) is
+ * derived from an already-decided mirror and is never re-decided. */
+function automaticCapture(input: CaptureInput, kind: Message["kind"]): AutomaticCapture | null {
+  const payload = input.payload;
+  if (kind === "session") {
+    const session = isRecord(payload?.session) ? payload.session : undefined;
+    return session?.type === "response" && isTurnFinalSession(session) ? { kind: "mirror", meta: session } : null;
+  }
+  if (kind !== "chat" || input.messageType === "final-turn") return null;
+  const capture = isRecord(payload?.responseCapture) ? payload.responseCapture : undefined;
+  return capture && isTurnFinalSession(capture) ? { kind: "report", meta: capture } : null;
+}
+
+// The runner writes a turn's mirror immediately before its direct report; a run settling between the
+// two writes must not split the decision. Bounded to the sender's newest session rows.
+export const MIRROR_LOOKBACK_ROWS = 200;
+
+/** The persisted decision of the same turn's mirror: `null` when no mirror exists yet. */
+function mirrorDecision(senderId: string, turnId: string): { suppression?: MessageReportSuppression } | null {
+  const row = getDb().query(`
+    SELECT payload FROM (
+      SELECT id, payload FROM messages
+      WHERE from_agent = ? AND kind = 'session' ORDER BY id DESC LIMIT ${MIRROR_LOOKBACK_ROWS}
+    )
+    WHERE json_extract(payload, '$.session.type') = 'response'
+      AND json_extract(payload, '$.session.turnId') = ?
+      AND (json_extract(payload, '$.session.turnFinal') = 1 OR json_extract(payload, '$.session.final') = 1)
+    ORDER BY id DESC LIMIT 1
+  `).get(senderId, turnId) as { payload: string } | null;
+  if (!row) return null;
+  const suppression = parseJson<Record<string, unknown>>(row.payload, {}).reportSuppression;
+  return isRecord(suppression) ? { suppression: suppression as unknown as MessageReportSuppression } : {};
+}
+
+/** #2840 — the coordinator's ANSWER, not an unsolicited report-up: its question was addressed to this agent
+ * AFTER every pending run started, so the answering turn started none of them. The runner stamps the turn's
+ * opener (`answersMessageId`); the row must agree, so a forged stamp proves nothing. Returns the question. */
+function questionAskedDuringRuns(input: CaptureInput, capture: AutomaticCapture, senderId: string, coordinator: string, runs: Array<{ startedAt: number }>): number | undefined {
+  if (!input.replyTo || input.to !== coordinator || capture.meta.answersMessageId !== input.replyTo) return undefined;
+  const asked = getDb().query(`
+    SELECT m.kind, m.created_at FROM messages m
+    WHERE m.id = ? AND m.from_agent = ? AND m.reply_expected = 1 AND (m.to_target = ? OR m.resolved_to_agent = ?)
+  `).get(input.replyTo, coordinator, senderId, senderId) as { kind: Message["kind"]; created_at: number } | null;
+  return asked && !isMechanicalMessageKind(asked.kind) && runs.every((run) => asked.created_at > run.startedAt) ? input.replyTo : undefined;
+}
+
+/** `suppression` — persist on the capture. `answers` — the question the capture answers during a pending
+ * run; the writer records it read in the insert transaction, since the capture proves it was consumed. */
+export type ReportDecision = { suppression?: MessageReportSuppression; answers?: number };
+
+export function decideReportSuppression(
+  input: CaptureInput,
+  kind: Message["kind"],
+  sender: AgentCard | null,
+  now: number,
+): ReportDecision {
+  const capture = automaticCapture(input, kind);
+  if (!capture || !sender) return {};
+  const coordinator = currentCoordinatorOf(sender);
+  if (!coordinator) return {};
+  // Every mirror feeds the lineage hold; a runner report only matters when it targets the coordinator
+  // (a peer's obligation reply is not a report-up). #2844 — the mirror is transcript-only, so an
+  // answering report is decided on its own stamp FIRST: it must deliver even though its mirror
+  // stays suppressed. Only a report that answers nothing inherits its turn's mirror decision.
+  const runs = pendingOwnRelayRuns(sender, now);
+  if (capture.kind === "report") {
+    if (input.to !== coordinator) return {};
+    if (runs.length > 0) {
+      const reportAnswers = questionAskedDuringRuns(input, capture, sender.id, coordinator, runs);
+      if (reportAnswers) return { answers: reportAnswers };
+    }
+    const turnId = stringValue(capture.meta.turnId);
+    const mirror = turnId ? mirrorDecision(sender.id, turnId) : null;
+    if (mirror) return mirror;
+  }
+  if (runs.length === 0) return {};
+  const answers = questionAskedDuringRuns(input, capture, sender.id, coordinator, runs);
+  return answers ? { answers } : { suppression: { reason: "pending-relay-run", runIds: runs.map((run) => run.id), decidedAt: now } };
+}
+
+export function isReportSuppressed(message: Pick<Message, "payload">): boolean {
+  return isRecord(message.payload?.reportSuppression);
+}
+
+/** SQL guard for reply-coverage reads: a suppressed capture never answers the coordinator — not
+ * even a transcript-only (`user`-addressed) session mirror (#2844 r1: the mirror carries the
+ * opener's replyTo but the run is still pending, so the obligation must stay open). The one
+ * exception is a suppressed mirror answering a HUMAN prompt (`from_agent` is human): the human
+ * reads the dashboard transcript, so that prompt is settled even while a run pends. */
+export function replyCoversObligationSql(alias: string): string {
+  return `(${notReportSuppressedSql(alias)} OR (${humanAgentIdSql(`${alias}.to_target`)} AND (${alias}.kind <> 'session' OR EXISTS (SELECT 1 FROM messages m WHERE m.id = ${alias}.reply_to AND ${humanAgentIdSql("m.from_agent")}))))`;
+}
+
+/** SQL guard for every semantic/body dedupe: a suppressed capture is never "the same message" as a
+ * later explicit send or a later turn's final. Same-key retries still dedupe on the idempotency key. */
+export function notReportSuppressedSql(alias: string): string {
+  return `json_extract(${alias}.payload, '$.reportSuppression') IS NULL`;
+}
+
+/** The coordinator's open obligations stay open while the agent waits on its own relay_run; this only
+ * marks them so the runner's automatic nags do not push a "still waiting" reply past the suppression. */
+export function markNagDeferral(agent: AgentCard | null, obligations: ReplyObligation[], now: number = Date.now()): ReplyObligation[] {
+  if (!agent || obligations.length === 0) return obligations;
+  const coordinator = currentCoordinatorOf(agent);
+  if (!coordinator || !obligations.some((obligation) => obligation.from === coordinator)) return obligations;
+  if (pendingOwnRelayRunIds(agent, now).length === 0) return obligations;
+  return obligations.map((obligation) => obligation.from === coordinator ? { ...obligation, nagDeferral: "pending-relay-run" as const } : obligation);
+}

package/src/db/restart-epoch-admin-async.ts

@@ -0,0 +1,14 @@
+// #2189 P7 — the async facade for EXPLICIT admin recovery, deliberately in its own module.
+//
+// It is not in restart-epoch-async.ts because that module is on the normal drain path, and importing
+// it there would hand the drain a reference to a cancel-capable op. Capability separation only works
+// if the facade layer respects it too — see src/restart-epoch-drain-capability.test.ts.
+
+import { getGateway } from "./gateway.ts";
+import type { AdminCancelExecutionArgs, AdminCancelExecutionResult } from "./restart-epoch-admin.ts";
+
+export function adminCancelRestartEpochExecutionAsync(args: AdminCancelExecutionArgs): Promise<AdminCancelExecutionResult> {
+  return getGateway().write(
+    "restartEpoch.adminCancelExecution" as never, args as never, { idempotencyKey: args.requestId },
+  ) as unknown as Promise<AdminCancelExecutionResult>;
+}

package/src/db/restart-epoch-admin.ts

@@ -0,0 +1,67 @@
+// #2189 P7 — EXPLICIT ADMIN RECOVERY. Deliberately the only place in the restart-epoch feature that
+// can cancel a command, and deliberately in its own module.
+//
+// The separation is the design, not bookkeeping. #2178 was a drain that killed healthy work; the fix
+// is not "be careful in the drain", it is that the drain has no cancellation capability to misuse.
+// Normal drain — restart-epoch.ts, restart-epoch-release.ts, restart-epoch-admission.ts and the
+// driver — never imports this module and never names its op. src/restart-epoch-drain-capability.test.ts
+// asserts exactly that, structurally, so a future edit cannot quietly reintroduce the coupling.
+//
+// Reaching this op requires a human-supplied actor and reason, and it is fenced on the command's
+// CURRENT execution generation: an operator cancelling "the stuck execution" cannot land that
+// cancellation on the retry that started while they were deciding.
+
+import { ValidationError } from "@humwick/sdk";
+import { getDb } from "./connection.ts";
+import { restartEpochById } from "./restart-epoch.ts";
+
+export interface AdminCancelExecutionArgs {
+  readonly epochId: string;
+  readonly commandId: string;
+  /** The execution the operator actually looked at. A newer generation rejects the cancel. */
+  readonly executionGeneration: number;
+  readonly expectedVersion: number;
+  readonly actor: string;
+  readonly reason: string;
+  readonly requestId: string;
+}
+
+export interface AdminCancelExecutionResult {
+  readonly canceled: boolean;
+  readonly reason?: string;
+}
+
+/**
+ * Cancel ONE unhealthy execution, by explicit operator action, against a named epoch.
+ *
+ * Every guard here exists because the alternative is the #2178 failure: cancelling work that was
+ * fine. The epoch must exist and be open; the caller must name its current version; the command must
+ * still be executing at the exact generation the operator observed.
+ */
+export function adminCancelExecutionBody(args: AdminCancelExecutionArgs, now: number): AdminCancelExecutionResult {
+  if (!args.actor.trim() || !args.reason.trim()) {
+    throw new ValidationError("admin execution cancellation requires an explicit actor and reason");
+  }
+  const replay = getDb().query(
+    "SELECT 1 FROM restart_epoch_audit WHERE epoch_id = ? AND event = 'admin-cancel-execution' AND request_id = ?",
+  ).get(args.epochId, args.requestId);
+  if (replay) return { canceled: true };
+
+  const epoch = restartEpochById(args.epochId);
+  if (!epoch) return { canceled: false, reason: "epoch-missing" };
+  if (epoch.state === "released") return { canceled: false, reason: "epoch-released" };
+  if (epoch.owner_version !== args.expectedVersion) return { canceled: false, reason: "epoch-version-changed" };
+
+  const changes = getDb().query(
+    `UPDATE commands SET status = 'canceled', error = ?, updated_at = ?
+     WHERE id = ? AND status IN ('accepted', 'running') AND execution_generation = ?`,
+  ).run(`admin-recovery: ${args.reason}`, now, args.commandId, args.executionGeneration).changes;
+  if (changes === 0) return { canceled: false, reason: "generation-fence-lost" };
+
+  getDb().query(
+    `INSERT OR IGNORE INTO restart_epoch_audit (epoch_id, event, actor, request_id, detail, created_at)
+     VALUES (?, 'admin-cancel-execution', ?, ?, ?, ?)`,
+  ).run(args.epochId, args.actor, args.requestId,
+    JSON.stringify({ commandId: args.commandId, executionGeneration: args.executionGeneration, reason: args.reason }), now);
+  return { canceled: true };
+}

package/src/db/restart-epoch-admission.ts

@@ -0,0 +1,114 @@
+// #2189 P7 — the create/claim admission seam.
+//
+// This is the whole point of the epoch, and it is deliberately tiny: ONE indexed point read — the
+// open epoch of the command target's Host, or a fleet epoch (#2988) — that every restart-sensitive
+// command create and every pending→accepted claim performs INSIDE its own writer transaction.
+//
+// "Inside" is not a style preference. A pre-read — check the epoch, await, then insert — is a
+// cross-await TOCTOU: the epoch can open in the gap and the command lands admitted into a sealed
+// epoch, which is precisely the leak the spec's create-request-seal and claim-request-seal
+// linearizability tests enumerate. Because SQLite serializes writers, doing the read in the same
+// transaction as the write makes the two orderings the ONLY two possible outcomes: either the create
+// commits before the epoch opens (and `beginWithDrain`'s parking sweep catches it), or it sees the
+// epoch and parks itself. There is no third interleaving.
+
+import { openRestartEpochForTarget, type RestartEpochRow } from "./restart-epoch.ts";
+import { isRestartSensitiveCommandType, PRE_REGISTRATION_SPAWN_TYPE } from "./restart-sensitive.ts";
+import { targetRunsRestartImmuneLandBodies } from "./target-host.ts";
+import type { CreateCommandInput } from "../types.ts";
+
+/**
+ * #2369 — is this type currently exempt from parking?
+ *
+ * A spawn is exempt while the epoch's own seal has recorded that an unrelated LAND GATE is what
+ * makes quiescence impossible (see `assessQuiescence`). The exemption costs nothing extra here: the
+ * flag rides on the single-row epoch read the seam already performs.
+ *
+ * WHY THIS IS SAFE. It does not weaken the deploy gate by one inch. Sealing still requires that NO
+ * restart-sensitive work — spawns included — is in flight, so a spawn admitted here still blocks the
+ * seal exactly as before, and the deploy still launches only from `quiesced`. All that changes is
+ * that the fleet stops being frozen through a window in which quiescence was unreachable anyway.
+ *
+ * WHY IT CONVERGES. New land gates keep parking (and their claims keep being refused), so the gate
+ * that holds the epoch is the LAST one: when it ends, no successor can have started. The flag then
+ * clears on the next seal attempt, spawns park again, and the epoch drains a population whose
+ * lifetime is bounded by registration — seconds, not a test suite.
+ *
+ * The `requested` guard is belt-and-braces: past that state the deploy is imminent and everything
+ * parks, whatever a stale flag says.
+ */
+function admissionDeferred(epoch: RestartEpochRow, type: string): boolean {
+  return type === PRE_REGISTRATION_SPAWN_TYPE
+    && epoch.state === "requested"
+    && epoch.spawn_admission_deferred === 1;
+}
+
+/**
+ * #2990 — a `workspace.merge` aimed at a host that runs land bodies in their own transient unit is not
+ * restart-sensitive: an orchestrator restart neither kills it nor needs to wait for it. Only the type
+ * that is actually re-homed is exempt; `landing.*` still run inside the orchestrator unit.
+ */
+function restartSensitiveFor(type: string, target: string): boolean {
+  return isRestartSensitiveCommandType(type) && !(type === "workspace.merge" && targetRunsRestartImmuneLandBodies(target));
+}
+
+/** #2672 — the epoch holding `target`'s Host. One that has settled is only draining what it parked: a
+ *  row parked after its last release page would strand there, and its spawn would wait forever. */
+function holdingEpoch(target: string): RestartEpochRow | null {
+  const epoch = openRestartEpochForTarget(target);
+  return epoch?.release_state === null ? epoch : null;
+}
+
+/** What a create must stamp on the row it is about to insert. */
+export interface RestartEpochCreateAdmission {
+  readonly admission: "parked";
+  readonly blockedByEpochId: string;
+}
+
+/**
+ * Should this create be parked? Returns null — meaning "carry on, admit normally" — for a
+ * non-restart-sensitive type, for a dry-run create (which actuates nothing a restart could destroy),
+ * and whenever no epoch holds the target's Host.
+ */
+export function restartEpochCreateAdmission(
+  type: string, currentAdmission: "admitted" | "parked" | "dry-run" | undefined, target: string,
+): RestartEpochCreateAdmission | null {
+  if (currentAdmission === "dry-run" || currentAdmission === "parked") return null;
+  if (!restartSensitiveFor(type, target)) return null;
+  const epoch = holdingEpoch(target);
+  if (!epoch) return null;
+  if (admissionDeferred(epoch, type)) return null;
+  return { admission: "parked", blockedByEpochId: epoch.id };
+}
+
+/**
+ * Apply {@link restartEpochCreateAdmission} to a create input. Every restart-sensitive create path
+ * funnels through this one call rather than repeating the spread — a second copy of "stamp parked +
+ * blockedByEpochId" is how one create path would end up admitting into a sealed epoch.
+ */
+export function withRestartEpochAdmission(input: CreateCommandInput): CreateCommandInput {
+  const parked = restartEpochCreateAdmission(input.type, input.admission, input.target);
+  if (!parked) {
+    // A restart-sensitive type still has to CARRY its classification, or the epoch's parking sweep
+    // and every seal check would be blind to it.
+    return restartSensitiveFor(input.type, input.target) && !input.restartSensitive
+      ? { ...input, restartSensitive: true } : input;
+  }
+  return { ...input, restartSensitive: true, admission: parked.admission, blockedByEpochId: parked.blockedByEpochId };
+}
+
+/**
+ * Is a pending→accepted claim currently refused? Returns the blocking epoch id, or null.
+ *
+ * Claim refusal is what keeps "accepted/running work continues untouched" honest: work that already
+ * holds an execution is left completely alone, and only the transition INTO execution is closed.
+ */
+export function restartEpochBlockingClaim(commandType: string, target: string): string | null {
+  if (!restartSensitiveFor(commandType, target)) return null;
+  const epoch = holdingEpoch(target);
+  if (!epoch) return null;
+  // The claim has to honour the SAME deferral as the create, or the exemption is theatre: the spawn
+  // would be admitted, polled, and then refused at the one transition that actually starts it.
+  if (admissionDeferred(epoch, commandType)) return null;
+  return epoch.id;
+}