@staix/agent-hub 0.20.0 → 0.21.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 =
@@ -168,6 +170,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,6 +269,8 @@ export class DeliveryJournal {
   readonly instanceId: string;
   private readonly db: Database;
   private closed = false;
+  private queueMetadataTracking = false;
+  private queueMetadataInvalidated = false;
   private readonly operationId?: string;
   constructor(options: DeliveryJournalOptions) {
     this.file = options.file;
@@ -323,6 +353,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 +506,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 +605,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 +641,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 +655,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 +666,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,21 +688,22 @@ 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(() => {
+    return this.queueMetadataTransaction(trackQueuePressure, () => {
       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.
@@ -627,6 +730,7 @@ export class DeliveryJournal {
           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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
@@ -647,7 +751,7 @@ export class DeliveryJournal {
         );
       this.harden();
       return { ...delivery, revision, updatedAt: now };
-    })();
+    });
   }
   createDelivery(
     input: Omit<JournalDelivery, "revision" | "updatedAt"> & {
@@ -944,9 +1048,10 @@ export class DeliveryJournal {
       )
       .run(this.projectId, count - TERMINAL_CAP);
   }
-  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 +1068,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 +1101,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. */

package/src/hub/eval-gate.ts

@@ -0,0 +1,131 @@
+import type { PrEvidence, SdlcConfig, SdlcGh } from "./sdlc.ts";
+import { completePlanInventory } from "./plan-conformance.ts";
+
+/**
+ * #481 S5: the gate MECHANISM for agent-configuration PRs. A PR whose changed paths match `config_paths` needs the one check named by `eval_check`.
+ * The hub chooses, creates and defaults to no suite: `eval_check` has no default, and the person names it (suite choice pending the person).
+ */
+export const DEFAULT_CONFIG_PATHS: readonly string[] = [
+  "AGENTS.md", "docs/agent-notes/**", "templates/**", ".agenthub/roles/**", ".agenthub/routing.toml", "routing.toml", "src/hub/hub-tools.ts",
+];
+const MAX_PATTERNS = 32;
+
+/** Repository-relative patterns: literal names, `*` and `?` inside one segment, and a whole-segment `**`. Anything else is refused at load. */
+export function configPathList(value: unknown, what: string): string[] {
+  const bad = () => new Error(`${what}: expected at most ${MAX_PATTERNS} unique repository-relative patterns (literal names, * and ? inside a segment, whole-segment **)`);
+  if (!Array.isArray(value) || value.length > MAX_PATTERNS || new Set(value).size !== value.length) throw bad();
+  for (const pattern of value) {
+    if (typeof pattern !== "string" || !pattern || pattern.length > 200 || /[\p{Cc}\p{Cf}\\]/u.test(pattern) || pattern.startsWith("/") || /^[A-Za-z]:/.test(pattern)) throw bad();
+    const parts = pattern.split("/");
+    if (parts.some(part => part === "" || part === "." || part === ".." || (part.includes("**") && part !== "**"))) throw bad();
+  }
+  return [...value] as string[];
+}
+
+const segmentRegex = (part: string) => new RegExp(`^${part.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]")}$`);
+/** Pure, lexical, no filesystem. `dir/**` matches everything under `dir`, never `dir` itself. */
+export function matchConfigPath(pattern: string, path: string): boolean {
+  const p = pattern.split("/"), s = path.split("/");
+  const walk = (i: number, j: number): boolean => {
+    if (i === p.length) return j === s.length;
+    if (p[i] === "**") { for (let k = j + 1; k <= s.length; k++) if (walk(i + 1, k)) return true; return false; }
+    return j < s.length && segmentRegex(p[i]!).test(s[j]!) && walk(i + 1, j + 1);
+  };
+  return walk(0, 0);
+}
+
+export type EvalApplies = "config" | "code" | "unknown";
+export const configPathsOf = (config: Pick<SdlcConfig, "configPaths">): readonly string[] => config.configPaths ?? DEFAULT_CONFIG_PATHS;
+
+/** `unknown` when the file inventory is not complete (never a clean code-only claim); `code` for a PR touching no configured path, an empty `config_paths` included. */
+export function evalApplies(config: Pick<SdlcConfig, "configPaths">, evidence: PrEvidence | undefined): { applies: EvalApplies; matched: string[] } {
+  const paths = configPathsOf(config);
+  if (!paths.length) return { applies: "code", matched: [] };
+  const inventory = completePlanInventory(evidence);
+  if (inventory === undefined) return { applies: "unknown", matched: [] };
+  const matched = inventory.filter(path => paths.some(pattern => matchConfigPath(pattern, path))).sort();
+  return { applies: matched.length ? "config" : "code", matched };
+}
+
+/** The extra required check for this reading of the PR: the configured eval check, only for a configuration PR. */
+export function evalRequiredChecks(config: Pick<SdlcConfig, "configPaths" | "evalCheck" | "mode">, evidence: PrEvidence | undefined): string[] {
+  if (config.mode === "off" || !config.evalCheck) return [];
+  return evalApplies(config, evidence).applies === "config" ? [config.evalCheck] : [];
+}
+
+/** What the eval check run reported, never its text: two bounded values read from a fixed marker (`eval_pass_rate=<0..1>`, `eval_suite=<version>`). */
+export interface EvalResult { check: string; head: string; passRate?: number; suite?: string; read: boolean }
+export interface EvalGate {
+  applies: "config" | "unknown";
+  /** How many changed files matched `config_paths`; names stay out of the view (counts and identities only). */
+  files: number;
+  check?: string;
+  state: "not_configured" | "coverage_unknown" | "passed" | "failed" | "pending" | "missing" | "unknown";
+  passRate?: number;
+  suite?: string;
+  /** Evidence gaps that were required of a configured gate: shown in every enabled mode, blockers only in enforce. */
+  gaps: string[];
+  /** Shown, never a blocker in any mode: the gate has no suite behind it yet (suite choice pending the person). */
+  notes?: string[];
+}
+export const EVAL_NOT_CONFIGURED = "eval check not configured: the person names one with eval_check in sdlc.toml (suite choice pending the person)";
+export const EVAL_COVERAGE_UNKNOWN = "eval gate: PR file coverage incomplete or unknown";
+export const evalReportedGap = (check: string) => `eval gate: pass rate or suite version not reported by ${check}`;
+const reported = evalReportedGap;
+
+/** Undefined for off mode and for a code-only PR: those outputs stay byte-identical. */
+export function evalGateView(config: Pick<SdlcConfig, "configPaths" | "evalCheck" | "mode">, evidence: PrEvidence | undefined, result?: EvalResult): EvalGate | undefined {
+  if (config.mode === "off") return undefined;
+  const { applies, matched } = evalApplies(config, evidence);
+  if (applies === "code") return undefined;
+  const check = config.evalCheck;
+  // With no eval check named there is nothing to require: say so, and never block. Enforce users gain no new refusal until the person names a suite.
+  if (!check) return applies === "unknown" ? undefined : { applies, files: matched.length, state: "not_configured", gaps: [], notes: [EVAL_NOT_CONFIGURED] };
+  if (applies === "unknown") return { applies, files: 0, state: "coverage_unknown", check, gaps: [EVAL_COVERAGE_UNKNOWN] };
+  const found = evidence!.checks.filter(c => c.name === check);
+  const state = !found.length ? "missing" : found.some(c => c.state === "failed") ? "failed" : found.some(c => c.state === "pending") ? "pending" : found.every(c => c.state === "passed") ? "passed" : "unknown";
+  const view: EvalGate = { applies, files: matched.length, check, state, gaps: [] };
+  // The record is read only for a passed check at this head; a result read for another head or check is never shown.
+  if (result && result.read && result.check === check && result.head === evidence!.head) {
+    if (result.passRate !== undefined) view.passRate = result.passRate;
+    if (result.suite !== undefined) view.suite = result.suite;
+  }
+  if (state === "passed" && result && (view.passRate === undefined || view.suite === undefined)) view.gaps.push(reported(check));
+  return view;
+}
+/** Evidence gaps that block in enforce. The state of the check itself is an ordinary required-check blocker. */
+export const evalGapBlockers = (view: EvalGate | undefined): string[] => view?.gaps ?? [];
+/** What advise shows beside the gaps: gaps and notes, each once. */
+export const evalAdvice = (view: EvalGate | undefined): string[] => [...(view?.gaps ?? []), ...(view?.notes ?? [])];
+
+const MARK_RATE = /(?:^|\s)eval_pass_rate=(0(?:\.[0-9]{1,6})?|1(?:\.0{1,6})?)(?=\s|$)/;
+const MARK_SUITE = /(?:^|\s)eval_suite=([A-Za-z0-9][A-Za-z0-9._-]{0,39})(?=\s|$)/;
+const SHA = /^[a-f0-9]{40}$/;
+/** Pure: the two markers, or nothing. The rest of the text is never kept. */
+export function parseEvalMarkers(text: string): { passRate?: number; suite?: string } {
+  const rate = MARK_RATE.exec(text.slice(0, 2000))?.[1], suite = MARK_SUITE.exec(text.slice(0, 2000))?.[1];
+  return { ...(rate === undefined ? {} : { passRate: Number(rate) }), ...(suite === undefined ? {} : { suite }) };
+}
+
+/** Read-only, fixed argv, bounded output and time. One completed check run of that exact name at that exact head, else `read: false`. */
+export async function readEvalResult(repository: string, head: string, check: string, run: SdlcGh): Promise<EvalResult> {
+  const none: EvalResult = { check, head, read: false };
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository) || repository.startsWith("-") || !SHA.test(head) || !check || check.length > 120 || /[\x00-\x1f]/.test(check)) return none;
+  try {
+    const reply = await run(["api", `repos/${repository}/commits/${head}/check-runs?check_name=${encodeURIComponent(check)}&per_page=10`, "--jq",
+      '{total_count,check_runs:[.check_runs[]|{name,status,conclusion,head_sha,text:(((.output.title // "")+" "+(.output.summary // ""))|.[0:1000])}]}'], 10_000, undefined, 32 * 1024);
+    if (reply.code !== 0) return none;
+    const parsed = JSON.parse(reply.stdout), runs = parsed?.check_runs;
+    if (!Array.isArray(runs) || runs.length > 10 || parsed.total_count !== runs.length) return none;
+    const same = runs.filter((r: { name?: string }) => r?.name === check);
+    const only = same[0];
+    if (same.length !== 1 || only.head_sha !== head || only.status !== "completed" || typeof only.text !== "string") return none;
+    return { check, head, read: true, ...parseEvalMarkers(only.text) };
+  } catch { return none; }
+}
+
+/** The read happens only where it can matter: an enabled mode, a configured eval check and a configuration PR. */
+export async function readEvalFor(config: Pick<SdlcConfig, "configPaths" | "evalCheck" | "mode">, evidence: PrEvidence | undefined, repository: string | undefined, run: SdlcGh): Promise<EvalResult | undefined> {
+  if (!evidence || !repository || !config.evalCheck || evalRequiredChecks(config, evidence).length === 0) return undefined;
+  return readEvalResult(repository, evidence.head, config.evalCheck, run);
+}

package/src/hub/events.ts

@@ -53,7 +53,7 @@ export type HubEvent =
   | { type: "hook_stats"; peer: string; n: number; startupMs: number; hubMs: number; maxStartupMs: number }
   | { type: "cohort"; id: number; event: "formed" | "joined" | "lifted"; silent: boolean; tasks: number[]; owners: string[] }
   | ({ type: "tokens"; peer: string; n: number } & Partial<TaskAttribution>)
-  | ({ type: "usage"; peer: string; source: "omniroute" | "claude_transcript" | "claude_result" | "codex_appserver" | "kimi_wire"; id: string; reasoningTokens?: number; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number } & Partial<TaskAttribution>)
+  | ({ type: "usage"; peer: string; source: "omniroute" | "claude_transcript" | "claude_result" | "codex_appserver" | "kimi_wire" | "jcode_acp"; id: string; reasoningTokens?: number; measuredAt?: string; requestedModel?: string; servedModel?: string; provider?: string; inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number; totalTokens?: number } & Partial<TaskAttribution>)
   | { type: "planning"; by: string; task?: number; release?: number; fields: string[]; revision: number }
   | { type: "task"; id: number; event: string; by: string; state: string; owner: string | null; reviewer: string | null; class: string; profile?: string; profileClass?: string; role?: string; roleIdentity?: { id: string; layer: "shipped" | "project"; hash: string }; pii: boolean; reason?: string; release?: number | null; priority?: number | null; plannedStart?: number | null; due?: number | null }
   | { type: "overlap"; task: number; owner: string; others: { task: number; owner: string; paths: string[]; symbols?: string[] }[] }