@staix/agent-hub 0.18.0 → 0.20.0

package/src/hub/tasks.ts

@@ -1,4 +1,6 @@
 import { canonicalMemorySymbolNode, normalizeMemorySymbolInput, MEMORY_SYMBOL_LIMIT, type MemorySymbolNodes } from "./memory-symbols.ts";
+import { createHash } from "node:crypto";
+import { taskShellBindingValid, type TaskShellBinding } from "./task-shell-command.ts";
 import { buildTaskCodeSymbols, publicTaskCodeSymbols, taskCodeSymbolsDisjoint, HOST_CODE_SYMBOLS } from "./task-code-symbols.ts";
 import { normalizePlanSymbol, symbolsOverlap } from "./symbol-normalizer.ts";
 import { publicTestIntegrity, readTestIntegrity, testIntegrityBlockers, type TestIntegrity } from "./test-integrity.ts";
@@ -16,6 +18,7 @@ import { BACKLOG_SPLIT_SCREEN_TIMEOUT_MS, actualTaskDates, planningPatch, type P
 import { readMergeQueue, type DeliveryTask } from "./sdlc-queue.ts";
 import { guardedMerge, mergeModeFor, mergeView, type MergeView } from "./sdlc-merge.ts";
 import { mirrorVerdict as mirrorToGitHub, type MirrorVerdict } from "./sdlc-mirror.ts";
+import { CODE_SCOPE_LINE, evidenceOnlyNotice, type ReviewScope } from "./review-scope.ts";
 import { DEFAULT_MAX_NITS, parseReviewFindings, findingsForHead, findingHead as resolveFindingHead, findingTally, type ReviewFinding, type ReviewFindingSet } from "./review-findings.ts";
 import { readReleaseReadiness } from "./sdlc-release.ts";
 import { loadRoleCatalog, taskRole, taskRoleText, type RoleCatalog } from "./roles.ts";
@@ -46,6 +49,7 @@ import { coverageGap, renderReviewBrief, type ReviewBrief } from "./review-brief
 import { definitionOf as builtinDefinitionOf } from "../adapters/registry.ts";
 import { ADAPTERS, DEFAULT_REVIEW_POOL, definitionOf, familyOf, type ProjectAdapterCatalog } from "../adapters/registry.ts";
 import { plannerGrooming, nextSweep, taskSweepConfig, type TaskSweepConfig, type SweepRecord } from "./task-sweep.ts";
+import { CiWatchers, pollCi, type CiOutcome, type CiWatch } from "./ci-watch.ts";
 import { planningIssueReceipt, linkedReceipt, openPrFor, readPrCostHistory, readReviewReadiness, reviewReadinessFromEvidence, type PrEvidence, type ReviewReadiness, readPlanIssueMetadata, canonicalStage, checklistOf, readSdlcPr, readSpecEdit, sdlcConfig, sdlcReceipt, sdlcStatus, specState, SPEC_STATE_TEXT, stageDefinition, lifecycleStage, type SdlcConfig, type MergeRecord, type PlanIssueMetadata, sdlcGh, type SdlcGh, type SdlcStatus, type SpecEdit, type SpecState } from "./sdlc.ts";
 
 export type TaskAssignmentRole = "owner" | "reviewer" | "planner";
@@ -95,6 +99,10 @@ export interface TasksDeps {
   /** Host-verified existing symbols at this task's admitted completion head; never plan guesses. */
   memorySymbolNodes?: (task: Task) => MemorySymbolNodes | undefined;
   sdlc?: { config: () => SdlcConfig; gh?: SdlcGh };
+  /** #785 P1b: the per-head CI watcher's bounds; tests shorten them, the defaults are `CI_WATCH_*` in `ci-watch.ts`. */
+  ciWatch?: { deadlineMs?: number; pollMs?: number };
+  /** #785 P1c: `tasks.auto_pull`, read at each capacity release so a reload applies to the next one; absent or false pulls nothing. */
+  autoPull?: () => boolean;
   briefs?: Briefs;
   /** Screened live fail notes directly intersecting the task plan or refs; read-only advice. */
   planFails?: (task: Task) => NativeItem[];
@@ -104,6 +112,8 @@ export interface TasksDeps {
   privateTurn?: (peer: PeerId) => boolean;
   /** #223 R4: the hub's reading of a verdict's context (`fresh` only for a reviewer session started for this review). */
   reviewContext?: (by: PeerId, task: number) => "fresh" | "continuing" | undefined;
+  /** #852: what a reviewer reads. `code` (the fixed sandboxed reviewers by default, or a local `review_scope`) reads the code only; unset or `full` also runs tests and reads CI. */
+  reviewScope?: (peer: PeerId) => ReviewScope;
   /** #223 R2: a reviewer-only instance gets review facts, not the builder's done summary. */
   reviewOnly?: (peer: PeerId) => boolean;
   /** #223: captured when a verdict call starts; a non-undefined result refuses the verdict at every later check. */
@@ -202,6 +212,7 @@ const QUIET_EVENTS = new Set(["answer", "reviewer changed", "idle sweep", "memor
 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.
 QUIET_EVENTS.add("planner changed"); // Planning authority does not move the execution owner or revoke its handoff.
+QUIET_EVENTS.add("shell branch bound"); // #880: the hub's host-observed branch binding (#845) is bookkeeping; it neither moves nor settles the task.
 /** 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)");
@@ -349,8 +360,17 @@ export class Tasks {
   private sweepConfig: TaskSweepConfig;
   private readonly noWriteTurns = new NoWriteTurns();
   private sweeping = false;
+  /** #785 P1b: one bounded CI watcher per exact PR head, and the reviews the hub held as premature, by task id. */
+  private readonly ciWatchers: CiWatchers;
+  private readonly heldReviews = new Map<number, { head: string; reviewer: PeerId; revision: number }>();
 
   constructor(private readonly d: TasksDeps) {
+    this.ciWatchers = new CiWatchers({
+      ...d.ciWatch,
+      poll: watch => pollCi(watch, watch.head, d.sdlc?.config().requiredChecks ?? [], d.sdlc?.gh ?? sdlcGh),
+      current: watch => this.ciWatchCurrent(watch),
+      finish: (watch, outcome) => this.ciCompleted(watch, outcome),
+    });
     d.board.trackPlanRevisions = () => (d.sdlc?.config().mode ?? "off") !== "off";
     this.repositories = new TaskRepositories(d.cwd, d.repository);
     d.board.proposalPlanner = task => this.proposalPlanner(task);
@@ -698,6 +718,8 @@ export class Tasks {
       ...(h.selfReview ? { selfReview: true } : {}),
       ...(h.reviewerFamily ? { reviewerFamily: screenHistoryText(h.reviewerFamily, "reviewer family") } : {}),
       ...(h.reviewerReason ? { reviewerReason: h.reviewerReason } : {}),
+      ...(h.reviewScope === "code" ? { reviewScope: "code" as const } : {}),
+      ...(h.evidenceOnly ? { evidenceOnly: true as const } : {}),
       ...(h.unmetCriteria?.length ? { unmetCriteria: h.unmetCriteria } : {}),
       ...(h.deliverables?.length ? { deliverables: publicDeliverables(h.deliverables, this.nameable) } : {}),
       ...(h.reviewBlocked ? { reviewBlocked: true } : {}),
@@ -775,7 +797,7 @@ export class Tasks {
       if (h.owner === undefined || h.owner !== owner) since = i;
       owner = h.owner;
     });
-    return new Set(task.history.slice(since + 1).filter((h) => h.event === "changes_requested").map((h) => h.by));
+    return new Set(task.history.slice(since + 1).filter((h) => h.event === "changes_requested" && h.evidenceOnly !== true).map((h) => h.by));
   }
 
   /** Workload is board/queue data only: wip() never calls health() or weights(). */
@@ -872,7 +894,7 @@ export class Tasks {
         if (!OWNERSHIP_EVENTS.has(given.event) || given.event === "unassigned" || given.owner !== peer || given.profile !== profile || given.by === peer) return [];
         const next = t.history.findIndex((h, j) => j > i && OWNERSHIP_EVENTS.has(h.event));
         const span = t.history.slice(i + 1, next < 0 ? undefined : next + 1);
-        if (span.some((h) => failed.includes(h.event))) return [{ outcome: "failed" }];
+        if (span.some((h) => failed.includes(h.event) && h.evidenceOnly !== true)) return [{ outcome: "failed" }];
         if (next >= 0 || t.state !== "approved") return []; // handed on without a failure (a relay), or still open
         const accepted = span.find((h) => h.event === "accepted" && h.by === peer);
         // The work stage ends at its first done call: checks and an integration step are not the work itself.
@@ -1038,6 +1060,129 @@ export class Tasks {
   wip(peer: PeerId, except?: number): number {
     return this.d.board.plannerWip(peer, except);
   }
+
+  /** Host-observed task branch/root binding (#845), never a tool-call branch claim or an execution grant. */
+  bindShellBranch(peer: PeerId, id: number, binding: TaskShellBinding & { worktree: string }, current: () => boolean): boolean {
+    try {
+      if (!Number.isSafeInteger(id) || id < 1 || !taskShellBindingValid(binding) || !this.publicMetadataText(binding.branch)
+        || !current() || this.d.privateTurn?.(peer)) return false;
+      const task = this.d.board.get(id), root = this.d.executionRoot?.(peer);
+      if (!task || task.owner !== peer || !["in_progress", "changes_requested"].includes(task.state) || this.isPii(task)
+        || !root || realPath(root) === realPath(this.d.cwd) || realPath(root) !== realPath(binding.worktree)) return false;
+      const worktree = createHash("sha256").update(realPath(root)).digest("hex");
+      const previous = task.history.findLast(entry => entry.by === HUB && entry.event === "shell branch bound");
+      if (previous) {
+        const saved: unknown = JSON.parse(previous.note ?? "");
+        if (!saved || typeof saved !== "object" || Array.isArray(saved)) return false;
+        const record = saved as Record<string, unknown>;
+        if (record.branch !== binding.branch || record.worktree !== worktree) return false;
+      }
+      if (task.refs.branch !== undefined && task.refs.branch !== binding.branch) return false;
+      const scope = this.repositories.scope(task.refs);
+      const others = this.d.board.list().filter(row => row.id !== id && !isClosedTaskState(row.state))
+        .map(row => ({ row, scope: this.repositories.scope(row.refs) }));
+      if (scope.key !== this.repositories.project.key || others.some(other => other.scope.key === scope.key && other.row.refs.branch === binding.branch)) return false;
+      if (!current() || this.d.privateTurn?.(peer) || this.d.board.get(id)?.history.length !== task.history.length) return false;
+      if (previous) return true;
+      let recorded = false;
+      this.releaseNotice(`task #${id}: execution branch binding unavailable`, () => {
+        this.d.board.update(id, HUB, "shell branch bound", { refs: { branch: binding.branch } }, JSON.stringify({ branch: binding.branch, worktree }), {}, task.history.length);
+        recorded = true;
+      });
+      return recorded;
+    } catch { return false; }
+  }
+  private capacityBefore(task: Task): Map<PeerId, number> {
+    return new Map([...new Set([task.owner, task.reserved])].filter((peer): peer is PeerId => !!peer).map(peer => [peer, this.wip(peer)]));
+  }
+
+  /** Write-driven wake-ups (#785): one unsettled ids-only task notice per planner, never a polling pull. */
+  private writePlannerNotices(task: Task, before: ReadonlyMap<PeerId, number>, approved = false): void {
+    this.releaseNotice(`task #${task.id}: could not notify planner about ready work`, () => {
+      const changes = new Map<PeerId, { capacity: Set<PeerId>; ready: Set<number> }>();
+      const add = (planner: PeerId, peer?: PeerId, id?: number) => {
+        if (!this.d.bus.isRostered(planner)) return;
+        const change = changes.get(planner) ?? { capacity: new Set<PeerId>(), ready: new Set<number>() };
+        if (peer) change.capacity.add(peer);
+        if (id !== undefined) change.ready.add(id);
+        changes.set(planner, change);
+      };
+      const released = new Set<PeerId>();
+      for (const [peer, used] of before) if (this.wip(peer) < used) { released.add(peer); for (const planner of this.taskPlanner(task)) add(planner, peer); }
+      if (approved) for (const card of this.d.board.list("backlog")) {
+        if (card.deps?.includes(task.id) && !this.waitsFor(card).length) for (const planner of this.taskPlanner(card)) add(planner, undefined, card.id);
+      }
+      for (const [planner, change] of changes) this.releaseNotice(`could not notify planner ${planner} about ready work`, () => {
+        const pending = this.d.bus.pendingEnvelopes(planner).filter(env => env.from === HUB && env.kind === "task" && env.body.startsWith("Planner work ready:"));
+        // The bus retains these hub-written lines across restart; an in-memory cache would lose unsettled events.
+        for (const env of pending) for (const line of env.body.split("\n")) {
+          const capacity = /^capacity_released: (\S+) WIP \d+; reserved ready (?:#\d+|none)$/.exec(line);
+          if (capacity) change.capacity.add(capacity[1]!);
+          const ready = /^backlog_ready: #(\d+)$/.exec(line);
+          if (ready && Number.isSafeInteger(Number(ready[1]))) change.ready.add(Number(ready[1]));
+        }
+        const lines: string[] = [];
+        for (const peer of change.capacity) {
+          const top = this.topReservedReady(peer, planner);
+          lines.push(`capacity_released: ${peer} WIP ${this.wip(peer)}; reserved ready ${top ? `#${top.id}` : "none"}`);
+        }
+        for (const id of change.ready) {
+          const card = this.d.board.get(id);
+          if (card?.state === "backlog" && this.taskPlanner(card).includes(planner) && !this.waitsFor(card).length) lines.push(`backlog_ready: #${id}`);
+          else change.ready.delete(id);
+        }
+        for (const env of pending) this.d.bus.withdraw(env.id);
+        const env = newEnvelope(HUB, sanitize(`Planner work ready:\n${lines.join("\n")}\nRead the current board before planning or pulling work.`), { to: [planner], kind: "task" });
+        if (!this.d.bus.publish(env).includes(planner)) throw new Error("the notice was not queued");
+      });
+      // #785 P1c: only this write's own release, never a merged earlier one, and only when the person turned it on.
+      if (this.d.autoPull?.() === true) this.queueAutoPulls(released);
+    });
+  }
+
+  /** The top card explicitly reserved for `peer` that this planner may pull now; the notice and the opt-in pull read the same rule. `pullable` keeps the staged backlog cards only. */
+  private topReservedReady(peer: PeerId, planner?: PeerId, pullable = false): Task | undefined {
+    return this.d.board.list().filter(card => (pullable ? card.state === "backlog" : ["backlog", "proposed"].includes(card.state)) && !card.owner && card.reserved === peer
+      && (planner === undefined || this.taskPlanner(card).includes(planner)) && !(pullable && this.isPii(card)) && !card.pinned && taskCanPlan(card) && !this.waitsFor(card).length && !this.excluded(card).includes(peer)
+      && (card.release == null || ["planning", "active"].includes(this.d.board.release(card.release)?.state ?? ""))).sort(this.readyOrder)[0];
+  }
+
+  /**
+   * #785 P1c: `tasks.auto_pull`. A slot freed for a peer pulls the one top backlog card explicitly reserved for it, through `pullPlanned` as the hub acting for that card's planner of
+   * record: revision, dependency, reservation, pinned, frozen-release, P0 order and WIP checks all run there unchanged. One card per release. Never an unreserved card, never PII.
+   * Serialized on one chain, so two releases cannot pick the same card; each job re-reads the board, so a card that moved meanwhile is skipped.
+   */
+  private autoPulls: Promise<void> = Promise.resolve();
+  private autoPullsOpen = 0;
+  /** Queued or running auto pulls, so a recovery commit waits for them the way it waits for `checksPending` (#785 P1c): one that is mid-admission would otherwise write after the commit's digest. */
+  autoPullsPending = (): number => this.autoPullsOpen;
+  private queueAutoPulls(released: ReadonlySet<PeerId>): void {
+    for (const peer of released) {
+      this.autoPullsOpen++;
+      this.autoPulls = this.autoPulls.then(() => this.autoPull(peer)).catch(() => { /* autoPull reports its own refusals */ }).finally(() => { this.autoPullsOpen--; });
+    }
+  }
+  /** Whether the hub may still start work on its own: the setting is on, and no recovery, shutdown or storage hold is active. Read at entry and again right before the assignment write. */
+  private autoPullAdmitted(): boolean {
+    return this.d.autoPull?.() === true && !this.d.sweepHeld?.() && !this.d.bus.isRecoveryHeld && !this.d.bus.storageError;
+  }
+  private async autoPull(peer: PeerId): Promise<void> {
+    if (!this.autoPullAdmitted()) return;
+    const card = this.topReservedReady(peer, undefined, true);
+    if (!card) return;
+    // The planner of record is the card's own: its bound planner, else the first current holder, and it must be rostered. A private card never gets here (topReservedReady skips it).
+    const planner = this.taskPlanner(card)[0];
+    if (!planner || !this.d.bus.isRostered(planner)) return;
+    const reason = `auto_pull: capacity released for ${peer}; hub acted for planner ${planner}`;
+    try {
+      await this.pullPlanned(HUB, { id: card.id, revision: card.planningRevision ?? 0, reason }, { onBehalfOf: planner, guard: () => { if (!this.autoPullAdmitted()) throw new PreEffectToolRefusal("auto pull is no longer admitted: tasks.auto_pull was turned off or a recovery, shutdown or storage hold began"); } });
+    } catch (e) {
+      // A guard refusal is the setting or a hold doing its job, not a failure to report.
+      if (!this.autoPullAdmitted()) return;
+      this.releaseNotice(`task ${this.publicTitle(card)}: auto_pull for ${peer} refused: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+
   /** #784 AC3: the read-only breakdown of `wip` for status, the console and the dashboard: one grouped query for every peer. Admission still reads `wip()`. */
   wipBreakdown(peers: readonly PeerId[]): Record<string, { wip: number; active: number; reviewWait: number; reserved: number; wipLimit: number }> {
     const grouped = this.d.board.plannerWipBreakdown();
@@ -1079,15 +1224,20 @@ export class Tasks {
     return assign({ ...task, state: "proposed" }, states, routing, { exclude: this.excluded(task), excludeOwners: full, ...(reservedOnly && task.reserved ? { candidates: [task.reserved], namedOwner: task.reserved } : {}), waitsFor: this.waitsFor(task), ...this.weights(task.class, task) });
   }
 
-  async pullPlanned(by: PeerId, input: { id: number; revision: number; reason: string }): Promise<Task> {
+  async pullPlanned(by: PeerId, input: { id: number; revision: number; reason: string }, opts: { onBehalfOf?: PeerId; guard?: () => void } = {}): Promise<Task> {
     // #455: one authority check, made before the screen and again after it (a person may move the planner meanwhile).
-    const authorized = () => this.planningAuthority(by);
+    // #785 P1c: `by` is the actor the history records; the hub's opt-in auto pull names the planner it acts for, and that planner's authority is what is checked.
+    if (opts.onBehalfOf !== undefined && by !== HUB) throw new PreEffectToolRefusal("only the hub pulls on a planner's behalf");
+    const planner = opts.onBehalfOf ?? by;
+    // `opts.guard` (the auto pull's own admission, #785 P1c) throws a PreEffectToolRefusal once the pull is no longer wanted; it runs wherever authority is rechecked, so it
+    // also runs after the awaited PII screen and right before the assignment write, where a setting turned off or a recovery that began meanwhile must still stop it.
+    const authorized = () => { this.planningAuthority(planner); opts.guard?.(); };
     authorized();
     if (!Number.isSafeInteger(input.id) || input.id <= 0 || !Number.isSafeInteger(input.revision) || input.revision < 0 || typeof input.reason !== "string" || !input.reason.trim() || input.reason.length > 1000) throw new PreEffectToolRefusal("planner pull needs an id, revision and bounded reason");
     const validate = () => {
       const task = this.d.board.get(input.id);
       if (!task || (task.planningRevision ?? 0) !== input.revision || task.state !== "backlog" || task.owner || !taskCanPlan(task) || task.pinned) throw new PreEffectToolRefusal("planner pull changed, pinned or already started");
-      this.planningAuthority(by, task);
+      this.planningAuthority(planner, task);
       const release = task.release == null ? undefined : this.d.board.release(task.release);
       if (task.release != null && (!release || ["frozen", "shipped", "dropped"].includes(release.state))) throw new PreEffectToolRefusal("planner pull requires unfrozen release scope");
       if (this.waitsFor(task).length) throw new PreEffectToolRefusal("planner pull waits for dependency approval");
@@ -1121,6 +1271,7 @@ export class Tasks {
           if (checked.task.history.length !== current.task.history.length || checked.owner !== current.owner) throw new PreEffectToolRefusal("planner pull changed during admission");
         } } });
     }
+    opts.guard?.();
     const pulled = this.d.board.pullPlanned(current.task.id, by, current.owner, input.revision, input.reason.trim(), withheld, this.plannerBinding(current.task, current.assignment, true));
     this.planningRecorded({ by, task: pulled.id, fields: ["pull", "reserved"], revision: pulled.planningRevision! });
     return pulled;
@@ -1380,7 +1531,9 @@ export class Tasks {
     if (entry.planning.pull) {
       const release = task.release == null ? undefined : this.d.board.release(task.release);
       if (task.state !== "proposed" || task.owner || taskHasStarted(task) || by !== USER && (task.pinned || release && ["frozen", "shipped", "dropped"].includes(release.state))) throw new PreEffectToolRefusal("planner pull undo is no longer eligible");
+      const capacity = this.capacityBefore(task);
       const returned = this.d.board.undoPlannedPull(id, by, revision);
+      this.writePlannerNotices(returned, capacity);
       this.offered.delete(id); this.incomingBacklog.add(id);
       this.planningRecorded({ by, task: id, fields: ["pull", "reserved"], revision: returned.planningRevision! });
       return returned;
@@ -1760,7 +1913,9 @@ export class Tasks {
     this.plannerWriteAuthority(by);
     const confirmed = validate();
     if (confirmed.history.length !== flow) throw new PreEffectToolRefusal("task changed during untouched return");
+    const capacity = this.capacityBefore(confirmed);
     const returned = this.d.board.update(confirmed.id, by, "backlog returned untouched", { state: "backlog", owner: null, reviewer: null }, input.reason.trim(), { ...(withheld ? { withheld: true } : {}) }, flow);
+    this.writePlannerNotices(returned, capacity);
     this.offered.delete(confirmed.id);
     this.cohorts.leave(confirmed.id);
     this.withdrawRoleRequest(confirmed, returned, "owner");
@@ -1783,7 +1938,9 @@ export class Tasks {
     if (!pull && taskHasStarted(task)) throw new PreEffectToolRefusal(`task #${n}: started work cannot return to backlog`);
     const pulled = task.history.findLast(entry => entry.event === "backlog pulled" || entry.event === "backlog returned");
     const restoreReservation = !pull && pulled?.planning?.pull && !task.history.slice(task.history.lastIndexOf(pulled) + 1).some(entry => entry.event === "reserved" || entry.planning?.fields.includes("reserved"));
+    const capacity = this.capacityBefore(task);
     const next = this.d.board.update(n, by, pull ? "backlog pulled" : "backlog returned", { state: pull ? "proposed" : "backlog", owner: null, reviewer: null, ...(restoreReservation ? { reserved: pulled.planning!.previous.reserved ?? null } : {}) });
+    this.writePlannerNotices(next, capacity);
     this.offered.delete(n);
     if (!pull) { this.incomingBacklog.add(n); return next; }
     const waits = this.waitsFor(next);
@@ -2612,7 +2769,10 @@ export class Tasks {
     const task = validate();
     if (task.history.length !== revision) throw new PreEffectToolRefusal("task flow revision changed");
     const cancelled = { reason: input.reason.trim(), ...(input.supersededBy ? { supersededBy: input.supersededBy.trim() } : {}), flowRevision: revision + 1, ...(withheld ? { withheld: true as const } : {}) };
+    const capacity = this.capacityBefore(task);
+    this.ciWatchers.cancel(task.id); this.heldReviews.delete(task.id);
     const next = this.d.board.update(task.id, by, "cancelled", { state: "cancelled", reserved: null, cancelled }, cancelled.reason, { ...(withheld ? { withheld: true as const } : {}) }, revision);
+    this.writePlannerNotices(next, capacity);
     this.releaseNotice(`task #${task.id}: cancellation cohort cleanup unavailable`, () => this.cohorts.leave(task.id));
     this.offered.delete(task.id);
     this.releaseNotice(`task #${task.id}: cancellation stall cleanup unavailable`, () => this.d.board.clearStall(task.id));
@@ -2863,7 +3023,7 @@ export class Tasks {
     }
     const rows = this.d.board.list();
     const tasks: MetricTask[] = rows.map(task => ({ id: task.id, private: this.isPii(task), history: task.history.map(entry => ({ at: entry.at, event: entry.event,
-      ...(entry.reviewCost?.head ? { requestHead: entry.reviewCost.head } : {}), ...(entry.reviewFindings?.head ? { verdictHead: entry.reviewFindings.head } : {}) })) }));
+      ...(entry.reviewCost?.head ? { requestHead: entry.reviewCost.head } : {}), ...(entry.reviewFindings?.head ? { verdictHead: entry.reviewFindings.head } : {}), ...(entry.evidenceOnly ? { evidenceOnly: true as const } : {}) })) }));
     const visibleIds = new Set(rows.filter(task => !this.isPii(task)).map(task => task.id));
     const byKind: Record<string, number> = {};
     for (const stall of this.stalled()) if (visibleIds.has(stall.task)) byKind[stall.cause.kind] = (byKind[stall.cause.kind] ?? 0) + 1;
@@ -3688,12 +3848,17 @@ export class Tasks {
     const task = this.need(id, true, true);
     this.mine(task, by, "owner", true);
     // The owner it is declined for goes on the entry, also when the console declines for it: `excluded()` keeps it out (#207).
+    const capacityBefore = this.capacityBefore(task);
     const planned = this.plannerPullRecord(task)?.pull === true;
     const back = this.d.board.update(task.id, by, "declined", { ...(["in_progress", "changes_requested"].includes(task.state) ? { state: "proposed" as const } : {}), ...(planned ? { reserved: null } : {}) }, reason, task.owner ? { from: task.owner, ...(capacity === true ? { capacity: true as const } : {}) } : {});
     if (planned) this.offered.delete(task.id);
     this.d.notify(`task ${this.publicTitle(back)} declined${capacity === true ? " (capacity only)" : ""} by ${by}${reason && !this.isPii(back) ? `: ${reason}` : ""}`);
     // A capacity decline is not in excluded(), so this move's own reroute leaves the decliner out explicitly.
-    return this.assignOwner(back, HUB, { event: "reassigned", reason: "declined", clearOnFail: true, ...(capacity === true && task.owner ? { exclude: [task.owner] } : {}), ...(planned ? { planner: true } : {}) });
+    try {
+      return await this.assignOwner(back, HUB, { event: "reassigned", reason: "declined", clearOnFail: true, ...(capacity === true && task.owner ? { exclude: [task.owner] } : {}), ...(planned ? { planner: true } : {}) });
+    } finally {
+      this.writePlannerNotices(this.d.board.get(task.id) ?? back, capacityBefore);
+    }
   }
 
   /**
@@ -4037,7 +4202,10 @@ export class Tasks {
     const completedRefs = cleanRefs(refs);
     this.warmRepository({ ...task, refs: { ...task.refs, ...completedRefs } });
     const noWrites = this.noWritesRecorded({ ...task, refs: { ...task.refs, ...completedRefs } });
+    const capacity = this.capacityBefore(task);
     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.writePlannerNotices(next, capacity, next.state === "approved");
+    this.ciWatchers.cancel(next.id); this.heldReviews.delete(next.id); // a newer head or a move ends the old head's watcher (#785 P1b)
     this.cohorts.closed(next.id); // its owner's next native turn end settles it in its cohort (issue #107)
     const memorySymbols = this.completionMemorySymbols(next);
     this.note(next, by, "finding", `Task #${next.id} done by ${by}: ${next.title}\nChanged-symbol memory anchors: ${memorySymbols.state === "known" ? memorySymbols.nodes.length : "unknown (no complete code facts)"}\n${summary ?? ""}`, withheld, memorySymbols);
@@ -4050,6 +4218,7 @@ export class Tasks {
     }
     else if (reviewer === USER) this.releaseNotice(`task ${this.publicTitle(next)} done by ${by}: review it in the ahub console (Tasks, select #${next.id}, press r) or with ahub review ${next.id} approved|changes_requested [note]`);
     else this.releaseNotice(`task ${this.publicTitle(next)}: could not send the review request to ${reviewer}`, () => this.sendReview(next, reviewer, "", admission));
+    if (reviewer && !(admission?.ready && admission.head === this.reviewHead(next))) this.watchCi(next);
     return next;
   }
 
@@ -4215,6 +4384,7 @@ export class Tasks {
     if (mode === "enforce" && !admission?.ready) {
       // Background roster/quota role changes are retained, but never invent a remotely admitted review request.
       this.releaseNotice(`task ${this.publicTitle(task)}: premature review held; retry the reviewer assignment after current CI and bot replies are verified`);
+      this.holdReview(task, reviewer);
       return false;
     }
 
@@ -4235,9 +4405,12 @@ export class Tasks {
         ? "No check ran for this class: verify the outcome yourself."
         : "No check ran for this class: run the affected tests yourself.";
     // #824: the hub's own exact-head CI evidence, from the admission this request already carries (no new gh call). Nothing here comes from the builder's summary or a recorded claim.
-    const verified = this.hubVerifiedBlock(task, admission);
+    const codeScoped = this.d.reviewScope?.(reviewer) === "code";
+    const verified = codeScoped ? "" : this.hubVerifiedBlock(task, admission);
     const ciPassed = admission?.ready === true && !this.isPii(task);
-    const checkResult = check ? `Check result: ${(check.note ?? "").split("\n")[0]}`
+    // #852 AC2: a code-scope reviewer's sandbox cannot run tests or read CI, so its Hub-verified and check lines are replaced by one fixed line.
+    const checkResult = codeScoped ? CODE_SCOPE_LINE
+      : check ? `Check result: ${(check.note ?? "").split("\n")[0]}`
       : ciPassed ? "CI passed at this exact head (see the Hub-verified line above); do not list test execution or CI evidence as unmet: name the specific missing test or behaviour instead."
       : noCheckWording;
     const checklistTemplates = profile.review_checklist ?? [
@@ -4291,6 +4464,67 @@ export class Tasks {
     return this.d.bus.publish(newEnvelope(HUB, body, { to: [reviewer], kind: "review", priority: "important", refs: { ...r, ...(this.reviewHead(task) ? { commit: this.reviewHead(task)! } : {}), task: String(task.id), reviewRevision: String(this.reviewRequestRevision(task)) }, ...(this.isPii(task) ? { private: true } : {}) })).includes(reviewer);
   }
 
+  /** #785 P1b: remember a review the hub held as premature, so a green CI at this exact head can re-offer it once. Also watches that head. */
+  private holdReview(task: Task, reviewer: PeerId): void {
+    try {
+      const head = this.reviewHead(task);
+      if (this.isPii(task) || !head || reviewer === USER) return;
+      this.heldReviews.set(task.id, { head, reviewer, revision: this.reviewRequestRevision(task) });
+      this.watchCi(task);
+    } catch { /* optional bookkeeping never fails a review path */ }
+  }
+
+  /** #785 P1b AC3: start the one watcher for this task's exact head. Not for private work, an unlinked PR or a lifecycle that is off; never throws. */
+  private watchCi(task: Task): void {
+    try {
+      const head = this.reviewHead(task), repo = task.sdlc?.repo, pr = task.sdlc?.pr;
+      if (!this.d.sdlc || this.d.sdlc.config().mode === "off" || this.isPii(task) || task.state !== "in_review" || !head || !/^[0-9a-f]{40}$/.test(head) || !repo || !pr) return;
+      this.ciWatchers.start({ id: task.id, head, repo, pr });
+    } catch { /* a watcher that cannot start leaves the review path as it was */ }
+  }
+
+  /** The watcher's own check before every read and every notice: the task must still be in review at this exact head and PR. */
+  private ciWatchCurrent(watch: CiWatch): boolean {
+    const task = this.d.board.get(watch.id);
+    return !!task && task.state === "in_review" && !this.isPii(task) && this.reviewHead(task) === watch.head && task.sdlc?.repo === watch.repo && task.sdlc?.pr === watch.pr
+      && (this.d.sdlc?.config().mode ?? "off") !== "off";
+  }
+
+  /**
+   * #785 P1b: the result of the exact head's CI, told once to the owner and the reviewer (one ids-only task envelope each, `status` weight: `fyi` is recorded but never delivered to the peer),
+   * then a review held as premature is offered once more after a fresh readiness read. A deadline tells the console only.
+   */
+  private async ciCompleted(watch: CiWatch, outcome: CiOutcome): Promise<void> {
+    const task = this.d.board.get(watch.id);
+    if (!task || !this.ciWatchCurrent(watch)) return;
+    const label = `#${task.id} head ${watch.head.slice(0, 12)}`;
+    if (outcome === "deadline") { this.releaseNotice(`task ${label}: CI did not finish within the watch deadline; no further reads`); return; }
+    const line = `ci_completed: ${label} ${outcome}`;
+    for (const peer of new Set([task.owner, task.reviewer])) {
+      if (!peer || peer === HUB) continue;
+      if (peer === USER) { this.releaseNotice(`task ${label}: CI ${outcome} at its exact head`); continue; }
+      this.releaseNotice(`task ${label}: could not tell ${peer} the CI result`, () => this.d.bus.publish(newEnvelope(HUB, `${line}\nRead hub_task_show for the task before acting.`, { to: [peer], kind: "task", priority: "status", refs: { task: String(task.id), commit: watch.head } })));
+    }
+    if (outcome === "failed") return;
+    await this.reofferHeldReview(task, watch);
+  }
+
+  /** The held review of this exact head and request, once: only while it is still the same reviewer, head and revision, and a fresh admission says it is ready. */
+  private async reofferHeldReview(task: Task, watch: CiWatch): Promise<void> {
+    const held = this.heldReviews.get(task.id);
+    if (!held || held.head !== watch.head || task.reviewer !== held.reviewer || this.reviewRequestRevision(task) !== held.revision) return;
+    this.heldReviews.delete(task.id); // once: a later hold needs a new head or a new request
+    try {
+      const admission = await this.reviewRequestAdmission(task, undefined, false, task.owner ?? USER);
+      const current = this.d.board.get(task.id);
+      if (!admission?.ready || !current || !this.ciWatchCurrent(watch) || current.reviewer !== held.reviewer || this.reviewRequestRevision(current) !== held.revision) return;
+      this.releaseNotice(`task ${this.publicTitle(current)}: could not re-offer the held review to ${held.reviewer}`, () => this.sendReview(current, held.reviewer, "(Held earlier because exact-head CI was not green; it is green now.)", admission));
+    } catch { /* still not ready: the hold notice already named why; a reviewer reassignment retries it */ }
+  }
+
+  /** Daemon shutdown: no watcher outlives the hub. */
+  stopCiWatchers(): void { this.ciWatchers.stopAll(); this.heldReviews.clear(); }
+
   private reviewRequestRevision(task: Task): number {
     // Role changes fence older requests; bookkeeping appended after the request does not.
     return task.history.findLastIndex(entry => ["done", "reviewer changed", "reviewer unavailable"].includes(entry.event) || OWNERSHIP_EVENTS.has(entry.event)) + 1;
@@ -4431,6 +4665,11 @@ export class Tasks {
     let parsed: ReviewFinding[];
     try { parsed = parseReviewFindings(findings, { person: by === USER, maxNits: this.d.sdlc?.config().maxNits ?? DEFAULT_MAX_NITS }); }
     catch (error) { throw new PreEffectToolRefusal(error instanceof Error ? error.message : "invalid structured findings"); }
+    // #852 AC3 (amended): a code-scope reviewer's changes_requested is always recorded, never refused. Without an open structured finding it is
+    // evidence-only: it does not count toward rejections or escalation, the task returns to its owner as usual, and the conductor gets one ids-only
+    // notice. The rule is structural (a finding with disposition open), never a reading of the unmet text.
+    const codeScope = by !== USER && this.d.reviewScope?.(by) === "code";
+    const evidenceOnly = codeScope && verdict === "changes_requested" && !parsed.some(finding => finding.disposition === "open");
     const resolvedHead = this.findingHead(initial);
     let findingHead = resolvedHead;
     if (head !== undefined) {
@@ -4512,7 +4751,7 @@ export class Tasks {
     }
     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)) {
+    if (verdict === "changes_requested" && !evidenceOnly && items.length && this.d.candidates && !withheld && !this.isPii(task) && !this.d.privateTurn?.(by)) {
       const input: CandidateInput = { project: this.d.store?.project ?? this.d.project, kind: "fail", approach: this.publicTitle(task), symptom: items.join("\n"),
         cause: "unknown: review unmet items do not establish a cause", retryWhen: "unknown: a person must review the unmet items before accepting",
         evidenceRefs: [`task:${task.id}`, `reviewed-head:${reviewedHead ?? task.refs.commit ?? "unknown"}`] };
@@ -4531,9 +4770,12 @@ export class Tasks {
     // #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 } : {}) };
+    const flag = { ...this.planObservation(task), withheld: withheld || undefined, ...(report ? { reviewFindings: report } : {}), ...(unmetCriteria.length ? { unmetCriteria } : {}), ...(boundDeliverables ? { deliverables: boundDeliverables } : {}), ...(reviewContext ? { reviewContext } : {}), ...(codeScope ? { reviewScope: "code" as const } : {}), ...(evidenceOnly ? { evidenceOnly: true as const } : {}), ...(reviewerFamily ? { reviewerFamily } : {}), ...(reviewerReason ? { reviewerReason } : {}) };
     if (verdict === "approved") {
+      const capacity = this.capacityBefore(task);
+      this.ciWatchers.cancel(task.id); this.heldReviews.delete(task.id);
       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);
+      this.writePlannerNotices(next, capacity, next.state === "approved");
       if (next.owner) {
         this.d.board.recordOutcome(next.owner, next.class, true);
         this.d.board.recordReview({ implementer: next.owner, reviewer: by, class: next.class, kind: "approved", task: next.id });
@@ -4552,17 +4794,20 @@ export class Tasks {
       this.releaseNotice(`task #${next.id}: review saved but recurring-finding proposal unavailable`, () => this.proposeRecurringFindings(next, by, parsed, withheld));
       return next;
     }
-    const rejected = this.d.board.update(task.id, by, "changes_requested", { state: "changes_requested", rejections: task.rejections + 1 }, note, flag);
+    this.ciWatchers.cancel(task.id); this.heldReviews.delete(task.id);
+    const rejected = this.d.board.update(task.id, by, "changes_requested", { state: "changes_requested", rejections: evidenceOnly ? task.rejections : task.rejections + 1 }, note, flag);
     void this.mirrorVerdict(rejected, by, "changes_requested", reviewedHead ?? rejected.sdlc?.reviewedHead, note, withheld);
-    this.releaseNotice(`task #${rejected.id}: review saved but recurring-finding proposal unavailable`, () => this.proposeRecurringFindings(rejected, by, parsed, withheld));
+    if (!evidenceOnly) this.releaseNotice(`task #${rejected.id}: review saved but recurring-finding proposal unavailable`, () => this.proposeRecurringFindings(rejected, by, parsed, withheld));
     if (candidate && !pii && !this.d.privateTurn?.(by) && this.candidateTextAllowed(JSON.stringify({ candidate, refs: rejected.refs, plan: rejected.plan }), rejected)) {
       try { this.d.memoryCheck?.(); this.d.candidates?.put({ ...candidate, evidenceRefs: [...candidate.evidenceRefs, `review:${rejected.id}:${rejected.history.length}`] }, "public"); } catch { /* a saved review remains authoritative if the optional sidecar fails */ }
     }
     this.cohorts.withdraw(rejected.id); // open again: its done intent no longer counts (issue #107)
-    if (rejected.owner) this.d.board.recordOutcome(rejected.owner, rejected.class, false);
-    this.contradict(rejected);
+    // Evidence-only is not a verdict on the owner's work: no failed outcome, no contradiction of an earlier approval, and no escalation count.
+    if (rejected.owner && !evidenceOnly) this.d.board.recordOutcome(rejected.owner, rejected.class, false);
+    if (!evidenceOnly) this.contradict(rejected);
     this.note(rejected, by, "decision", `Task #${rejected.id} changes requested by ${by}: ${rejected.title}\n${note ?? ""}`, withheld);
-    if (rejected.rejections >= (this.d.escalateAfter?.() ?? ESCALATE_AFTER)) {
+    if (evidenceOnly) this.tellConductorEvidenceOnly(rejected, by);
+    if (!evidenceOnly && rejected.rejections >= (this.d.escalateAfter?.() ?? ESCALATE_AFTER)) {
       let moved: Task;
       try {
         moved = await this.escalate(HUB, rejected.id, `${rejected.rejections} consecutive changes_requested`, "rejections");
@@ -4587,6 +4832,19 @@ export class Tasks {
     return reopened;
   }
 
+  /**
+   * #852 AC3: one task-weight notice to the configured conductor for a verdict recorded as evidence-only. Ids only (task and reviewer), so nothing of
+   * the review or the task reaches it; a PII task's notice is private. With no conductor the person sees one console notice instead.
+   */
+  private tellConductorEvidenceOnly(task: Task, reviewer: PeerId): void {
+    const conductors = Object.entries(this.d.roles ?? {}).filter(([, roles]) => Array.isArray(roles) && roles.includes("conductor")).map(([actor]) => actor).filter(actor => actor !== reviewer);
+    const text = evidenceOnlyNotice(task.id, reviewer);
+    if (!conductors.length) { this.releaseNotice(text); return; }
+    this.releaseNotice(`task #${task.id}: could not tell the conductor a code-scope review was evidence-only`, () => {
+      this.d.bus.publish(newEnvelope(HUB, sanitize(text), { to: conductors, kind: "task", refs: { task: String(task.id) }, ...(this.isPii(task) ? { private: true } : {}) }));
+    });
+  }
+
   /** Task-level escalation: the next attached peer in the class's escalate_to takes over, with the history. */
   async escalate(by: PeerId, id: unknown, why = "by hand", reason: TaskMoveReason | undefined = by === HUB ? undefined : "manual", preEffect = false): Promise<Task> {
     let task = this.need(id, true, preEffect);