@staix/agent-hub 0.20.0 → 0.22.0

package/src/hub/deliverable-files.ts

@@ -1,10 +1,12 @@
 import { constants, lstatSync, type Stats } from "node:fs";
 import { open } from "node:fs/promises";
 import { createHash } from "node:crypto";
-import { relative } from "node:path";
+import { relative, resolve } from "node:path";
 import { guardPath } from "../local/tools.ts";
+import { isDenied } from "../local/deny.ts";
 import { isHubWritePath } from "./permission-mode.ts";
 import { realPath } from "./project.ts";
+import { insideRoot } from "./path-policy.ts";
 import { DELIVERABLE_LIMITS, deliverableId, type DeliverableClaim, type DeliverableRecord, type DeliverableState } from "./deliverables.ts";
 
 /**
@@ -49,7 +51,11 @@ function locate(path: string, ports: DeliverablePorts): Located {
   // git file ever reaches a record (a hash of a low-entropy file confirms guesses). Compared on the resolved path, folded like the write guard.
   let root: string;
   try { root = realPath(ports.cwd); } catch { return refuse(path, "the project root cannot be resolved"); }
-  if (isHubWritePath(relative(root, real))) return refuse(path, "the hub's own state is not a deliverable");
+  // Judged on the resolved name and on the name the caller gave (#552, the #541 class): Bun's realpath can name another hardlink of the same file.
+  const typed = relative(root, resolve(root, path));
+  const inside = insideRoot(typed);
+  if (isHubWritePath(relative(root, real)) || inside && isHubWritePath(typed)) return refuse(path, "the hub's own state is not a deliverable");
+  if (inside && isDenied(typed, [...ports.deny])) return refuse(path, "the path is on the secrets denylist");
   let stat: Stats;
   try { stat = lstatSync(real); }
   catch (error) { return refuse(path, (error as NodeJS.ErrnoException).code === "ENOENT" ? "the file does not exist" : "the file cannot be read"); }

package/src/hub/delivery-journal.ts

@@ -2,10 +2,12 @@ import { chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { Database } from "bun:sqlite";
 import type { BusSnapshot } from "./bus.ts";
+import type { QueuePressure } from "./queue-backpressure.ts";
 import { HUB, USER, type Envelope, type Kind } from "./envelope.ts";
 import { heldDeliveryHints } from "./delivery-hints.ts";
 import { processLiveness } from "../pi/process-signature.ts";
 import { HUB_DB_BUSY_TIMEOUT_MS } from "./db-timeout.ts";
+import { parseRemotePeerId } from "../rooms/application.ts";
 import { validateDeferredHub } from "./deferred-hub.ts";
 
 export type JournalDeliveryState =
@@ -18,8 +20,8 @@ export type JournalDeliveryState =
   | "discarded";
 export type JournalResolution = "completed" | "retry" | "discard";
 export const MAX_ENVELOPE_BODY = 1_000_000;
+export const TERMINAL_CAP = 2048;
 const SCHEMA_VERSION = 1,
-  TERMINAL_CAP = 2048,
   MAX_ROWS = 100_000,
   MAX_JSON = 20 * 1024 * 1024;
 const STATES = new Set<JournalDeliveryState>([
@@ -54,6 +56,8 @@ export interface DeliveryJournalOptions {
   projectId: string;
   instanceId: string;
   operationId?: string;
+  /** Accepted live history target; only terminal mutations apply it, other pruning keeps the legacy cap. */
+  terminalHistoryLimit?: () => number;
 }
 export interface JournalSnapshot {
   schemaVersion: number;
@@ -168,6 +172,32 @@ function validateBus(value: unknown, name = "bus"): BusSnapshot {
     list(b.manualPaused, `${name}.manualPaused`, 4096).forEach((id) =>
       text(id, `${name}.manualPaused[]`, 256),
     );
+  if (b.remoteQueueMembers !== undefined) {
+    const members = obj(b.remoteQueueMembers, `${name}.remoteQueueMembers`);
+    if (Object.keys(members).length > 12800) fail(`${name}.remoteQueueMembers is too large`);
+    for (const [peer, member] of Object.entries(members)) {
+      if (!parseRemotePeerId(peer) || !Array.isArray(queues[peer]) || typeof member !== "string" || !/^[0-9a-f]{64}$/.test(member)) fail(`${name}.remoteQueueMembers is invalid`);
+    }
+  }
+  if (b.remoteQueueRooms !== undefined) {
+    const rooms = obj(b.remoteQueueRooms, `${name}.remoteQueueRooms`);
+    if (Object.keys(rooms).length > 12800) fail(`${name}.remoteQueueRooms is too large`);
+    for (const [peer, room] of Object.entries(rooms)) {
+      if (!parseRemotePeerId(peer) || !Array.isArray(queues[peer])) fail(`${name}.remoteQueueRooms key is invalid`);
+      text(room, `${name}.remoteQueueRooms room`, 256);
+    }
+  }
+  if (b.remoteQueueExpires !== undefined) {
+    const expiries = obj(b.remoteQueueExpires, `${name}.remoteQueueExpires`);
+    if (Object.keys(expiries).length > 4096) fail(`${name}.remoteQueueExpires is too large`);
+    let count = 0;
+    for (const [peer, values] of Object.entries(expiries)) {
+      if (!parseRemotePeerId(peer)) fail(`${name}.remoteQueueExpires key is invalid`);
+      const entries = Object.entries(obj(values, `${name}.remoteQueueExpires.${peer}`));
+      if (entries.length > 200 || (count += entries.length) > 12800) fail(`${name}.remoteQueueExpires is too large`);
+      for (const [id, expiry] of entries) { text(id, `${name}.remoteQueueExpires id`, 256); integer(expiry, `${name}.remoteQueueExpires expiry`); }
+    }
+  }
   const occupied = new Set<string>([
     ...(b.seen as Envelope[]).map(env => env.id),
     ...Object.values(queues).flatMap(items => (items as Envelope[]).map(env => env.id)),
@@ -241,13 +271,18 @@ export class DeliveryJournal {
   readonly instanceId: string;
   private readonly db: Database;
   private closed = false;
+  private queueMetadataTracking = false;
+  private queueMetadataInvalidated = false;
+  private pruningDeferred = 0;
   private readonly operationId?: string;
+  private readonly terminalHistoryLimit?: () => number;
   constructor(options: DeliveryJournalOptions) {
     this.file = options.file;
     this.projectRoot = text(options.projectRoot, "projectRoot", 4096);
     this.projectId = text(options.projectId, "projectId", 256);
     this.instanceId = text(options.instanceId, "instanceId", 256);
     this.operationId = options.operationId;
+    this.terminalHistoryLimit = options.terminalHistoryLimit;
     mkdirSync(dirname(options.file), { recursive: true, mode: 0o700 });
     this.db = new Database(options.file, { create: true });
     this.db.run(`PRAGMA busy_timeout = ${HUB_DB_BUSY_TIMEOUT_MS}`);
@@ -323,6 +358,8 @@ export class DeliveryJournal {
     this.db.run(
       `CREATE TABLE IF NOT EXISTS deliveries (id TEXT PRIMARY KEY, project_id TEXT NOT NULL, peer TEXT NOT NULL, state TEXT NOT NULL, revision INTEGER NOT NULL, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, originals TEXT NOT NULL, out_json TEXT NOT NULL, reason TEXT, attempt INTEGER, previous_id TEXT)`,
     );
+    this.db.run("CREATE TABLE IF NOT EXISTS delivery_queue_meta_state (project_id TEXT PRIMARY KEY, revision INTEGER NOT NULL)");
+    this.db.run("CREATE TABLE IF NOT EXISTS delivery_queue_meta (project_id TEXT NOT NULL, peer TEXT NOT NULL, queued INTEGER NOT NULL, oldest_at INTEGER, unknown_age INTEGER NOT NULL, PRIMARY KEY(project_id,peer))");
     this.db.run("CREATE TABLE IF NOT EXISTS task_offer_reads (project_id TEXT NOT NULL, peer TEXT NOT NULL, envelope_id TEXT NOT NULL, delivery_id TEXT NOT NULL, source TEXT NOT NULL CHECK(source IN ('adapter','reply','pull')), offer_revision INTEGER NOT NULL CHECK(offer_revision >= 1), PRIMARY KEY(project_id,peer,envelope_id))");
     this.db.run(
       `CREATE TABLE IF NOT EXISTS resolution_history (id INTEGER PRIMARY KEY AUTOINCREMENT, project_id TEXT NOT NULL, delivery_id TEXT NOT NULL, observed_revision INTEGER NOT NULL, action TEXT NOT NULL, reason TEXT NOT NULL, result_revision INTEGER NOT NULL, result_state TEXT NOT NULL, UNIQUE(project_id, delivery_id, observed_revision, action, reason))`,
@@ -474,11 +511,71 @@ export class DeliveryJournal {
       ) !== 1
     )
       throw new Error("delivery journal instance fence lost");
+    // New writers carry unchanged summary provenance across non-queue revisions.
+    // An older writer does not, so its next revision makes these rows unknown.
+    if (this.queueMetadataTracking) this.db.query("UPDATE delivery_queue_meta_state SET revision=? WHERE project_id=? AND revision=?")
+      .run(revision, this.projectId, revision - 1);
     return revision;
   }
+
+  /** Atomically accompanies the bus snapshot, never extracts body JSON on a periodic path. */
+  private writeQueueMetadata(bus: BusSnapshot, revision: number, tracking: boolean): void {
+    if (!tracking) {
+      // Invalidate once per disabled period; ordinary revisions already stale old summaries.
+      if (!this.queueMetadataInvalidated) {
+        this.db.query("UPDATE delivery_queue_meta_state SET revision=-1 WHERE project_id=? AND revision>=0").run(this.projectId);
+        this.queueMetadataInvalidated = true;
+      }
+      return;
+    }
+    this.db.query("DELETE FROM delivery_queue_meta WHERE project_id=?").run(this.projectId);
+    const put = this.db.query("INSERT INTO delivery_queue_meta(project_id,peer,queued,oldest_at,unknown_age) VALUES(?,?,?,?,?)");
+    for (const [peer, queue] of Object.entries(bus.queues)) {
+      const provenance = bus.queuedAt;
+      const times = provenance && typeof provenance === "object" && !Array.isArray(provenance) && Object.hasOwn(provenance, peer) ? provenance[peer] : undefined;
+      let oldest: number | undefined, unknown = false;
+      for (const env of queue) {
+        const at = times && typeof times === "object" && !Array.isArray(times) && Object.hasOwn(times, env.id) ? times[env.id] : null;
+        if (typeof at !== "number" || !Number.isSafeInteger(at) || at <= 0) unknown = true;
+        else oldest = oldest === undefined ? at : Math.min(oldest, at);
+      }
+      put.run(this.projectId, peer, queue.length, oldest ?? null, unknown ? 1 : 0);
+    }
+    this.db.query("INSERT INTO delivery_queue_meta_state(project_id,revision) VALUES(?,?) ON CONFLICT(project_id) DO UPDATE SET revision=excluded.revision")
+      .run(this.projectId, revision);
+    this.queueMetadataInvalidated = false;
+  }
+
+  /** Host policy only, refreshed before receipt/reply mutations as well as snapshot writes. No SQL. */
+  setQueueMetadataTracking(tracking: boolean): void { this.queueMetadataTracking = tracking === true; }
+
+  private queueMetadataTransaction<T>(tracking: boolean, fn: () => T): T {
+    return this.transaction(() => { this.setQueueMetadataTracking(tracking); return fn(); });
+  }
+  private queueMetadataSnapshot(bus: BusSnapshot, tracking: boolean): BusSnapshot {
+    if (tracking || bus.queuedAt === undefined) return bus;
+    const legacy = { ...bus }; delete legacy.queuedAt;
+    return legacy;
+  }
+
+  /** Indexed per-peer pending counts/age only, independent of delivery history and payload columns. */
+  pendingQueueMetadata(peer: string): QueuePressure | undefined {
+    this.ensureOpen();
+    const row = this.db.query("SELECT m.revision,s.revision AS metadata_revision,q.peer AS metadata_peer,q.queued,q.oldest_at,q.unknown_age FROM delivery_meta m LEFT JOIN delivery_queue_meta_state s ON s.project_id=m.project_id LEFT JOIN delivery_queue_meta q ON q.project_id=m.project_id AND q.peer=? WHERE m.project_id=?")
+      .get(peer, this.projectId) as { revision: number; metadata_revision: number | null; metadata_peer: string | null; queued: number | null; oldest_at: number | null; unknown_age: number | null } | null;
+    if (!row || !Number.isSafeInteger(row.revision) || row.revision < 0 || row.metadata_revision !== row.revision) return undefined;
+    if (row.metadata_peer === null) return { queued: 0, oldestQueuedAt: null };
+    if (typeof row.queued !== "number" || !Number.isSafeInteger(row.queued) || row.queued < 0 || row.queued > 2048 || ![0, 1].includes(row.unknown_age!)) return undefined;
+    if (row.queued === 0) return row.oldest_at === null && row.unknown_age === 0 ? { queued: 0, oldestQueuedAt: null } : undefined;
+    if (row.unknown_age === 1) return { queued: row.queued };
+    if (!Number.isSafeInteger(row.oldest_at) || row.oldest_at! <= 0) return undefined;
+    return { queued: row.queued, oldestQueuedAt: row.oldest_at! };
+  }
   transaction<T>(fn: () => T): T {
     this.ensureOpen();
-    return this.db.transaction(fn)();
+    const invalidated = this.queueMetadataInvalidated;
+    try { return this.db.transaction(fn)(); }
+    catch (error) { this.queueMetadataInvalidated = invalidated; throw error; }
   }
   snapshot(): JournalSnapshot {
     this.ensureOpen();
@@ -513,26 +610,34 @@ export class DeliveryJournal {
     validateJournalSnapshot(result);
     return result;
   }
-  persistBus(bus: unknown, manualPaused: string[]): number {
+  persistBus(bus: unknown, manualPaused: string[], trackQueuePressure = false): number {
     this.ensureOpen();
-    validateBus(bus);
+    let checkedBus = this.queueMetadataSnapshot(validateBus(bus), trackQueuePressure);
+    let encodedBus: string;
+    try { encodedBus = JSON.stringify(checkedJSON(checkedBus, "bus")); }
+    catch (error) {
+      if (checkedBus.queuedAt === undefined || !(error instanceof Error) || error.message !== "invalid delivery journal: bus is too large") throw error;
+      checkedBus = { ...checkedBus }; delete checkedBus.queuedAt;
+      encodedBus = JSON.stringify(checkedJSON(checkedBus, "bus"));
+    }
     list(manualPaused, "manualPaused", 4096).forEach((id) =>
       text(id, "manualPaused[]", 256),
     );
-    return this.db.transaction(() => {
+    return this.queueMetadataTransaction(trackQueuePressure, () => {
       const revision = this.bump();
       this.db
         .query(
           "UPDATE delivery_meta SET bus_snapshot = ?, manual_paused = ? WHERE project_id = ?",
         )
         .run(
-          JSON.stringify(checkedJSON(bus, "bus")),
+          encodedBus,
           JSON.stringify([...new Set(manualPaused)].sort()),
           this.projectId,
         );
+      this.writeQueueMetadata(checkedBus, revision, trackQueuePressure);
       this.harden();
       return revision;
-    })();
+    });
   }
   /** Atomically persist a bus snapshot and any fan-out rows created for that snapshot. */
   persistBusAndDeliveries(
@@ -541,9 +646,10 @@ export class DeliveryJournal {
     deliveries: Array<
       Omit<JournalDelivery, "revision" | "updatedAt"> & { updatedAt?: number }
     >,
+    trackQueuePressure = false,
   ): number {
     this.ensureOpen();
-    validateBus(bus);
+    bus = this.queueMetadataSnapshot(validateBus(bus), trackQueuePressure);
     list(manualPaused, "manualPaused", 4096).forEach((id) =>
       text(id, "manualPaused[]", 256),
     );
@@ -554,7 +660,7 @@ export class DeliveryJournal {
         updatedAt: d.updatedAt ?? d.createdAt,
       }),
     );
-    return this.db.transaction(() => {
+    return this.queueMetadataTransaction(trackQueuePressure, () => {
       const revision = this.bump();
       this.db
         .query(
@@ -565,6 +671,7 @@ export class DeliveryJournal {
           JSON.stringify([...new Set(manualPaused)].sort()),
           this.projectId,
         );
+      this.writeQueueMetadata(bus, revision, trackQueuePressure);
       for (const d of deliveries)
         this.db
           .query(
@@ -586,68 +693,73 @@ export class DeliveryJournal {
           );
       this.harden();
       return revision;
-    })();
+    });
   }
   checkpointDelivery(
     bus: BusSnapshot,
     delivery: Omit<JournalDelivery, "revision" | "updatedAt"> & {
       state: "dispatching";
     },
+    trackQueuePressure = false,
   ): JournalDelivery {
-    validateBus(bus);
+    bus = this.queueMetadataSnapshot(validateBus(bus), trackQueuePressure);
     validateDelivery({
       ...delivery,
       revision: 0,
       updatedAt: delivery.createdAt,
     });
-    return this.db.transaction(() => {
-      const evidence = this.retryEvidence(delivery.peer, delivery.originals);
-      if (evidence === "used") {
-        // Inheritance commits with the handoff, before safe failure or pruning can erase a grouped parent.
-        this.recordRetryEvidence(delivery.peer, delivery.originals, delivery.id, this.retryWarning(delivery.peer, delivery.originals));
-        delivery = { ...delivery, attempt: Math.max(1, delivery.attempt ?? 0) };
-      } else if (evidence === "unknown") this.markRetryUnknown([{ ...delivery, revision: 0, updatedAt: delivery.createdAt }], {});
-      const ids = new Set(delivery.originals.map((env) => env.id)), immutableIds = new Set(retryOriginals(delivery.originals).map(env => env.id));
-      for (const row of this.list(delivery.peer)) {
-        if (row.state !== "queued" || !row.originals.some((env) => ids.has(env.id))) continue;
-        this.transition(row.id, "discarded", `grouped into delivery ${delivery.id}`);
-        if (retryOriginals(row.originals).some(env => immutableIds.has(env.id))) {
-          delivery = { ...delivery, previousId: delivery.previousId ?? row.id };
-          if ((row.attempt ?? 0) > 0) delivery = { ...delivery, attempt: Math.max(delivery.attempt ?? 0, row.attempt!) };
+    return this.queueMetadataTransaction(trackQueuePressure, () => {
+      // Grouped parents are not linked until the handoff INSERT.
+      return this.withPruningDeferred(() => {
+        const evidence = this.retryEvidence(delivery.peer, delivery.originals);
+        if (evidence === "used") {
+          // Inheritance commits with the handoff, before safe failure or pruning can erase a grouped parent.
+          this.recordRetryEvidence(delivery.peer, delivery.originals, delivery.id, this.retryWarning(delivery.peer, delivery.originals));
+          delivery = { ...delivery, attempt: Math.max(1, delivery.attempt ?? 0) };
+        } else if (evidence === "unknown") this.markRetryUnknown([{ ...delivery, revision: 0, updatedAt: delivery.createdAt }], {});
+        const ids = new Set(delivery.originals.map((env) => env.id)), immutableIds = new Set(retryOriginals(delivery.originals).map(env => env.id));
+        for (const row of this.list(delivery.peer)) {
+          if (row.state !== "queued" || !row.originals.some((env) => ids.has(env.id))) continue;
+          this.transition(row.id, "discarded", `grouped into delivery ${delivery.id}`);
+          if (retryOriginals(row.originals).some(env => immutableIds.has(env.id))) {
+            delivery = { ...delivery, previousId: delivery.previousId ?? row.id };
+            if ((row.attempt ?? 0) > 0) delivery = { ...delivery, attempt: Math.max(delivery.attempt ?? 0, row.attempt!) };
+          }
         }
-      }
-      const revision = this.bump();
-      const now = Date.now();
-      this.db
-        .query(
-          "UPDATE delivery_meta SET bus_snapshot = ?, manual_paused = ? WHERE project_id = ?",
-        )
-        .run(
-          JSON.stringify(bus),
-          JSON.stringify(bus.manualPaused ?? []),
-          this.projectId,
-        );
-      this.db
-        .query(
-          "INSERT INTO deliveries (id, project_id, peer, state, revision, created_at, updated_at, originals, out_json, reason, attempt, previous_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
-        )
-        .run(
-          delivery.id,
-          this.projectId,
-          delivery.peer,
-          delivery.state,
-          revision,
-          delivery.createdAt,
-          now,
-          JSON.stringify(delivery.originals),
-          JSON.stringify(delivery.out),
-          delivery.reason ?? null,
-          delivery.attempt ?? null,
-          delivery.previousId ?? null,
-        );
-      this.harden();
-      return { ...delivery, revision, updatedAt: now };
-    })();
+        const revision = this.bump();
+        const now = Date.now();
+        this.db
+          .query(
+            "UPDATE delivery_meta SET bus_snapshot = ?, manual_paused = ? WHERE project_id = ?",
+          )
+          .run(
+            JSON.stringify(bus),
+            JSON.stringify(bus.manualPaused ?? []),
+            this.projectId,
+          );
+        this.writeQueueMetadata(bus, revision, trackQueuePressure);
+        this.db
+          .query(
+            "INSERT INTO deliveries (id, project_id, peer, state, revision, created_at, updated_at, originals, out_json, reason, attempt, previous_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+          )
+          .run(
+            delivery.id,
+            this.projectId,
+            delivery.peer,
+            delivery.state,
+            revision,
+            delivery.createdAt,
+            now,
+            JSON.stringify(delivery.originals),
+            JSON.stringify(delivery.out),
+            delivery.reason ?? null,
+            delivery.attempt ?? null,
+            delivery.previousId ?? null,
+          );
+        this.harden();
+        return { ...delivery, revision, updatedAt: now };
+      });
+    });
   }
   createDelivery(
     input: Omit<JournalDelivery, "revision" | "updatedAt"> & {
@@ -681,7 +793,7 @@ export class DeliveryJournal {
           input.attempt ?? null,
           input.previousId ?? null,
         );
-      this.pruneTerminal();
+      this.pruneTerminal(input.state, input.id);
       return { ...input, revision, updatedAt };
     })();
   }
@@ -698,9 +810,14 @@ export class DeliveryJournal {
     return this.db.transaction((): JournalDelivery => {
       const row = this.get(deliveryId);
       if (!row || row.peer !== peer || !["dispatching", "accepted"].includes(row.state)) throw new Error("delivery is not active for this peer");
-      const completed = this.transition(deliveryId, "completed", reason, row.revision);
-      const put = this.db.query("INSERT OR IGNORE INTO task_offer_reads (project_id,peer,envelope_id,delivery_id,source,offer_revision) VALUES (?,?,?,?,?,?)");
-      for (const env of row.originals) if (env.from === HUB && env.kind === "task" && Number.isSafeInteger(env.refs?.taskOffer) && env.refs!.taskOffer! >= 1) put.run(this.projectId, peer, env.id, deliveryId, source, env.refs!.taskOffer!);
+      const completed = this.withPruningDeferred(() => {
+        const result = this.transition(deliveryId, "completed", reason, row.revision);
+        const put = this.db.query("INSERT OR IGNORE INTO task_offer_reads (project_id,peer,envelope_id,delivery_id,source,offer_revision) VALUES (?,?,?,?,?,?)");
+        for (const env of row.originals) if (env.from === HUB && env.kind === "task" && Number.isSafeInteger(env.refs?.taskOffer) && env.refs!.taskOffer! >= 1) put.run(this.projectId, peer, env.id, deliveryId, source, env.refs!.taskOffer!);
+        return result;
+      });
+      // Proof is now durable in this transaction, and the return receipt is captured.
+      this.pruneTerminal("completed", "");
       return completed;
     })();
   }
@@ -730,7 +847,7 @@ export class DeliveryJournal {
           "UPDATE deliveries SET state = ?, revision = ?, updated_at = ?, reason = ? WHERE id = ? AND project_id = ?",
         )
         .run(state, revision, Date.now(), reason ?? null, id, this.projectId);
-      this.pruneTerminal();
+      this.pruneTerminal(state, id);
       return this.get(id)!;
     })();
   }
@@ -919,7 +1036,7 @@ export class DeliveryJournal {
           JSON.stringify(retryOriginals(current.originals).map(env => env.id)),
         );
       if (action === "retry") this.recordRetryEvidence(current.peer, current.originals, id, actor === `peer:${current.peer}`);
-      this.pruneTerminal();
+      this.pruneTerminal(result.state, result.id);
       return result;
     })();
   }
@@ -927,7 +1044,15 @@ export class DeliveryJournal {
     const row = this.db.query("SELECT action,reason,observed_revision,actor FROM resolution_history WHERE project_id=? AND delivery_id=? ORDER BY id DESC LIMIT 1").get(this.projectId, id) as { action: JournalResolution; reason: string; observed_revision: number; actor: string } | null;
     return row ? { action: row.action, reason: row.reason, observedRevision: row.observed_revision, actor: row.actor } : undefined;
   }
-  private pruneTerminal(): void {
+  private withPruningDeferred<T>(body: () => T): T {
+    this.pruningDeferred++;
+    try { return body(); } finally { this.pruningDeferred--; }
+  }
+  private pruneTerminal(state: JournalDeliveryState, currentId: string): void {
+    if (this.pruningDeferred) return;
+    const terminal = state === "completed" || state === "discarded" || state === "failed";
+    const terminalCap = terminal ? this.terminalHistoryLimit?.() ?? TERMINAL_CAP : TERMINAL_CAP;
+    // Never delete the receipt this mutation/resolve is still using, at any target.
     const count = Number(
       (
         this.db
@@ -937,16 +1062,17 @@ export class DeliveryJournal {
           .get(this.projectId) as { n: number }
       ).n,
     );
-    if (count <= TERMINAL_CAP) return;
+    if (count <= terminalCap) return;
     this.db
       .query(
-        "DELETE FROM deliveries WHERE id IN (SELECT d.id FROM deliveries d WHERE d.project_id = ? AND d.state IN ('completed','discarded','failed') AND NOT EXISTS (SELECT 1 FROM deliveries c WHERE c.project_id = d.project_id AND c.previous_id = d.id) ORDER BY d.updated_at, d.id LIMIT ?)",
+        "DELETE FROM deliveries WHERE id IN (SELECT d.id FROM deliveries d WHERE d.project_id = ? AND d.state IN ('completed','discarded','failed') AND d.id != ? AND NOT EXISTS (SELECT 1 FROM deliveries c WHERE c.project_id = d.project_id AND c.previous_id = d.id) ORDER BY d.updated_at, d.id LIMIT ?)",
       )
-      .run(this.projectId, count - TERMINAL_CAP);
+      .run(this.projectId, currentId, count - terminalCap);
   }
-  importSnapshot(snapshot: JournalSnapshot, operationId: string): boolean {
+  importSnapshot(snapshot: JournalSnapshot, operationId: string, trackQueuePressure = false): boolean {
     this.ensureOpen();
     validateJournalSnapshot(snapshot);
+    const bus = this.queueMetadataSnapshot(snapshot.bus, trackQueuePressure);
     text(operationId, "operationId", 256);
     if (this.operationId !== undefined && this.operationId !== operationId)
       throw new Error("recovery operation does not own delivery journal");
@@ -963,18 +1089,19 @@ export class DeliveryJournal {
       Object.keys(storedBus).length !== 0
     )
       return false;
-    return this.db.transaction(() => {
+    return this.queueMetadataTransaction(trackQueuePressure, () => {
       this.db
         .query(
           "UPDATE delivery_meta SET revision = ?, bus_snapshot = ?, manual_paused = ?, operation_id = ? WHERE project_id = ?",
         )
         .run(
           snapshot.revision,
-          JSON.stringify(snapshot.bus),
+          JSON.stringify(bus),
           JSON.stringify(snapshot.manualPaused),
           operationId,
           this.projectId,
         );
+      this.writeQueueMetadata(bus, snapshot.revision, trackQueuePressure);
       for (const row of snapshot.deliveries)
         this.db
           .query(
@@ -995,9 +1122,9 @@ export class DeliveryJournal {
             row.previousId ?? null,
           );
       // Snapshots deliberately omit resolution history; only these imported originals have unknown retry rights.
-      this.markRetryUnknown(snapshot.deliveries, snapshot.bus);
+      this.markRetryUnknown(snapshot.deliveries, bus);
       return true;
-    })();
+    });
   }
   close(): void {
     if (!this.closed) {

package/src/hub/dogfood-profile.ts

@@ -8,10 +8,12 @@ import type { StampedEvent } from "./events.ts";
 
 export interface ProfileHistory {
   at: number; event: string; criteria?: string[]; criteriaPrivate?: true; deliverables?: string[];
+  /** #901: on the hub's own check entries, the check key and the example check's unresolved-key count; on a `claim verdict` entry, the person's verdict. Closed values only, no claim text. */
+  checkKey?: string; missingKeys?: number; claim?: { slot: number; verdict: "supported" | "unsupported" | "unclear"; model?: string; modelVerdict?: "supported" | "unsupported" | "unclear"; list?: string };
 }
 export interface ProfileTaskMetadata {
   profile: ProfileName; state?: string; class: string; alias: string | null; history: ProfileHistory[];
-  plan?: { sources: number | null; claims: number | null };
+  plan?: { sources: number | null; claims: number | null; /** #901: `claimListId` of the plan's claims now (an opaque hash, never their text); absent when the list could not be read. */ claimList?: string };
 }
 const complete = (s: Source<unknown>) => s.available && s.complete;
 const number = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n) && n >= 0;
@@ -24,7 +26,7 @@ const criterion = (s: unknown): s is string => typeof s === "string" && /^[A-Za-
 
 // Exhaustive maps make producer union changes a compile-time review point.
 const taskStates: Record<TaskState,true> = {backlog:true,proposed:true,in_progress:true,in_review:true,approved:true,changes_requested:true,cancelled:true};
-const usageSources: Record<Extract<StampedEvent,{type:"usage"}>["source"],true> = {omniroute:true,claude_transcript:true,claude_result:true,codex_appserver:true,kimi_wire:true};
+const usageSources: Record<Extract<StampedEvent,{type:"usage"}>["source"],true> = {omniroute:true,claude_transcript:true,claude_result:true,codex_appserver:true,kimi_wire:true,jcode_acp:true};
 const attributions: Record<Attribution,true> = {delivery:true,single_open:true,unattributed:true};
 const screenItems: Record<ScreenItem,true> = {task:true,summary:true,"review note":true,handoff:true,note:true};
 const screenMisses: Record<ScreenMiss,true> = {"too long":true,"off campus":true,timeout:true,unreadable:true,failed:true};
@@ -228,12 +230,37 @@ export function profileScorecard(input: DogfoodInput) {
         const count=t.metadata.plan?.[key];
         return full && declarationCount(count) ? count : null;
       };
+      // #901: claim verdicts and check provenance, read only from entries the hub or the person wrote with closed values. Unknown stays unknown, never zero: a count exists only when its source
+      // history is complete, and a row without its basis (no verdict, no model verdict, no recorded check key) is null.
+      type Verdict = "supported" | "unsupported" | "unclear";
+      // A verdict counts only for the claim list it evaluated: its `list` must equal the plan's current claim-list id. After the owner replaces or reorders the claims, an earlier verdict names no claim
+      // of the new list (it is unknown again, not carried over to whatever now sits in its slot), and a verdict from before ids were recorded cannot be bound, so it does not count.
+      const lastVerdict = (t: BoundTask, slot: number) => t.metadata.history.filter(h => h.event === "claim verdict" && h.claim?.slot === slot && inWindow(h.at) && t.metadata.plan?.claimList !== undefined && h.claim.list === t.metadata.plan.claimList).sort((a, b) => a.at - b.at).at(-1)?.claim;
+      const slotRows = group.tasks.map(t => {
+        const count = planCount(t, "claims");
+        return { task: t.id, claims: count === null ? null : Array.from({ length: count }, (_, i) => {
+          const c = lastVerdict(t, i + 1);
+          return { slot: i + 1, modelLabel: c?.model ?? null, personVerdict: c?.verdict ?? null, agreement: c?.modelVerdict ? c.modelVerdict === c.verdict : null };
+        }) };
+      });
+      const slotted = slotRows.flatMap(row => row.claims ?? []);
+      const decided = slotted.filter(c => c.personVerdict !== null);
+      const checkEntries = history.filter(h => (h.event === "check passed" || h.event === "check failed") && h.checkKey === "fact_check");
+      const everyCheckKeyed = full && history.filter(h => h.event === "check passed" || h.event === "check failed").every(h => typeof h.checkKey === "string");
+      const compared = decided.filter(c => c.agreement !== null);
       const research = profile === "research" ? {research:{
         declarations:{scope:"current_plan",perTask:group.tasks.map(t=>({task:t.id,sources:planCount(t,"sources"),claims:planCount(t,"claims")}))},
-        claims:{reachedPersonVerdict:null,perTask:group.tasks.map(t=>{const count=planCount(t,"claims");return {task:t.id,claims:count===null?null:Array.from({length:count},(_,i)=>({slot:i+1,modelLabel:null,personVerdict:null,agreement:null}))};})},
+        // A verdict is the person's, entered with `ahub task claim`; task approval never supplies one. Null until at least the declarations are known; then the number of slots with a recorded verdict.
+        claims:{reachedPersonVerdict:full && slotRows.every(r => r.claims !== null) && decided.length > 0 ? decided.length : null,perTask:slotRows},
         observedCheckOutcomes:{scope:"task_check_history",passed:full?history.filter(h=>h.event==="check passed").length:null,failed:full?history.filter(h=>h.event==="check failed").length:null},
-        factCheck:{scope:null,selection:null,passed:null,failed:null,missingKeysPerRun:null,
-          agreement:["supported","unsupported","unclear"].map(label=>({label,count:null}))}
+        // Selection and pass/fail are proven only for entries that carry the hub's own check key, and only when every check entry of the group carries one (an older entry has no key: that is unknown, not "another check").
+        factCheck:{scope:everyCheckKeyed && checkEntries.length > 0 ? "task_check_history_with_key" : null,selection:everyCheckKeyed && checkEntries.length > 0 ? "checks.fact_check" : null,
+          passed:everyCheckKeyed && checkEntries.length > 0 ? checkEntries.filter(h => h.event === "check passed").length : null,
+          failed:everyCheckKeyed && checkEntries.length > 0 ? checkEntries.filter(h => h.event === "check failed").length : null,
+          missingKeysPerRun:everyCheckKeyed && checkEntries.length > 0 && checkEntries.every(h => h.missingKeys !== undefined) ? checkEntries.map(h => h.missingKeys!) : null,
+          // Agreement is a count of slots where the model's own verdict was entered and equals the person's, per label. A slot without the model's verdict (agreement null) is unknown and counts for nothing; one where they differ
+          // (agreement false) is a disagreement and counts for no label. With no comparable slot every label is null, never zero.
+          agreement:(["supported","unsupported","unclear"] as Verdict[]).map(label=>({label,count:compared.length > 0 ? compared.filter(c => c.agreement === true && c.personVerdict === label).length : null}))}
       }} : {};
       return {...research,profile, alias:group.alias, baseClass:group.base, tasks:[...ids].sort((a,b)=>a-b),
         flow:{scope,autoApprovalTransitions:{scope:"recorded_events",value:eventsFull?new Set(autoApprovals.map(e=>e.id)).size:null},proposed:count("proposed"),accepted:count("accepted"),approved:milestoneKnown&&!approvalUnknown?approvalIds.size:null,cancelled:count("cancelled"),proposeToApproveMs:full&&!approvalUnknown?quantiles(leads):{samples:null,p50:null,p90:null},reviewRounds:milestoneKnown?rounds:null,firstPassApproval:full&&!approvalUnknown&&first.length?first.reduce((a,b)=>a+b,0)/first.length:null,escalations:count("escalated")},

package/src/hub/dogfood-read.ts

@@ -1,3 +1,4 @@
+import { claimListId } from "./board.ts";
 import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
 import { join } from "node:path";
 import { Database } from "bun:sqlite";
@@ -96,7 +97,10 @@ export function dogfoodTasks(file: string): Source<DogfoodTask[]> {
               if (history.some((h:any) => h && (h.unmetCriteria !== undefined && (!Array.isArray(h.unmetCriteria) || h.unmetCriteria.length>32 || new Set(h.unmetCriteria).size!==h.unmetCriteria.length || h.unmetCriteria.some((v:unknown)=>typeof v!=="string" || !/^[A-Za-z][A-Za-z0-9-]{0,47}$/.test(v))) || h.deliverables !== undefined && (!Array.isArray(h.deliverables) || h.deliverables.length>16 || h.deliverables.some((v:any)=>typeof v?.id!=="string" || !/^d-[0-9a-f]{12}$/.test(v.id)))))) complete=false;
               const projection = history.filter((h:any)=>h && Number.isFinite(h.at) && typeof h.event==="string").map((h:any) => ({at:h.at,event:h.event,
                 ...(Array.isArray(h.unmetCriteria) ? {criteria:h.unmetCriteria.slice(0,32).filter((v:unknown)=>typeof v === "string" && /^[A-Za-z][A-Za-z0-9-]{0,47}$/.test(v)).map((v:string)=>pii || h.withheld ? "withheld" : v), ...(h.withheld ? {criteriaPrivate:true as const} : {})} : {}),
-                ...(Array.isArray(h.deliverables) ? {deliverables:h.deliverables.slice(0,16).filter((v:any)=>typeof v?.id==="string" && /^d-[0-9a-f]{12}$/.test(v.id)).map((v:any)=>v.id)} : {})}));
+                ...(Array.isArray(h.deliverables) ? {deliverables:h.deliverables.slice(0,16).filter((v:any)=>typeof v?.id==="string" && /^d-[0-9a-f]{12}$/.test(v.id)).map((v:any)=>v.id)} : {}),
+                // #901: only closed values cross: a check key is a bounded identifier, a count a safe integer, a verdict one of three words and a model label a bounded token. Anything else is dropped (unknown).
+                ...(h.event==="check passed" || h.event==="check failed" ? {...(typeof h.checkKey==="string" && /^[a-z][a-z0-9_]{0,47}$/.test(h.checkKey) ? {checkKey:h.checkKey} : {}), ...(Number.isSafeInteger(h.missingKeys) && h.missingKeys>=0 && h.missingKeys<=100000 ? {missingKeys:h.missingKeys} : {})} : {}),
+                ...(h.event==="claim verdict" && h.claim && Number.isSafeInteger(h.claim.slot) && h.claim.slot>=1 && h.claim.slot<=50 && ["supported","unsupported","unclear"].includes(h.claim.verdict) ? {claim:{slot:h.claim.slot,verdict:h.claim.verdict,...(typeof h.claim.list==="string" && /^[0-9a-f]{16}$/.test(h.claim.list) ? {list:h.claim.list} : {}),...(typeof h.claim.model==="string" && /^[A-Za-z0-9][A-Za-z0-9._:/@+-]{0,63}$/.test(h.claim.model) && !pii ? {model:h.claim.model} : {}),...(["supported","unsupported","unclear"].includes(h.claim.modelVerdict) ? {modelVerdict:h.claim.modelVerdict} : {})}} : {})}));
               let declarations: ProfileTaskMetadata["plan"];
               if (!row.plan_cut && row.plan !== null) {
                 try {
@@ -110,7 +114,7 @@ export function dogfoodTasks(file: string): Source<DogfoodTask[]> {
                       if (!Array.isArray(value) || value.length>50 || value.some((v:unknown)=>typeof v!=="string" || v.length>300)) throw new Error("plan list malformed");
                       return value.length;
                     };
-                    declarations={sources:count("sources"),claims:count("claims")};
+                    declarations={sources:count("sources"),claims:count("claims"),claimList:claimListId(Array.isArray(rawPlan.claims) ? rawPlan.claims : undefined)};
                   }
                 } catch {planBad=true;}
               }

package/src/hub/envelope.ts

@@ -78,6 +78,17 @@ export const STANDING_INSTRUCTION =
   "with [IMPORTANT] only when the recipient must see it before finishing what it is doing. Unmarked messages are batched. " +
   HUB_MESSAGE_INSTRUCTION;
 
+/**
+ * #912: Jcode defers MCP tools. Only its built-in tools are listed, and an MCP tool appears once the model searches for it, so a Jcode peer with no hint
+ * concludes it has no `hub_*` tools and answers in its final message instead of calling `hub_send`, `hub_task_accept`, `hub_task_done` or `hub_review`.
+ * This is the ONE place the guidance is written: `JcodePeer` puts it in front of the session's role contract (sent once, with the first prompt of a session),
+ * and no other peer's prompt, the AGENTS block or a profile template repeats it. The server name is `JCODE_MCP_NAME` (`src/cli/jcode-mcp.ts`); a test pins them equal.
+ */
+export const JCODE_DEFERRED_TOOLS_INSTRUCTION =
+  "[agent-hub] Your hub tools (hub_send, hub_inbox, hub_task_accept, hub_task_done, hub_review and the rest) are deferred MCP tools from the agent-hub-jcode server: " +
+  "they are not in your visible tool list until you load them. Before you conclude a hub tool is missing, search for it by name with your tool search and load it, " +
+  "then call it. Never report the hub as unavailable without having searched. Answer a hub message with hub_send, not only in your final message.";
+
 const MARKER = /^\s*\[(IMPORTANT|STATUS|FYI)\]\s*/i;
 
 /** A leading [IMPORTANT] / [STATUS] / [FYI] sets the priority and is stripped from the body. */