@staix/agent-hub 0.14.0 → 0.15.0

package/src/hub/tasks.ts

@@ -21,7 +21,9 @@ import { correctionInput, resolveVisibleMemory } from "./memory-candidates.ts";
 import type { MemoryScreen } from "./read-tools.ts";
 import { withoutPii, mentionsPrivatePath } from "./memory-policy.ts";
 import { profileClass, profileData, profileTaskLabel, projectProfile, type ProfileName, type ProfileSelection, type ProjectProfile } from "./profiles.ts";
-import { criteriaView, workflowHash } from "./workflow.ts";
+import { criteriaView, unmetCriteriaIds, workflowHash } from "./workflow.ts";
+import { approvedDeliverables, latestDeliverables, parseDeliverableClaims, publicDeliverables, type DeliverableRecord, type DeliverableStatus } from "./deliverables.ts";
+import { checkDeliverables, DeliverableRefusal, hashDeliverables, vetDeliverables, type DeliverablePorts } from "./deliverable-files.ts";
 import { isAbsolute, relative } from "node:path";
 import type { Briefs, NativeItem } from "../memory/brief.ts";
 import type { MemoryClient } from "../memory/client.ts";
@@ -66,6 +68,13 @@ export interface TasksDeps {
   profile?: ProfileName;
   profileData?: ProjectProfile;
   piiPaths?: string[];
+  /** The project's secrets denylist (`local.deny`), for the deliverable file reader (#509a). */
+  deny?: string[];
+  /**
+   * #509a: the root a peer's files live under: its verified execution root (the daemon's `ownerWriteRoot`), which for a declared worktree
+   * instance is not the project checkout. `undefined` means the root is not proven right now. Absent (library use): the project root.
+   */
+  executionRoot?: (peer: PeerId) => string | undefined;
   catalog?: RoleCatalog;
   /** Role ids whose contract was prepared for the current native session. */
   sessionRoles?: (peer: PeerId) => string[];
@@ -92,6 +101,8 @@ export interface TasksDeps {
   reviewOnly?: (peer: PeerId) => boolean;
   /** #223: captured when a verdict call starts; a non-undefined result refuses the verdict at every later check. */
   reviewAuthority?: (by: PeerId, task: number) => (() => string | undefined) | undefined;
+  /** Host-captured current-child authority, rechecked before an admitted async tool first commits effects. */
+  requestAuthority?: (by: PeerId) => (() => string | undefined) | undefined;
   memory?: MemoryClient;
   /** Captured native profile fence at our memory operation boundaries; no board mutation. */
   memoryCheck?: () => void;
@@ -183,6 +194,11 @@ const OPEN: Task["state"][] = ["proposed", "in_progress", "changes_requested"];
 const QUIET_EVENTS = new Set(["answer", "reviewer changed", "idle sweep", "memory reference started"]);
 QUIET_EVENTS.add("ready held"); // #655: the hub's note that a ready task waits for its reserved owner's WIP slot.
 QUIET_EVENTS.add("plan observed"); // Host observation does not move the task or replace completion intent.
+/** The records of the `done (checking)` entry a passed check now completes: what the owner delivered then (#509a). */
+const latestPendingDeliverables = (task: Task): DeliverableRecord[] | undefined => {
+  const checking = task.history.findLastIndex(entry => entry.event === "done (checking)");
+  return checking >= 0 && !task.history.slice(checking + 1).some(entry => entry.event === "done") ? task.history[checking]!.deliverables : undefined;
+};
 
 /**
  * Thrown when an assignment's board write is saved but a publish or notify after it failed (#297): the move is
@@ -358,6 +374,12 @@ export class Tasks {
   };
 
   /** One bounded screen call. A screener that fails is no verdict, handled as PII (fail closed). */
+  private requestCheck(by: PeerId): () => void {
+    const authority = this.d.requestAuthority?.(by);
+    const check = () => { const reason = authority?.(); if (reason) throw new PreEffectToolRefusal(reason); };
+    check(); return check;
+  }
+
   private async screenCall(text: string): Promise<PiiVerdict> {
     return (await this.d.piiScreen?.(text).catch(() => undefined)) ?? { label: "unknown", miss: "failed", ms: 0 };
   }
@@ -559,6 +581,31 @@ export class Tasks {
   }
 
   /** Host-authored proposals contain only cleared IDs, integer task references and fixed instruction targets. */
+  /**
+   * #736: how many separate pieces of work the tasks are. Tasks that share a PR, a branch in one repository, or a
+   * supersession (a cancelled task names its replacement) are one piece of work, as an approve-as-step follow-up is: a
+   * finding carried between them is the same finding, not a recurrence.
+   */
+  private workUnits(rows: readonly Task[]): number {
+    const parent = new Map<number, number>();
+    const find = (id: number): number => { let at = id; while (parent.has(at)) at = parent.get(at)!; return at; };
+    const join = (a: number, b: number) => { const x = find(a), y = find(b); if (x !== y) parent.set(x, y); };
+    const first = new Map<string, number>(), ids = new Set(rows.map(row => row.id));
+    for (const row of rows) {
+      // Repository identity comes from the board's own resolver, so aliases match and an outside path never falls back to this project.
+      const prRepo = row.sdlc?.pr ? this.repositories.scope(row.sdlc.repo ? { repo: row.sdlc.repo, paths: row.refs.paths } : row.refs).key : "";
+      const branchRepo = row.refs.branch ? this.repositories.scope(row.refs).key : "";
+      for (const key of [prRepo ? `pr ${prRepo}#${row.sdlc!.pr}` : "", branchRepo ? `branch ${branchRepo} ${row.refs.branch}` : ""]) {
+        if (!key) continue;
+        const seen = first.get(key);
+        if (seen === undefined) first.set(key, row.id); else join(row.id, seen);
+      }
+      // superseded_by is free text ("task #73", "#73" or "73"); the first task number in it names the replacement.
+      const next = Number(/#?(\d+)/.exec(row.cancelled?.supersededBy ?? "")?.[1]);
+      if (ids.has(next)) join(row.id, next);
+    }
+    return new Set(rows.map(row => find(row.id))).size;
+  }
   private proposeRecurringFindings(task: Task, by: PeerId, items: readonly ReviewFinding[], withheld: boolean): void {
     if (withheld || this.isPii(task) || this.d.privateTurn?.(by) || !items.length || !this.findingTextAllowed(task, items)) return;
     const rows = this.d.board.list();
@@ -574,7 +621,7 @@ export class Tasks {
         const finding = last?.reviewFindings?.items.find(value => value.id === item.id);
         return !last?.withheld && finding && same(finding) && finding.disposition !== "false_positive" && this.findingTextAllowed(row, [finding]);
       });
-      if (new Set(holders.map(row => row.id)).size < 2) continue;
+      if (this.workUnits(holders) < 2) continue;
       const key = `Review finding key: ${item.pass}:${item.id}`;
       if (keys.has(key)) continue;
       const title = `Review policy amendment for recurring finding ${item.pass}:${item.id}`;
@@ -608,6 +655,8 @@ export class Tasks {
       ...(h.owner === undefined ? {} : { owner: h.owner }),
       ...(h.reviewerFamily ? { reviewerFamily: screenHistoryText(h.reviewerFamily, "reviewer family") } : {}),
       ...(h.reviewerReason ? { reviewerReason: h.reviewerReason } : {}),
+      ...(h.unmetCriteria?.length ? { unmetCriteria: h.unmetCriteria } : {}),
+      ...(h.deliverables?.length ? { deliverables: publicDeliverables(h.deliverables, this.nameable) } : {}),
       ...(h.reviewBlocked ? { reviewBlocked: true } : {}),
       ...(h.reviewerFailure ? { reviewerFailure: { peer: screenHistoryText(h.reviewerFailure.peer, "reviewer"), cause: h.reviewerFailure.cause, ...(h.reviewerFailure.head ? { head: screenHistoryText(h.reviewerFailure.head, "review head") } : {}) } } : {}),
       ...(h.planning ? { planning: { revision: h.planning.revision, fields: h.planning.fields, ...(h.planning.split ? { children: h.planning.split.children.map(child => child.id) } : {}) } } : {}),
@@ -745,10 +794,19 @@ export class Tasks {
   }
 
   /** What assignment weighs besides states and policy: quota, demotion and the review record. */
+  /**
+   * #525-3: the settled planner holders, sorted: the one input of the planner walk. It comes from the same settled role map as planner
+   * authority (`d.roles`), restricted to rostered peers, so assignment, planner notices and `route explain` agree on who the holders are.
+   * Read-only for now: the walk's result is shown and recorded nowhere until 525-2.
+   */
+  private plannerHolders(): PeerId[] {
+    return Object.entries(this.d.roles ?? {}).filter(([peer, roles]) => Array.isArray(roles) && roles.includes("planner") && this.d.bus.isRostered(peer)).map(([peer]) => peer).sort();
+  }
+
   private weights(cls: TaskClass, task?: Task) {
     const now = Date.now();
     const quota = this.d.quota?.();
-    return { ...this.health(), ...(task ? { reviewPool: this.reviewPoolOptions(task) } : {}), now, demoted: this.demoted(cls, now), reviews: this.reviewRecord(cls), ...(quota ? { quota } : {}), ...(this.d.review?.adaptive ? { adaptive: { min: this.d.review.min_reviews } } : {}) };
+    return { ...this.health(), planners: this.plannerHolders(), ...(task ? { reviewPool: this.reviewPoolOptions(task) } : {}), now, demoted: this.demoted(cls, now), reviews: this.reviewRecord(cls), ...(quota ? { quota } : {}), ...(this.d.review?.adaptive ? { adaptive: { min: this.d.review.min_reviews } } : {}) };
   }
 
   /**
@@ -1382,6 +1440,7 @@ export class Tasks {
   }
 
   async propose(by: PeerId, input: { title?: string; detail?: string; class?: string; role?: unknown; refs?: TaskRefs; plan?: TaskPlan; owner?: PeerId; after?: unknown; urgent?: unknown; backlog?: unknown; goal?: unknown }, external?: GitHubSource, created?: () => void): Promise<Task> {
+    const requestCheck = this.requestCheck(by);
     external = external ? { ...external } : undefined;
     if (external && (by !== USER || input.backlog !== true)) throw new PreEffectToolRefusal("external intake requires person-owned backlog staging");
     if (input.backlog !== undefined && typeof input.backlog !== "boolean") throw new PreEffectToolRefusal("backlog must be a boolean");
@@ -1426,6 +1485,7 @@ export class Tasks {
     // board, in no envelope and before no other model. A pattern match is PII without a call; no verdict is PII too.
     const screening = this.screenOn();
     const screened = screening && !signals.includes("pii") ? await this.screenCall(screenText({ ...text, detail: screenDetail, plan })) : undefined;
+    requestCheck();
     if (screened && screened.label !== "clear") signals.push("pii");
     let cls = baseGiven;
     let triaged = false;
@@ -1433,8 +1493,11 @@ export class Tasks {
     if (!cls && this.d.triage) {
       // Signals first: a PII task's text may only go to a model that is reached without leaving the campus network.
       const pii = this.isPii({ signals });
-      if (!pii || (await this.d.triage.onCampus().catch(() => false))) cls = await this.d.triage.classify(text.title, text.detail).catch(() => undefined);
+      const reached = !pii || await this.d.triage.onCampus().catch(() => false);
+      requestCheck();
+      if (reached) cls = await this.d.triage.classify(text.title, text.detail).catch(() => undefined);
       else fenced = true;
+      requestCheck();
       triaged = !!cls;
     }
     // A claim is work the caller will do itself: without a class and a model to name one, it is implementation (#6).
@@ -1450,6 +1513,7 @@ export class Tasks {
     if (reserved) this.requireCapabilities({ ...draft, signals, ...(external ? { external } : {}) }, reserved);
     this.warmRepository({ refs: draft.refs, plan });
     const repositoryMismatch = !this.isPii({ signals }) && this.repositories.mismatch(draft.refs, plan);
+    requestCheck();
     let task = this.d.board.propose(by, { ...draft, plan, ...(external ? { external } : {}), ...(deps.length ? { deps } : {}), ...(reserved ? { reserved } : {}), signals, ...(backlog ? { backlog: true } : {}) });
     if (repositoryMismatch) this.releaseNotice(`task #${task.id}: refs and plan name different repositories; check refs.repo before editing`);
     if (this.d.coordination) this.coordinationModes.set(task.id, this.d.coordination());
@@ -2741,7 +2805,23 @@ export class Tasks {
   }
 
   /** Artifact links and claimed local gates stay on the board; no outside text is accepted. */
-  recordLifecycle(by: PeerId, id: unknown, input: unknown): Task {
+  /**
+   * `hub_sdlc_record` (#509a): the receipt may also name `deliverables`. They are split off here, claims vetted and the files hashed by the hub,
+   * and only then is the rest recorded as before. A receipt with deliverables and nothing else records just the deliverables.
+   */
+  async recordSdlc(by: PeerId, id: unknown, input: unknown): Promise<Task> {
+    if (!input || typeof input !== "object" || Array.isArray(input) || !("deliverables" in input)) return this.recordLifecycle(by, id, input);
+    const { deliverables, ...receipt } = input as Record<string, unknown>;
+    const task = this.need(id, false, true);
+    if (by !== USER && by !== task.owner && by !== task.reviewer) throw new PreEffectToolRefusal("only the task owner, reviewer or console user may record lifecycle evidence");
+    const claims = this.deliverableClaims(deliverables, task);
+    const records = await this.hashClaims(claims, task, true);
+    const current = this.need(id, false, true);
+    if (current.history.length !== task.history.length) throw new PreEffectToolRefusal("task changed while its deliverables were hashed; record them again");
+    return this.recordLifecycle(by, id, receipt, records);
+  }
+
+  recordLifecycle(by: PeerId, id: unknown, input: unknown, deliverables?: DeliverableRecord[]): Task {
     const task = this.need(id, false, true);
     if (by !== USER && by !== task.owner && by !== task.reviewer) throw new PreEffectToolRefusal("only the task owner, reviewer or console user may record lifecycle evidence");
     const config = this.d.sdlc?.config() ?? sdlcConfig(undefined);
@@ -2771,7 +2851,7 @@ export class Tasks {
     if (next.reviewedHead !== undefined && (next.reviewedHead !== task.sdlc?.reviewedHead || (suppliedHead && artifactChanged))) this.mine(task, by, "reviewer", true);
     const departure = task.history.findLast(h => h.by === USER && h.planDeparture)?.planDeparture;
     const invalidatesDeparture = !!departure && (artifactChanged || next.localHead !== task.sdlc?.localHead && next.localHead !== undefined && next.localHead !== departure.head || next.reviewedHead !== task.sdlc?.reviewedHead && next.reviewedHead !== undefined && next.reviewedHead !== departure.head);
-    return this.d.board.update(task.id, by, "lifecycle", { sdlc: next }, undefined, { ...this.planObservation({ ...task, sdlc: next }), ...(invalidatesDeparture ? { planDepartureInvalidated: true } : {}) });
+    return this.d.board.update(task.id, by, "lifecycle", { sdlc: next }, undefined, { ...this.planObservation({ ...task, sdlc: next }), ...(invalidatesDeparture ? { planDepartureInvalidated: true } : {}), ...(deliverables ? { deliverables } : {}) });
   }
 
   async deliveryQueue(repo: string) {
@@ -2981,7 +3061,9 @@ export class Tasks {
     const task = this.need(id, false, true), config = this.d.sdlc?.config() ?? sdlcConfig(undefined);
     if (config.mode === "off" || by === USER || !input || typeof input !== "object" || !("stage" in input)) return;
     let next: ReturnType<typeof sdlcReceipt>;
-    try { next = sdlcReceipt(input, task.sdlc, config, VERSION); } catch { return; } // recordLifecycle reports an invalid receipt
+    // #509a: `deliverables` ride in the receipt but are not a lifecycle field: recordSdlc splits them off, so the gate reads the same receipt it will record.
+    const { deliverables: _carried, ...lifecycleInput } = input as Record<string, unknown>;
+    try { next = sdlcReceipt(lifecycleInput, task.sdlc, config, VERSION); } catch { return; } // recordLifecycle reports an invalid receipt
     const definition = stageDefinition(config, next.stage);
     if (next.stage === task.sdlc?.stage || !definition || canonicalStage(definition.base) !== "build") return;
     const accepted = next.acceptance;
@@ -3059,6 +3141,7 @@ export class Tasks {
     return base === "build" || base === "implement";
   }
   async acceptReviewed(by: PeerId, id: unknown, plan?: unknown, refs?: unknown): Promise<Task> {
+    const requestCheck = this.requestCheck(by);
     const metadata = acceptRefs(refs);
     const task = this.need(id, false, true);
     this.mine(task, by, "owner", true);
@@ -3069,6 +3152,7 @@ export class Tasks {
     if ((this.d.sdlc?.config() ?? sdlcConfig(undefined)).mode === "off" || !this.isBuildTask(task)) return this.accept(by, id, plan, metadata);
     await this.specGate(by, id);
     await this.planEntryGate(by, draft);
+    requestCheck();
     const current = this.need(id, false, true);
     this.mine(current, by, "owner", true);
     if (current.history.length !== task.history.length || current.owner !== task.owner) throw new PreEffectToolRefusal("task changed during build admission");
@@ -3225,6 +3309,59 @@ export class Tasks {
     return this.assignOwner(back, HUB, { event: "reassigned", reason: "declined", clearOnFail: true, ...(capacity === true && task.owner ? { exclude: [task.owner] } : {}), ...(planned ? { planner: true } : {}) });
   }
 
+  /**
+   * #509a: the task's deliverables as they are now against what was delivered and what was approved. `changedSinceReview` is true only for a file
+   * measured to differ from the bytes a reviewer approved (or, before approval, from the bytes delivered); a file the hub cannot read is
+   * `unknown`, never `unchanged`. Ids, hashes and sizes only for a private record. Undefined when the task delivered nothing.
+   */
+  async deliverableStatus(task: Task): Promise<{ state: "none" | "delivered" | "approved"; changedSinceReview: boolean; files: DeliverableStatus[] } | undefined> {
+    const delivered = latestDeliverables(task.history);
+    if (!delivered) return undefined;
+    const approved = task.state === "approved" ? approvedDeliverables(task.history) : undefined;
+    const basis = approved ?? delivered;
+    const checks = await this.checkRecords(basis, task);
+    const shown = publicDeliverables(basis, this.nameable)!;
+    const files = checks.map((check, i): DeliverableStatus => {
+      const { sha256, id, format, version, path, private: hidden } = shown[i]!;
+      return { id, sha256, state: check.state, ...(path ? { path } : {}), format, ...(version ? { version } : {}), ...(hidden ? { private: true as const } : {}) };
+    });
+    return { state: approved ? "approved" : "delivered", changedSinceReview: files.some(file => file.state === "changed"), files };
+  }
+
+  /** Check records against the owner's root; with that root unproven every file is `unknown` (never `unchanged`, never an exception). */
+  private async checkRecords(records: DeliverableRecord[], task: Task) {
+    try { return await checkDeliverables(records, this.deliverablePorts(task)); }
+    catch (error) { return records.map(record => ({ record, state: "unknown" as const, why: error instanceof Error ? error.message : "unreadable" })); }
+  }
+
+  /** What the deliverable reader needs from the host: the project root, the secrets denylist, and which files make a record private (#509a). */
+  private deliverablePorts(task: Task): DeliverablePorts {
+    const taskPrivate = this.isPii(task);
+    // The owner's own root: a declared worktree instance writes under its worktree, so its deliverables are hashed there, never in the canonical
+    // checkout (which holds a different file or none). With the root unproven there is nothing safe to hash: refuse rather than guess.
+    const root = !this.d.executionRoot || !task.owner || task.owner === USER ? this.d.cwd : this.d.executionRoot(task.owner);
+    if (root === undefined) throw new DeliverableRefusal(`deliverables: ${task.owner}'s execution root is not verified right now, so its files cannot be hashed`);
+    return { cwd: root, deny: this.d.deny ?? [], private: path => taskPrivate || matchesPolicy(root, path, this.d.piiPaths ?? [], true) };
+  }
+
+  /**
+   * #509a: parse and vet a call's deliverable claims before any effect. A claimed hash is a refusal (the hub hashes the files itself), and so is a
+   * path outside the project, on the denylist, inside the hub's own state, not a regular file, missing or too large. Nothing is hashed or stored here.
+   */
+  private deliverableClaims(input: unknown, task: Task, preEffect = true) {
+    try {
+      const claims = parseDeliverableClaims(input);
+      vetDeliverables(claims, this.deliverablePorts(task));
+      return claims;
+    } catch (error) { throw new (preEffect ? PreEffectToolRefusal : Error)(error instanceof Error ? error.message : "invalid deliverables"); }
+  }
+
+  /** Hash vetted claims now. A refusal during the read (the file changed while it was read) is still before any write. */
+  private async hashClaims(claims: ReturnType<Tasks["deliverableClaims"]>, task: Task, preEffect = true): Promise<DeliverableRecord[]> {
+    try { return await hashDeliverables(claims, this.deliverablePorts(task)); }
+    catch (error) { throw new (preEffect ? PreEffectToolRefusal : Error)(error instanceof DeliverableRefusal || error instanceof Error ? error.message : "deliverables could not be hashed"); }
+  }
+
   /** Tasks whose check is queued or running, and the owner it was started for. */
   private readonly checking = new Map<number, PeerId | null>();
   private checkQueue: Promise<void> = Promise.resolve();
@@ -3252,11 +3389,17 @@ export class Tasks {
     return task;
   }
 
-  async done(by: PeerId, id: unknown, summary?: string, refs?: TaskRefs): Promise<Task> {
-    const valid = () => this.completionCurrent(id, by, true);
+  async done(by: PeerId, id: unknown, summary?: string, refs?: TaskRefs, deliverables?: unknown): Promise<Task> {
+    const requestCheck = this.requestCheck(by);
+    const valid = () => { requestCheck(); return this.completionCurrent(id, by, true); };
+    // #509a: a bad claim (a claimed hash, an outside or denied path, a missing file) is refused before any effect, with nothing recorded.
+    const claims = deliverables === undefined ? undefined : this.deliverableClaims(deliverables, valid());
     // The PII screen reads the summary of a done that passes these checks (issue #198); they run again after it.
     const withheld = await this.withholds("summary", summary, valid());
     let task = valid();
+    // The hub hashes the files itself, once, here: what the owner delivered is what this read, whatever the file becomes afterwards.
+    const records = claims ? await this.hashClaims(claims, task, true) : undefined;
+    task = valid();
     // #481 S1: done without a separate accept starts build work too: the same live spec check as accept, before any write.
     if (task.state === "proposed" || task.state === "changes_requested") {
       const admission = task;
@@ -3302,12 +3445,12 @@ export class Tasks {
     }
     if (task.state === "proposed" || task.state === "changes_requested") task = this.withLink(this.d.board.update(task.id, by, "accepted", { state: "in_progress" }, WITH_DONE), link, refs); // done without a separate accept
     const command = this.d.runCheck ? this.d.check?.(task.class, task) : undefined;
-    if (!command) return this.complete(task, by, summary, refs, "", withheld, "review", reviewAdmission, link);
+    if (!command) return this.complete(task, by, summary, refs, "", withheld, "review", reviewAdmission, link, records, requestCheck);
     // The tool call returns now; a check can outlast an agent's tool timeout. The result decides what comes next.
     this.checking.set(task.id, task.owner);
     const checkedRefs = cleanRefs(refs);
     this.warmRepository({ ...task, refs: { ...task.refs, ...checkedRefs } });
-    const pending = this.d.board.update(task.id, by, "done (checking)", { codeSymbols: this.observedCodeSymbols({ ...task, refs: { ...task.refs, ...checkedRefs } }), refs: checkedRefs, ...(task.sdlc ? { sdlc: task.sdlc } : {}) }, summary, { withheld: withheld || undefined }, task.history.length, HOST_CODE_SYMBOLS);
+    const pending = this.d.board.update(task.id, by, "done (checking)", { codeSymbols: this.observedCodeSymbols({ ...task, refs: { ...task.refs, ...checkedRefs } }), refs: checkedRefs, ...(task.sdlc ? { sdlc: task.sdlc } : {}) }, summary, { withheld: withheld || undefined, ...(records ? { deliverables: records } : {}) }, task.history.length, HOST_CODE_SYMBOLS);
     this.releaseNotice(`task ${this.publicTitle(pending)} done by ${by}; its check is queued or running: ${command}`);
     const seen = { events: pending.history.length, owner: pending.owner };
     this.pendingChecks++;
@@ -3438,11 +3581,15 @@ export class Tasks {
   }
 
   /** `gated`: the transition `done()` already gated with no await since, so it is not read back twice (#382). */
-  private async complete(task: Task, by: PeerId, summary?: string, refs?: TaskRefs, checkOutput = "", withheld = false, gated?: "review", admission?: ReviewReadiness, link?: IdentityLink): Promise<Task> {
+  private async complete(task: Task, by: PeerId, summary?: string, refs?: TaskRefs, checkOutput = "", withheld = false, gated?: "review", admission?: ReviewReadiness, link?: IdentityLink, records?: DeliverableRecord[], requestCheck: () => void = () => {}): Promise<Task> {
+    requestCheck();
+    // A check's completion carries the records its `done (checking)` bound: the same bytes the owner delivered, not a later read.
+    records ??= latestPendingDeliverables(task);
     let selection = this.poolReview(task, refs);
     let reviewer = selection?.reviewer ?? task.reviewer, reviewEvidence: PrEvidence | undefined;
     if (this.d.sdlc && this.d.sdlc.config().mode !== "off" && gated !== (reviewer ? "review" : "approval")) {
       reviewEvidence = await this.lifecycleGate(task, reviewer ? "review" : "approval");
+      requestCheck();
       task = this.withLink(this.completionCurrent(task.id, by, false), link, refs);
       selection = this.poolReview(task, refs);
       reviewer = selection?.reviewer ?? task.reviewer;
@@ -3450,6 +3597,7 @@ export class Tasks {
     // A delayed local check needs a new readback; a completion-selected reviewer also needs optional facts in off mode.
     if (!admission && ((reviewer && (this.d.sdlc?.config().mode ?? "off") !== "off") || this.d.prepareReviewBrief)) {
       admission = await this.reviewRequestAdmission(task, refs, false, by, reviewEvidence, undefined, staged => this.withLink(staged, link, refs), !reviewer);
+      requestCheck();
       task = this.withLink(this.completionCurrent(task.id, by, false), link, refs);
     }
     selection = this.poolReview(task, refs);
@@ -3460,7 +3608,7 @@ export class Tasks {
     const completedRefs = cleanRefs(refs);
     this.warmRepository({ ...task, refs: { ...task.refs, ...completedRefs } });
     const noWrites = this.noWritesRecorded({ ...task, refs: { ...task.refs, ...completedRefs } });
-    const next = this.d.board.update(task.id, by, "done", { codeSymbols: this.observedCodeSymbols({ ...task, refs: { ...task.refs, ...completedRefs } }), state: reviewer ? "in_review" : "approved", ...(selection ? { reviewer: reviewer ?? USER } : {}), ...(task.sdlc ? { sdlc: { ...task.sdlc, stage: lifecycleStage(this.d.sdlc?.config() ?? sdlcConfig(undefined), reviewer ? "review" : "merge") } } : {}), refs: completedRefs }, checkOutput ? `${routedSummary ?? ""}\n${checkOutput}`.trim() : routedSummary, { ...this.planObservation(task), withheld: withheld || undefined, ...(noWrites ? { noWrites: true as const } : {}), ...this.reviewMetadata(selection), ...(reviewCost ? { reviewCost } : {}) }, task.history.length, HOST_CODE_SYMBOLS);
+    const next = this.d.board.update(task.id, by, "done", { codeSymbols: this.observedCodeSymbols({ ...task, refs: { ...task.refs, ...completedRefs } }), state: reviewer ? "in_review" : "approved", ...(selection ? { reviewer: reviewer ?? USER } : {}), ...(task.sdlc ? { sdlc: { ...task.sdlc, stage: lifecycleStage(this.d.sdlc?.config() ?? sdlcConfig(undefined), reviewer ? "review" : "merge") } } : {}), refs: completedRefs }, checkOutput ? `${routedSummary ?? ""}\n${checkOutput}`.trim() : routedSummary, { ...this.planObservation(task), withheld: withheld || undefined, ...(noWrites ? { noWrites: true as const } : {}), ...this.reviewMetadata(selection), ...(reviewCost ? { reviewCost } : {}), ...(records ? { deliverables: records } : {}) }, task.history.length, HOST_CODE_SYMBOLS);
     this.cohorts.closed(next.id); // its owner's next native turn end settles it in its cohort (issue #107)
     this.note(next, by, "finding", `Task #${next.id} done by ${by}: ${next.title}\n${summary ?? ""}`, withheld);
     this.tellCompleted(next, summary, withheld);
@@ -3650,7 +3798,19 @@ export class Tasks {
     const checklistLines = checklistTemplates.map(template =>
       template.replaceAll("{target}", target).replaceAll("{check}", checkResult)
     );
-    const checklist = [
+    // #507b: the task's recorded acceptance criteria (the #481 S8 checklist, ids and all). A PII task shows none: its checklist is private.
+    const recorded = this.isPii(task) ? undefined : checklistOf(task.sdlc);
+    const criteriaBlock = recorded?.criteria.length
+      ? ["Acceptance criteria (name an id at the start of an unmet item, such as \"AC1: what is missing\"):",
+        ...recorded.criteria.map(c => `- ${c.id}${c.required ? "" : " (optional)"}: ${c.result}`)].join("\n") + "\n"
+      : "";
+    // #509a: what was delivered, by id, hash and size. A private record (a PII task, or a path under pii.paths) shows no path.
+    const delivered = publicDeliverables(latestDeliverables(task.history), this.nameable);
+    const deliverablesBlock = delivered?.length
+      ? ["Deliverables (the hub hashed these files when the task was done; approval binds these hashes):",
+        ...delivered.map(d => `- ${d.id}: ${d.path ?? "(path withheld)"} [${d.format}${d.version ? ` ${d.version}` : ""}] sha256 ${d.sha256.slice(0, 16)}, ${d.bytes} bytes`)].join("\n") + "\n"
+      : "";
+    const checklist = deliverablesBlock + criteriaBlock + [
       "Checklist:",
       ...this.planGuardItems(task).map(item => `- Check the plan against this live fail before the remaining checks: ${item.line}`),
       ...checklistLines.map(line => `- ${line}`),
@@ -3829,6 +3989,28 @@ export class Tasks {
       const checked = sdlcReceipt({ reviewedHead: head }, task.sdlc, this.d.sdlc?.config() ?? sdlcConfig(undefined));
       reviewedHead = checked.reviewedHead;
     }
+    // #509a: an approval binds the bytes that were delivered. The files are read again now: unchanged, their hashes go on the approval; changed,
+    // missing or unreadable, a reviewer's approval is refused before any write, and the person may approve the files as they are, saying so.
+    let boundDeliverables: DeliverableRecord[] | undefined;
+    if (verdict === "approved") {
+      const delivered = latestDeliverables(task.history);
+      if (delivered) {
+        const identity = JSON.stringify(delivered);
+        const checks = await this.checkRecords(delivered, task);
+        task = valid();
+        if (JSON.stringify(latestDeliverables(task.history)) !== identity) throw new PreEffectToolRefusal("the task's deliverables changed during the verdict; review the current work again");
+        const drift = checks.filter(check => check.state !== "unchanged");
+        if (!drift.length) boundDeliverables = delivered;
+        else {
+          const text = drift.map(check => `${check.record.id} (${check.state})`).join(", ");
+          if (by !== USER) throw new PreEffectToolRefusal(`deliverable changed since it was delivered: ${text}; ask its owner to call hub_task_done again so the current files are reviewed, or a person may approve them as they are`);
+          // The person approves what is on disk now: those bytes are measured and bound, and the verdict says the files had moved.
+          boundDeliverables = await this.hashClaims(delivered.map(record => ({ path: record.path!, format: record.format, ...(record.version !== undefined ? { version: record.version } : {}) })), task, true);
+          task = valid();
+          note = `${note ?? ""}\nApproved with the deliverable files changed since delivery: ${text}`.trim();
+        }
+      }
+    }
     if (verdict === "approved" && this.d.sdlc && this.d.sdlc.config().mode !== "off") { await this.lifecycleGate(task, "approval", reviewedHead, proposedSets(task)); task = valid(); }
     let candidate: Extract<CandidateInput, { kind: "fail" }> | undefined;
     if (verdict === "changes_requested" && items.length && this.d.candidates && !withheld && !this.isPii(task) && !this.d.privateTurn?.(by)) {
@@ -3847,7 +4029,10 @@ export class Tasks {
     const family = by === USER ? undefined : (this.d.adapterCatalog?.familyOf ?? familyOf)(by, this.d.instances?.());
     const reviewerFamily = poolRequest?.reviewerFamily === family ? family : undefined;
     const reviewerReason = reviewerFamily ? poolRequest?.reviewerReason : undefined;
-    const flag = { ...this.planObservation(task), withheld: withheld || undefined, ...(report ? { reviewFindings: report } : {}), ...(reviewContext ? { reviewContext } : {}), ...(reviewerFamily ? { reviewerFamily } : {}), ...(reviewerReason ? { reviewerReason } : {}) };
+    // #507b: unmet items that start with a recorded criterion id name that criterion. The ids come from the checklist on the board as it is at this
+    // write (the `task` just rechecked by valid()), never from the caller; a PII task carries none, its checklist being private.
+    const unmetCriteria = pii ? [] : unmetCriteriaIds(items, checklistOf(task.sdlc));
+    const flag = { ...this.planObservation(task), withheld: withheld || undefined, ...(report ? { reviewFindings: report } : {}), ...(unmetCriteria.length ? { unmetCriteria } : {}), ...(boundDeliverables ? { deliverables: boundDeliverables } : {}), ...(reviewContext ? { reviewContext } : {}), ...(reviewerFamily ? { reviewerFamily } : {}), ...(reviewerReason ? { reviewerReason } : {}) };
     if (verdict === "approved") {
       const next = this.d.board.update(task.id, by, "approved", { state: "approved", rejections: 0, ...(reviewedHead && task.sdlc ? { sdlc: { ...task.sdlc, reviewedHead, stage: lifecycleStage(this.d.sdlc?.config() ?? sdlcConfig(undefined), "merge") } } : {}) }, note, flag);
       if (next.owner) {
@@ -4147,6 +4332,7 @@ export class Tasks {
   }
 
   async remember(by: PeerId, input: { text?: string; title?: string; kind?: string; task?: unknown; horizon?: unknown; scope?: unknown; approach?: unknown; symptom?: unknown; cause?: unknown; evidence?: unknown; retry_when?: unknown }): Promise<string> {
+    const requestCheck = this.requestCheck(by);
     const text = composeRememberText(input);
     const task = input.task !== undefined ? this.d.board.get(Number(input.task)) : undefined;
     if (task && this.isPii(task)) throw new Error("notes about a PII task are not saved: claude-mem processes what it stores with a cloud model");
@@ -4160,6 +4346,7 @@ export class Tasks {
     if (looksSecret(`${title}\n${text}`)) throw new Error("this note looks like it holds a secret (a key, token or password) and is not saved");
     if (this.aboutPrivatePath(title, text, task)) throw new Error("this note is about a path the project keeps private (pii.paths) and is not saved");
     if (await this.withholds("note", `${title}\n${text}`, task)) throw new Error("the PII screen did not clear this note, so it is not saved: claude-mem processes what it stores with a cloud model");
+    requestCheck();
     const kind = (NOTE_KINDS as readonly string[]).includes(String(input.kind)) ? String(input.kind) as Kind : "finding";
     const native = this.saveNative(by, kind, text, title, task, input.horizon === "long" || input.horizon === "short" ? input.horizon : undefined, input.scope === "shared" ? "shared" : "project");
     if (task && this.d.memory) this.markMemoryReference(task, by);

package/src/hub/token-window.ts

@@ -0,0 +1,33 @@
+/**
+ * A rolling window of counted tokens, by the time each was used (not the time it was read), so a row read late still ages out
+ * on schedule. The hub's own count against a ceiling a person configured, never the provider's quota (#285).
+ */
+export class TokenWindow {
+  private rows: { at: number; n: number }[] = [];
+  constructor(private readonly spanMs: number) {}
+
+  add(at: number, n: number): void {
+    if (!Number.isFinite(at) || !Number.isSafeInteger(n) || n <= 0) return;
+    const index = this.rows.findIndex(row => row.at > at);
+    if (index < 0) this.rows.push({ at, n }); else this.rows.splice(index, 0, { at, n });
+  }
+
+  private prune(now: number): void {
+    let drop = 0;
+    while (drop < this.rows.length && now - this.rows[drop]!.at > this.spanMs) drop++;
+    if (drop) this.rows.splice(0, drop);
+  }
+
+  sum(now: number): number {
+    this.prune(now);
+    return this.rows.reduce((total, row) => total + row.n, 0);
+  }
+
+  /** When the oldest counted token was used: the window frees its first share at this time plus its span. */
+  oldest(now: number): number | undefined {
+    this.prune(now);
+    return this.rows[0]?.at;
+  }
+
+  reset(): void { this.rows = []; }
+}

package/src/hub/usage-rollup.ts

@@ -101,7 +101,8 @@ export class UsageRollup {
    * Fold the next slice of the log. Whole lines only: a trailing partial line (a crash, or a write in flight) waits for the next pass.
    * A log that is shorter than the stored offset was replaced or reset, so the roll-up starts over from byte 0.
    */
-  poll(): { bytes: number; done: boolean } {
+  poll(maxMs = 20): { bytes: number; done: boolean } {
+    const deadline = performance.now() + Math.max(0, Math.min(20, maxMs));
     if (this.closed) return { bytes: 0, done: true };
     if (!existsSync(this.eventsFile)) return { bytes: 0, done: true };
     const fd = openSync(this.eventsFile, "r");
@@ -127,18 +128,27 @@ export class UsageRollup {
         want = Math.min(size - offset, want * 2);
       }
       if (end < 0) return { bytes: 0, done: true };                    // the last line is still being written: it waits for the next pass
-      const text = buffer.subarray(0, end + 1).toString("utf8");
+      let consumed = 0;
       // The offset was read before the slice was; another roll-up on this hub.db (a restart that overlaps the old process) may have folded the same
       // bytes since. The transaction takes the write lock first and checks the stored offset again: a pass whose start is stale is abandoned whole,
       // so a byte range is folded exactly once however many writers there are (found by a forced interleave: the counts doubled).
       const applied = this.db.transaction(() => {
         if (this.state().offset !== offset) return false;
-        for (const line of text.split("\n")) this.fold(line);
-        this.db.query("UPDATE rollup_state SET byte_offset = ? WHERE id = 1").run(offset + end + 1);
+        // Commit only complete processed records with their offset. Yield between records;
+        // ponytail: one whole record and the existing corrupt-line skip are indivisible;
+        // a streaming parser would be needed to preempt within either operation.
+        for (let start = 0; start <= end;) {
+          const newline = buffer.indexOf(0x0a, start);
+          if (newline < 0 || newline > end) break;
+          this.fold(buffer.subarray(start, newline).toString("utf8"));
+          consumed = newline + 1; start = consumed;
+          if (performance.now() >= deadline) break;
+        }
+        this.db.query("UPDATE rollup_state SET byte_offset = ? WHERE id = 1").run(offset + consumed);
         return true;
       }).immediate();
       if (!applied) return { bytes: 0, done: false };                   // stale: the next pass starts from the stored offset
-      return { bytes: end + 1, done: offset + end + 1 >= size };
+      return { bytes: consumed, done: offset + consumed >= size };
     } finally { closeSync(fd); }
   }
 
@@ -160,7 +170,7 @@ export class UsageRollup {
    */
   catchUp(maxMs?: number): boolean {
     const until = maxMs === undefined ? Infinity : Date.now() + maxMs;
-    for (let i = 0; i < 100_000; i++) { if (this.poll().done) return true; if (Date.now() >= until) return false; }
+    for (let i = 0; i < 100_000; i++) { if (this.poll(Math.min(20, until - Date.now())).done) return true; if (Date.now() >= until) return false; }
     return true;
   }
 

package/src/hub/workflow.ts

@@ -46,4 +46,20 @@ export function criteriaView(config: SdlcConfig, task: Task, isPrivate: (t: Task
   for (const criterion of checklist.criteria) if (criterion.required && criterion.result !== "verified") blockers.push(`criterion ${criterion.id}: ${criterion.result}`);
   return { id: checklist.id, ready: blockers.length === 0, blockers, criteria: checklist.criteria.map(c => ({ ...c, refs: [...c.refs] })), ...("tasks" in checklist && (checklist as LegacyPhaseReceipt).tasks.length ? { note: "stored checklist task list ignored: task import was retired (#481)" } : {}) };
 }
+/**
+ * #507b: which of a task's recorded acceptance criteria (the #481 S8 checklist, the only criteria model) a reviewer's unmet items name.
+ * An item names a criterion when it STARTS with that criterion's id, exactly (case and all), followed by the end of the item or a delimiter:
+ * `AC3: the overwrite case has no test`, or just `AC3`. An id the checklist does not hold is plain text, never a criterion, and an id in the
+ * middle of a sentence is not a claim. Pure: items in, ids out (in the order first named, each once).
+ */
+export function unmetCriteriaIds(items: readonly string[], checklist: Pick<CriteriaReceipt, "criteria"> | undefined): string[] {
+  if (!checklist) return [];
+  const known = new Set(checklist.criteria.map(c => c.id));
+  const named: string[] = [];
+  for (const item of items) {
+    const id = /^\s*([A-Za-z][A-Za-z0-9-]{0,47})(?=$|[\s:.,;)\]])/.exec(item)?.[1];
+    if (id !== undefined && known.has(id) && !named.includes(id)) named.push(id);
+  }
+  return named;
+}
 export function workflowHash(value: unknown): string { return createHash("sha256").update(JSON.stringify(value)).digest("hex"); }