@staix/agent-hub 0.28.0 → 0.30.0

package/src/hub/tasks.ts

@@ -68,13 +68,14 @@ import { parseClaimVerdict, claimListId, CLASSES, OUTCOMES_KEPT_MS, ALL_PLAN_KEY
 import type { Bus } from "./bus.ts";
 import { HUB, newEnvelope, NOTE_KINDS, noteLine, sanitize, USER, type Envelope, type PeerId, type PeerState } from "./envelope.ts";
 import type { PiiVerdict, ScreenItem, ScreenRecord } from "./inference.ts";
-import { assign, isRemotePeerId, detectSignals, peerEntry, predictSplit, relayCandidates, type Assignment, type InstanceRoutingOptions, type PeerCapabilities, type Routing, type SplitObservation, type SplitPrediction } from "./routing.ts";
+import { assign, isRemotePeerId, detectSignals, peerEntry, predictSplit, relayCandidates, writesRepository, type Assignment, type InstanceRoutingOptions, type PeerCapabilities, type Routing, type SplitObservation, type SplitPrediction } from "./routing.ts";
 import { ExecutionBudget, type ExecutionBudgetConfig, type ExecutionBudgetDecision, type ExecutionBudgetStatus, type ExecutionUnit } from "./execution-budget.ts";
 import { Cohorts, MAX_REQUESTS, type Cohort, type Completion } from "./cohorts.ts";
 import { realPath } from "./project.ts";
 import { TaskRepositories } from "./task-repository.ts";
 import { mainCheckoutWarning } from "./main-checkout.ts";
 import { PreEffectToolRefusal } from "./tool-refusal.ts";
+import type { TaskWorktreePort } from "./task-worktree.ts";
 import { coverageGap, renderReviewBrief, renderSpecTaskReport, type BriefFile, type ReviewBrief } from "./review-brief.ts";
 import { DEFAULT_SPECS_CONFIG, type SpecsConfig } from "./specs-config.ts";
 import type { SpecsCheckReport, SpecsCoverReport } from "./specs.ts";
@@ -82,7 +83,7 @@ import { definitionOf as builtinDefinitionOf } from "../adapters/registry.ts";
 import { ADAPTERS, DEFAULT_REVIEW_POOL, definitionOf, familyOf, type ProjectAdapterCatalog } from "../adapters/registry.ts";
 import { plannerGrooming, nextSweep, plannedStartPending, 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";
+import { planningIssueReceipt, linkedReceipt, openPrFor, readPrCostHistory, readReviewReadiness, reviewReadinessFromEvidence, type PrEvidence, type ReviewReadiness, readPlanIssueMetadata, canonicalStage, checklistOf, readSdlcPr, readSdlcPrHead, 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";
 
 function requireLocalTaskPeer(peer: unknown): void {
   if (isRemotePeerId(peer)) throw new PreEffectToolRefusal("remote peers have no local task authority");
@@ -217,6 +218,8 @@ export interface TasksDeps {
   review?: { adaptive: boolean; min_reviews: number; pool?: readonly string[]; rerotate?: boolean; same_family?: "fallback" | "never" };
   /** Peers whose recent deliveries all failed, with the reason (issue #89); routing skips them. */
   capabilities?: () => Record<PeerId, PeerCapabilities>;
+  /** #1115: the hub makes, commits and clears the task worktree of a hub-sandboxed peer. Absent: such a peer keeps the #1081 refusal. */
+  taskWorktree?: TaskWorktreePort;
   repository?: string;
   offerRead?: (peer: PeerId, envelopeId: string) => boolean;
   offerPullOnly?: (peer: PeerId) => boolean;
@@ -429,6 +432,7 @@ export interface ExperimentView { attempts: ExperimentAttemptView[]; counts: { a
   comparison?: { planHash: string; baselineAttemptId: string; variantAttemptId: string; approved: boolean; private: boolean; projection: ReturnType<typeof comparisonProjection> | "[pii]" } }
 interface ExperimentContext { task: Task; campaign: ResearchCampaignRecord; private: boolean; key: string; fence: ExperimentWriteFence }
 interface CompletionRefresh { revision: number; commit: string; state: "in_review" | "approved" }
+interface RefileHeadGuard { recorded?: string }
 interface IdentityLink { repo: string; pr: number; basis: { commit?: string; branch?: string } }
 
 /** What one live check of a task's files says as a whole (#317): `unchanged` only when EVERY file measured unchanged. A change outranks a missing file, which outranks one the hub could not read. */
@@ -1335,6 +1339,38 @@ export class Tasks {
 
   private reviewHead(task: Task): string | undefined { return task.refs.commit ?? task.sdlc?.head ?? task.sdlc?.localHead; }
 
+  private recordedReviewHead(task: Task): string | undefined {
+    const isFullHead = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{40}$/.test(value);
+    const historyHead = task.history.findLast(entry => (entry.event === "approved" || entry.event === "changes_requested") && isFullHead(entry.reviewedHead))?.reviewedHead;
+    return [task.sdlc?.reviewedHead, historyHead].find(isFullHead);
+  }
+
+  /** An owner ref, when present, outranks host-derived receipt.head values for review identity. */
+  private ownerReviewHead(task: Task): string | undefined {
+    return /^[a-f0-9]{40}$/.test(task.refs.commit ?? "") ? task.refs.commit : this.recordedReviewHead(task);
+  }
+
+  private hasReviewHistory(task: Task): boolean {
+    return task.state === "changes_requested" || !!task.sdlc?.reviewedHead || task.history.some(entry => entry.event === "approved" || entry.event === "changes_requested");
+  }
+
+  private reviewHeadMoveRefusal(taskId: number, recorded: string | undefined, current?: string): PreEffectToolRefusal {
+    const known = recorded ? `recorded review head ${recorded}` : "a recorded full review head";
+    const cause = current ? `${known} differs from current head of PR ${current}`
+      : `current PR head could not be verified against ${known}`;
+    const next = current ? `refs.commit set to ${current}` : "refs.commit set to the current full SHA";
+    return new PreEffectToolRefusal(`task #${taskId}: ${cause}; owner must re-file hub_task_done with ${next} before review`);
+  }
+
+  private async currentPrHeadForReview(task: Task, validate: () => Task): Promise<string | undefined> {
+    const receipt = task.sdlc, gh = this.d.sdlc?.gh;
+    if (this.isPii(task) || !receipt?.repo || !receipt.pr || !gh) return undefined;
+    const identity = (value: Task) => JSON.stringify([value.id, value.state, value.owner, value.reviewer, value.history.length, this.isPii(value), value.refs, value.sdlc]);
+    const before = identity(task), head = await readSdlcPrHead(receipt, gh), current = validate();
+    if (identity(current) !== before) throw new PreEffectToolRefusal(`task #${task.id}: task or review head changed during PR readback; reload and retry`);
+    return head;
+  }
+
   private reviewPoolOptions(task: Task) {
     const head = this.reviewHead(task);
     const round = task.state === "in_review" ? task.history.slice(task.history.findLastIndex(entry => entry.event === "done") + 1) : [];
@@ -1377,16 +1413,18 @@ export class Tasks {
    * sandboxed peer from accepting work, failing at `git worktree add` (#270) and leaving an empty branch ref behind (#621, #565). Unknown capability is
    * not a refusal, and a PII task skips the check as `requireCapabilities` does.
    */
-  private declaredNeedCheck(task: Pick<Task, "signals" | "id"> & Partial<Pick<Task, "signals">>, peer: PeerId): void {
+  private declaredNeedCheck(task: Pick<Task, "signals" | "id"> & Partial<Pick<Task, "signals" | "class">>, peer: PeerId): void {
     if (!this.d.capabilities || this.isPii(task as Task)) return;
-    const wantsNetwork = task.signals?.includes("needs_network") === true, wantsWorktree = task.signals?.includes("needs_worktree") === true;
+    // #1129: write-class work needs the hub's worktree whether or not it says so, because a hub-sandboxed owner cannot commit.
+    const declaredWorktree = task.signals?.includes("needs_worktree") === true;
+    const wantsNetwork = task.signals?.includes("needs_network") === true, wantsWorktree = declaredWorktree || (task.class !== undefined && writesRepository(task.class));
     if (!wantsNetwork && !wantsWorktree) return;
     const caps = peerEntry(this.d.capabilities(), peer);
     if (wantsNetwork && caps?.network === false) {
       throw new PreEffectToolRefusal(`task #${task.id} needs the network and ${peer} has none: ${caps.networkReason ?? "its shell cannot reach the network"}; decline it so the hub offers it to a peer with network, or ask the person to enable it`);
     }
     if (wantsWorktree && caps?.worktree === false) {
-      throw new PreEffectToolRefusal(`task #${task.id} needs its own git worktree and ${peer} cannot create one: ${caps.worktreeReason ?? "it cannot create the task worktree"}; nothing was created, so no branch ref is left behind; decline it so the hub offers it to a peer that can, this will not change by waiting`);
+      throw new PreEffectToolRefusal(`task #${task.id} ${declaredWorktree ? "needs its own git worktree" : "changes the repository, so the hub must make its git worktree and commit for it"} and ${peer} cannot create one: ${caps.worktreeReason ?? "it cannot create the task worktree"}; nothing was created, so no branch ref is left behind; decline it so the hub offers it to a peer that can, this will not change by waiting`);
     }
   }
 
@@ -3281,6 +3319,8 @@ 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; needs_network?: unknown; needs_worktree?: unknown; backlog?: unknown; draft?: unknown; goal?: unknown }, external?: GitHubSource, created?: () => void, fence?: () => string | undefined): Promise<Task> {
     const requestCheck = this.requestCheck(by, fence);
+    const plan = cleanPlan(input.plan, this.d.profileData ?? this.d.profile ?? "dev");
+    this.validatePlanSources(plan);
     requireLocalTaskPeer(input.owner);
     external = external ? { ...external } : undefined;
     if (external && (!this.personOrConductor(by) || input.backlog !== true)) throw new PreEffectToolRefusal("external intake requires person-owned backlog staging");
@@ -3317,7 +3357,6 @@ export class Tasks {
     let baseGiven: TaskClass | undefined;
     try { if (given !== undefined) baseGiven = profileClass(given, this.d.profileData ?? profile); } catch (error) { throw new PreEffectToolRefusal((error as Error).message); }
     const text = { title, detail: String(input.detail ?? "").slice(0, 8000), refs: cleanRefs(input.refs) };
-    const plan = cleanPlan(input.plan, this.d.profileData ?? profile);
     // The plan reaches other owners, so a PII pattern in it makes the task a PII task like one in the detail would.
     const screenDetail = [text.detail, text.refs.repo, external?.repo, external?.url].filter(value => value !== undefined && value !== "").join("\n");
     const signals = this.signalsFor({ ...text, detail: [screenDetail, planText(plan)].join("\n"), plan });
@@ -3393,10 +3432,14 @@ export class Tasks {
     }
   }
 
-  async returnUntouchedToBacklog(by: PeerId, input: { id: number; revision: number; reason: string }): Promise<Task> {
+  async returnUntouchedToBacklog(by: PeerId, input: { id: number; revision: number; reason: string; fields?: unknown }): Promise<Task> {
     this.plannerWriteAuthority(by);
     if (!Number.isSafeInteger(input.id) || input.id < 1 || !Number.isSafeInteger(input.revision) || input.revision < 0
       || typeof input.reason !== "string" || !input.reason.trim() || input.reason.length > 1000) throw new PreEffectToolRefusal("untouched return needs an id, revision and bounded reason");
+    let parsed: PlanningFields;
+    try { parsed = planningPatch(input.fields); } catch (error) { throw new PreEffectToolRefusal(`${(error as Error).message}; use fields.reserved with an agent peer id or null, or omit fields`); }
+    if (Object.keys(parsed).some(key => key !== "reserved")) throw new PreEffectToolRefusal("untouched return fields may contain only reserved; remove every other field, or omit fields");
+    const patch: Pick<PlanningFields, "reserved"> = Object.hasOwn(parsed, "reserved") ? { reserved: parsed.reserved } : {};
     const validate = () => {
       const task = this.need(input.id, false, true);
       this.plannerWriteAuthority(by, task);
@@ -3404,6 +3447,14 @@ export class Tasks {
       if (by !== USER && task.pinned) throw new PreEffectToolRefusal("pinned work requires the person");
       const release = task.release == null ? undefined : this.d.board.release(task.release);
       if (release && (["shipped", "dropped"].includes(release.state) || by !== USER && release.state === "frozen")) throw new PreEffectToolRefusal("settled or frozen release scope cannot return");
+      if (Object.hasOwn(patch, "reserved")) {
+        if (by !== USER && this.hasPersonReservation(task)) throw new PreEffectToolRefusal("a person's reservation is retained; ask the person to change it");
+        const reserved = patch.reserved, definitionOf = this.d.adapterCatalog?.definitionOf ?? builtinDefinitionOf;
+        if (reserved && !definitionOf(reserved, this.d.instances?.()) && !this.d.bus.knownPeers().includes(reserved) && !this.d.routing().classes[task.class]?.peers.includes(reserved)) throw new PreEffectToolRefusal("reserved owner is not a supported or configured peer; choose a peer from ahub status");
+        if (reserved && !this.d.bus.isRostered(reserved)) throw new PreEffectToolRefusal("reserved owner is off roster; choose a rostered peer from ahub status or ask the person to update the roster");
+        if (reserved && this.excluded(task).includes(reserved)) throw new PreEffectToolRefusal(`${reserved} is excluded from this task (it declined it or was escalated away from it for good); a reservation for it can never be honoured. Only a person's ahub task assign lifts the exclusion`);
+        if (reserved) this.requireCapabilities(task, reserved);
+      }
       return task;
     };
     const task = validate(), flow = task.history.length;
@@ -3412,14 +3463,14 @@ export class Tasks {
     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);
+    const returned = this.d.board.update(confirmed.id, by, "backlog returned untouched", { state: "backlog", owner: null, reviewer: null, ...patch }, 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");
     this.withdrawRoleRequest(confirmed, returned, "reviewer");
     this.incomingBacklog.add(confirmed.id);
-    this.planningRecorded({ by, task: confirmed.id, fields: ["return"], revision: confirmed.planningRevision ?? 0 });
+    this.planningRecorded({ by, task: confirmed.id, fields: ["return", ...Object.keys(patch)], revision: returned.planningRevision ?? 0 });
     await this.releaseHeld(confirmed.owner); // its owner's slot is free (#655)
     return returned;
   }
@@ -4044,7 +4095,17 @@ export class Tasks {
       }
       if (stagedClaimGap) return next; // An explicit claim may reserve its owner, but no offer or acceptance bypasses review.
       this.studyDispatchCheck(next, by);
-      const claimed = this.d.board.update(next.id, by, "accepted", { state: "in_progress" });
+      // #1129: a self-claim of write-class work is an accept too, so a hub-sandboxed claimant gets the hub's worktree here, before the write. When the hub cannot make one the claim stays an assignment, like the missing-spec case above: `hub_task_accept` starts it and refuses with the same cause.
+      let undoWorktree: (() => void) | undefined;
+      try { undoWorktree = this.hubWorktreeFor(next, by); }
+      catch (error) {
+        if (!(error instanceof PreEffectToolRefusal)) throw error;
+        this.releaseNotice(`${error.message}; the claim stays assigned to ${by} and is not started`);
+        return next;
+      }
+      let claimed: Task;
+      try { claimed = this.d.board.update(next.id, by, "accepted", { state: "in_progress" }); }
+      catch (error) { undoWorktree?.(); throw error; }
       this.captureOwnerAcceptance(claimed);
       this.releaseNotice(`task ${this.publicTitle(claimed)} claimed by ${by}`);
       return claimed;
@@ -4080,7 +4141,8 @@ export class Tasks {
   /** A self-claim has no assignment envelope; its tool result carries the same bounded guidance. */
   claimRoleGuidance(task: Task, peer: PeerId): string {
     requireLocalTaskPeer(peer);
-    return task.owner === peer && task.state === "in_progress" ? this.roleGuidance(task, peer) : "";
+    // #1129: a claim by a hub-sandboxed peer carries the worktree note as an accept does, since the claim result is all it reads.
+    return task.owner === peer && task.state === "in_progress" ? [this.roleGuidance(task, peer), this.worktreeNote(task, peer)].filter(Boolean).join("\n") : "";
   }
 
   private roleGuidance(task: Task, peer: PeerId, review = false): string {
@@ -4493,6 +4555,7 @@ export class Tasks {
     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.releaseHubWorktree(task, task.owner);
     this.writePlannerNotices(next, capacity);
     this.releaseNotice(`task #${task.id}: cancellation cohort cleanup unavailable`, () => this.cohorts.leave(task.id));
     this.offered.delete(task.id);
@@ -5648,10 +5711,18 @@ export class Tasks {
 
   /** The eval record the last approval-time lifecycle read produced for a task; consumed by the verdict that follows it. */
   private readonly evalRecords = new Map<number, string>();
-  private async lifecycleGate(task: Task, transition: "review" | "approval", reviewedHead?: string, findings?: readonly ReviewFindingSet[]): Promise<PrEvidence | undefined> {
+  private async lifecycleGate(task: Task, transition: "review" | "approval", reviewedHead?: string, findings?: readonly ReviewFindingSet[], refileHead?: RefileHeadGuard): Promise<PrEvidence | undefined> {
     const config = this.d.sdlc?.config() ?? sdlcConfig(undefined);
     if (config.mode === "off") return;
     const receipt = task.sdlc && { ...task.sdlc, ...(reviewedHead ? { reviewedHead } : {}) };
+    const approvalHead = transition === "approval" ? reviewedHead ?? this.ownerReviewHead(task) ?? this.findingHead(task) : undefined;
+    const guardedHead = !!refileHead || !!approvalHead && !!receipt?.repo && !!receipt.pr && !this.isPii(task);
+    // Compare raw head identity on both sides; `task` may carry an uncommitted identityLink.
+    // Completion state/history races stay with completionCurrent's existing post-readback fence.
+    const identity = (value: Task) => JSON.stringify([value.id, value.owner, value.reviewer, this.isPii(value),
+      value.refs.repo, value.refs.commit, value.refs.branch, value.sdlc?.repo, value.sdlc?.pr,
+      value.sdlc?.head, value.sdlc?.localHead, value.sdlc?.reviewedHead]);
+    const beforeHeadRead = guardedHead ? identity(this.need(task.id, false, true)) : undefined;
     const deadline = performance.now() + 20_000;
     const read: SdlcGh = (args, timeout, cwd, cap) => {
       const current = this.need(task.id, false, true);
@@ -5660,6 +5731,16 @@ export class Tasks {
       return remaining > 0 ? (this.d.sdlc?.gh ?? sdlcGh)(args, Math.min(timeout ?? 10_000, remaining), cwd, cap) : Promise.resolve({ code: 1, stdout: "" });
     };
     const evidence = receipt && !this.isPii(task) ? await readSdlcPr(receipt, read, true) : undefined;
+    const currentHead = receipt && !this.isPii(task) && (refileHead || approvalHead) && !evidence?.head
+      ? await readSdlcPrHead(receipt, read) : evidence?.head;
+    if (beforeHeadRead !== undefined) {
+      const current = this.need(task.id, false, true);
+      if (identity(current) !== beforeHeadRead) throw new PreEffectToolRefusal(`task #${task.id}: task or review head changed during PR readback; reload and retry`);
+    }
+    if (refileHead) {
+      if (!refileHead.recorded || !currentHead) throw this.reviewHeadMoveRefusal(task.id, refileHead.recorded);
+      if (currentHead !== refileHead.recorded) throw this.reviewHeadMoveRefusal(task.id, refileHead.recorded, currentHead);
+    } else if (approvalHead && currentHead && currentHead !== approvalHead) throw this.reviewHeadMoveRefusal(task.id, approvalHead, currentHead);
     const integrity = publicTestIntegrity(receipt && evidence && !this.isPii(task) ? await readTestIntegrity(receipt, evidence, read) : this.unknownTestIntegrity(this.isPii(task)), this.publicMetadataText);
     const evalResult = receipt && !this.isPii(task) ? await readEvalFor(config, evidence, receipt.repo, read) : undefined;
     const current = this.need(task.id, false, true);
@@ -5708,6 +5789,8 @@ export class Tasks {
     const metadata = acceptRefs(refs);
     const task = this.need(id, false, true);
     this.mine(task, by, "owner", true);
+    const proposedPlan = plan == null ? undefined : cleanPlan(plan, (task.profile ?? "dev") === (this.d.profile ?? "dev") ? this.d.profileData ?? task.profile ?? "dev" : task.profile ?? "dev");
+    this.validatePlanSources(proposedPlan && Object.keys(proposedPlan).length ? proposedPlan : task.plan);
     this.acceptanceCapacity(task, 0, "check"); // #1080: an urgent task may still take unaccepted offers; `accept` does that, after its gates
     if (metadata && !this.isPii(task) && (!this.nameable(metadata.repo!) || looksSecret(metadata.repo!) || this.aboutPrivatePath("", metadata.repo!, task))) throw new PreEffectToolRefusal("this repository metadata is private or sensitive and is not kept");
     const draft = metadata ? { ...task, refs: { ...task.refs, ...metadata } } : task;
@@ -5822,6 +5905,12 @@ export class Tasks {
     throw new PreEffectToolRefusal(`planner WIP capacity for ${owner}: limit ${limit}; open tasks ${ids(open)} (${parts.join("; ")})${pending ? `; pending claims ${pending}` : ""}; ${next}`);
   }
 
+  private validatePlanSources(plan: TaskPlan = {}): void {
+    for (const id of plan.sources ?? []) if (!this.d.intake?.sourceKnown(id)) {
+      throw new PreEffectToolRefusal(`unknown source ${id}; list registered ids with ahub source list`);
+    }
+  }
+
   /**
    * With a plan, the owners of overlapping tasks get it as a ride-along line, and an overlap only the plan reveals is
    * announced like one found at assignment (issue #31).
@@ -5833,6 +5922,11 @@ export class Tasks {
     this.mine(task, by, "owner", true);
     this.ready(task, true);
     if (task.state !== "proposed" && task.state !== "changes_requested" && task.state !== "in_progress") throw new PreEffectToolRefusal(`task #${task.id} is ${task.state}: cannot move to in_progress`);
+    // Models send null or {} for an optional field they leave empty: neither replaces a plan.
+    const given = plan == null ? undefined : cleanPlan(plan, (task.profile ?? "dev") === (this.d.profile ?? "dev") ? this.d.profileData ?? task.profile ?? "dev" : task.profile ?? "dev");
+    // File-list intent still replaces the old lists; omitted budget keys retain the planner-reviewed scope.
+    const cleaned = given && Object.keys(given).length ? { ...cleanCostPlan(task.plan ?? {}), ...given } : undefined;
+    this.validatePlanSources(cleaned ?? task.plan);
     this.studyDispatchCheck(task, task.owner ?? undefined);
     this.declaredNeedCheck(task, task.owner ?? by); // the owner's capability, also when the console user accepts on its behalf (`mine` admits USER)
     this.acceptanceCapacity(task, 0, "check");
@@ -5843,10 +5937,6 @@ export class Tasks {
       this.reviewedAdmissions.delete(task.id);
       if (!readback || readback.flow !== task.history.length || readback.owner !== task.owner) throw new PreEffectToolRefusal("current plan-review readback required before acceptance");
     }
-    // Models send null or {} for an optional field they leave empty: neither replaces a plan.
-    const given = plan == null ? undefined : cleanPlan(plan, (task.profile ?? "dev") === (this.d.profile ?? "dev") ? this.d.profileData ?? task.profile ?? "dev" : task.profile ?? "dev");
-    // File-list intent still replaces the old lists; omitted budget keys retain the planner-reviewed scope.
-    const cleaned = given && Object.keys(given).length ? { ...cleanCostPlan(task.plan ?? {}), ...given } : undefined;
     if (this.d.sdlc?.config().mode === "enforce" && task.sdlc?.planReview && !task.sdlc.planReview.scope
       && given && Object.keys(cleanCostPlan(given)).length) throw new PreEffectToolRefusal("legacy plan cost scope is unspecified; record a scoped planner review before acceptance");
     if (this.d.sdlc?.config().mode === "enforce" && task.sdlc?.planReview?.scope
@@ -5863,8 +5953,13 @@ export class Tasks {
     const repositoryChanged = this.repositories.scope(task.refs).key !== this.repositories.scope(draft.refs).key;
     const before = new Set(this.overlapHits(task).map((h) => h.task.id));
     this.studyDispatchCheck(task, task.owner ?? undefined);
-    this.acceptanceCapacity(task, 0, "displace"); // #1080: every gate has passed; synchronous from here to the accept write
-    const next = this.linkOnWrite(this.d.board.update(task.id, by, "accepted", { state: "in_progress", ...(cleaned ? { plan: cleaned } : {}), ...(metadata ? { refs: metadata } : {}) })); // #723: refs.repo may have just arrived
+    // #1115: a hub-sandboxed peer cannot run `git worktree add`, so for work that declares a worktree the hub makes it here, before any write. Anything that throws below clears it again.
+    const undoWorktree = this.hubWorktreeFor(task, task.owner ?? by);
+    let next: Task;
+    try {
+      this.acceptanceCapacity(task, 0, "displace"); // #1080: every gate has passed; synchronous from here to the accept write
+      next = this.linkOnWrite(this.d.board.update(task.id, by, "accepted", { state: "in_progress", ...(cleaned ? { plan: cleaned } : {}), ...(metadata ? { refs: metadata } : {}) })); // #723: refs.repo may have just arrived
+    } catch (error) { undoWorktree?.(); throw error; }
     this.captureOwnerAcceptance(next);
     this.d.notify(`task ${this.publicTitle(next)} accepted by ${by}`);
     if (repositoryChanged) this.cohorts.leave(next.id);
@@ -5925,6 +6020,51 @@ export class Tasks {
   /** #572 AC3: what the owner's `hub_task_done` result adds while the project root checkout is on a task branch. */
   checkoutNote = (): string | undefined => { const warning = mainCheckoutWarning(this.d.cwd, this.publicMetadataText); return warning ? `Note: ${warning}.` : undefined; };
 
+  /**
+   * #1115, #1129: the hub makes the worktree of a hub-sandboxed owner for write-class work (`implement`, `bulk_edit`) and for any work that declares `needs_worktree`. Returns a function that clears it again, or
+   * undefined when there is nothing to clear (another peer, a read-only class that did not declare it, a PII task, or a worktree an earlier accept already made). A failure refuses the
+   * accept before any board write and names the cause and the next step; nothing is left behind.
+   */
+  private hubWorktreeFor(task: Task, peer: PeerId): (() => void) | undefined {
+    const port = this.d.taskWorktree;
+    if (!port || peer === USER || peer === HUB || !port.applies(peer) || this.isPii(task) || !(task.signals.includes("needs_worktree") || writesRepository(task.class))) return undefined;
+    const made = port.create({ peer, task: task.id });
+    if (!made.ok) throw new PreEffectToolRefusal(`task #${task.id} needs its own git worktree and the hub could not make one for ${peer}: ${made.reason}; nothing was created, so no branch ref is left behind. Decline the task so the hub offers it to a peer that makes its own worktree`);
+    return made.created ? () => { try { port.remove({ peer, task: task.id }); } catch { /* the accept error that got us here is the one reported */ } } : undefined;
+  }
+
+  /** The hub-made worktree of the task's owner, for the accept answer: where to edit, and what the hub does at `hub_task_done`. */
+  worktreeNote(task: Task, peer: PeerId): string | undefined {
+    const found = this.d.taskWorktree?.describe(peer, task.id);
+    return found ? `Worktree: the hub made ${found.path} on branch ${found.branch} for this task. Edit files there only; do not run git. At hub_task_done the hub stages, commits and pushes it for you.` : undefined;
+  }
+
+  /**
+   * #1115: at `hub_task_done` the hub commits and pushes a hub-sandboxed peer's worktree and answers the refs the done carries. Undefined when the peer made no
+   * hub worktree for this task (it commits itself). A refused commit or push is a pre-effect refusal that names the cause and the next step: the board is untouched.
+   */
+  async worktreeHandoff(by: PeerId, id: unknown, refs: unknown): Promise<TaskRefs | undefined> {
+    const port = this.d.taskWorktree;
+    if (!port || by === USER || by === HUB || !port.applies(by)) return undefined;
+    const task = this.need(id, false, true);
+    this.mine(task, by, "owner", true);
+    if (this.isPii(task) || !port.describe(by, task.id)) return undefined;
+    const result = await port.commitAndPush({ peer: by, task: task.id, title: task.title });
+    if (!result.ok) throw new PreEffectToolRefusal(`hub_task_done for task #${task.id}: ${result.reason}`);
+    if (result.note) this.doneNotes.set(task.id, result.note);
+    return { ...cleanRefs(refs), commit: result.commit, branch: result.branch };
+  }
+
+  /** Decline or cancel: clear the hub-made worktree and its empty branch. Uncommitted work is kept and reported, never force-removed. */
+  private releaseHubWorktree(task: Task, peer: PeerId | null | undefined): void {
+    const port = this.d.taskWorktree;
+    if (!port || !peer || peer === USER || peer === HUB || !port.applies(peer)) return;
+    this.releaseNotice(`task #${task.id}: the hub-made worktree could not be cleared`, () => {
+      const removal = port.remove({ peer, task: task.id });
+      if (removal.kept) this.d.notify(`task #${task.id}: ${removal.kept}`);
+    });
+  }
+
   /**
    * `capacity` (#531): the owner has no room right now, so the decline excludes it only from this move's own reroute
    * (below), never from a later reroute or planner pull. Without it, a decline is a lasting refusal (`excluded()`), and so
@@ -5939,6 +6079,7 @@ export class Tasks {
     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}` : ""}`);
+    this.releaseHubWorktree(task, task.owner ?? by);
     // A capacity decline is not in excluded(), so this move's own reroute leaves the decliner out explicitly.
     try {
       return await this.assignOwner(back, HUB, { event: "reassigned", reason: "declined", clearOnFail: true, ...(capacity === true && task.owner ? { exclude: [task.owner] } : {}), ...(planned ? { planner: true } : {}) });
@@ -6122,11 +6263,20 @@ export class Tasks {
     let refresh: CompletionRefresh | undefined;
     if (initial.state === "in_review" || initial.state === "approved") {
       const commit = cleanRefs(refs).commit;
-      if (!commit || !/^[a-f0-9]{40}$/.test(commit) || commit === this.reviewHead(initial))
-        throw new PreEffectToolRefusal(`task #${initial.id} is already ${initial.state}; re-file requires a different full head SHA`);
+      const recorded = this.ownerReviewHead(initial) ?? this.findingHead(initial);
+      const currentReviewHead = this.ownerReviewHead(initial) ?? this.reviewHead(initial);
+      if (!commit || !/^[a-f0-9]{40}$/.test(commit) || commit === currentReviewHead) {
+        throw new PreEffectToolRefusal(`task #${initial.id} is already ${initial.state}${recorded ? ` with recorded review head ${recorded}` : ""}; re-file requires a different full head SHA. Owner must re-file hub_task_done with refs.commit set to the new full SHA`);
+      }
       refresh = { revision: initial.history.length, commit, state: initial.state };
     }
     const submittedCommit = cleanRefs(refs).commit;
+    if (submittedCommit && this.hasReviewHistory(initial) && !/^[a-f0-9]{40}$/.test(submittedCommit)) {
+      const recorded = this.ownerReviewHead(initial);
+      throw new PreEffectToolRefusal(`task #${initial.id}: re-file after review needs refs.commit to be a full lowercase SHA${recorded ? ` (recorded review head ${recorded})` : ""}; owner must re-file hub_task_done with the new full SHA in refs.commit`);
+    }
+    const refileHead: RefileHeadGuard | undefined = !submittedCommit && initial.sdlc?.repo && initial.sdlc.pr && this.hasReviewHistory(initial) && !this.isPii(initial)
+      ? { recorded: this.ownerReviewHead(initial) } : undefined;
     const draft = refresh ?? (submittedCommit && /^[a-f0-9]{40}$/.test(submittedCommit) ? { commit: submittedCommit } : undefined);
     const valid = () => { requestCheck(); return this.completionDraft(this.completionCurrent(id, by, true, refresh), draft); };
     if (initial.state === "approved") { await this.unmergedForReopen(initial, valid); valid(); }
@@ -6150,9 +6300,15 @@ export class Tasks {
     const current = () => this.withLink(valid(), link, refs);
     task = current();
     let reviewEvidence: PrEvidence | undefined;
-    if (this.d.sdlc && this.d.sdlc.config().mode !== "off") { reviewEvidence = await this.lifecycleGate(task, "review"); task = current(); }
-    const reviewAdmission = task.reviewer || this.d.prepareReviewBrief ? await this.reviewRequestAdmission(task, refs, true, by, reviewEvidence, undefined, staged => this.withLink(this.completionDraft(staged, draft), link, refs), !task.reviewer) : undefined;
+    if (this.d.sdlc && this.d.sdlc.config().mode !== "off") { reviewEvidence = await this.lifecycleGate(task, "review", undefined, undefined, refileHead); task = current(); }
+    const reviewAdmission = task.reviewer || this.d.prepareReviewBrief ? await this.reviewRequestAdmission(task, refs, true, by, reviewEvidence, undefined, staged => this.withLink(this.completionDraft(staged, draft), link, refs), !task.reviewer, refileHead) : undefined;
     task = current();
+    if (refileHead && (this.d.sdlc?.config().mode ?? "off") === "off") {
+      const currentHead = await this.currentPrHeadForReview(task, current);
+      task = current();
+      if (!refileHead.recorded || !currentHead) throw this.reviewHeadMoveRefusal(task.id, refileHead.recorded);
+      if (currentHead !== refileHead.recorded) throw this.reviewHeadMoveRefusal(task.id, refileHead.recorded, currentHead);
+    }
     const currentSpecTask = () => { const fresh = current(); return { ...fresh, refs: { ...fresh.refs, ...cleanRefs(refs) } }; };
     const specInspection = await this.inspectTaskSpecs(currentSpecTask(), by, specAck, currentSpecTask);
     task = current(); // the host head and task authority are revalidated after spec inspection
@@ -6507,7 +6663,7 @@ export class Tasks {
 
   /** The one place a review request is written: the first reviewer and a replacement get the same text, refs and privacy. */
   /** Review admission is separate from brief construction (#228). All refusals precede the requesting done's writes. */
-  private async reviewRequestAdmission(task: Task, refs?: TaskRefs, preEffect = true, actor: PeerId = task.owner ?? USER, previous?: PrEvidence, sameRequest?: () => boolean, stage: (task: Task) => Task = task => task, prepareOnly = false): Promise<ReviewReadiness | undefined> {
+  private async reviewRequestAdmission(task: Task, refs?: TaskRefs, preEffect = true, actor: PeerId = task.owner ?? USER, previous?: PrEvidence, sameRequest?: () => boolean, stage: (task: Task) => Task = task => task, prepareOnly = false, refileHead?: RefileHeadGuard): Promise<ReviewReadiness | undefined> {
     const mode = (this.d.sdlc?.config() ?? sdlcConfig(undefined)).mode;
     if (mode === "off" && !this.d.prepareReviewBrief) return undefined;
     let quietDrift = false;
@@ -6544,8 +6700,13 @@ export class Tasks {
     const evidence: ReviewReadiness = this.isPii(task)
       ? { ready: false, blockers: ["private review readiness unavailable"] }
       : task.sdlc ? reviewReadinessFromEvidence(previous, expected, this.d.sdlc?.config().requiredChecks ?? []) ?? await readReviewReadiness(task.sdlc, expected, read, this.d.sdlc?.config().requiredChecks ?? []) : { ready: false, blockers: ["review PR identity missing"] };
+    const currentHead = refileHead && !evidence.head && task.sdlc ? await readSdlcPrHead(task.sdlc, read) : evidence.head;
     const current = guard();
     const admitted: ReviewReadiness = quietDrift ? { ready: false, blockers: ["review readiness unknown: task changed during readback"] } : evidence;
+    if (refileHead) {
+      if (!refileHead.recorded || !currentHead) throw this.reviewHeadMoveRefusal(task.id, refileHead.recorded);
+      if (currentHead !== refileHead.recorded) throw this.reviewHeadMoveRefusal(task.id, refileHead.recorded, currentHead);
+    }
     if (!admitted.ready) {
       const message = `task ${this.publicTitle(current)}: premature review: ${admitted.blockers.join("; ")}`;
       if (mode === "enforce") throw new (preEffect ? PreEffectToolRefusal : Error)(message);
@@ -6879,7 +7040,7 @@ export class Tasks {
     // 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);
+    const resolvedHead = this.ownerReviewHead(initial) ?? this.findingHead(initial);
     let findingHead = resolvedHead;
     if (head !== undefined) {
       try { findingHead = sdlcReceipt({ reviewedHead: head }, initial.sdlc, this.d.sdlc?.config() ?? sdlcConfig(undefined)).reviewedHead; }
@@ -6926,7 +7087,7 @@ export class Tasks {
         if (gap.length) note = `${note ?? ""}\nCoverage gap (${gap.length}): ${list(gap)}`.trim();
       }
     }
-    if (head !== undefined && resolvedHead && findingHead !== resolvedHead) throw new PreEffectToolRefusal("supplied review head differs from the task resolved head");
+    if (head !== undefined && resolvedHead && findingHead !== resolvedHead) throw new PreEffectToolRefusal(`task #${initial.id}: supplied review head ${findingHead} differs from recorded task head ${resolvedHead}; owner must re-file hub_task_done with refs.commit set to the supplied full SHA before review`);
     // The PII screen reads the note of a review that passes these checks (issue #198); they run again after it.
     const withheld = await this.withholds("review note", parsed.length ? JSON.stringify({ note, findings: parsed }) : note, valid())
       || parsed.length > 0 && !this.findingTextAllowed(initial, parsed);
@@ -6963,6 +7124,12 @@ export class Tasks {
       await this.lifecycleGate(task, "approval", reviewedHead, proposedSets(task)); task = valid();
       const record = this.evalRecords.get(task.id); this.evalRecords.delete(task.id);
       if (record) note = `${note ?? ""}\n${record}`.trim();
+    } else if (verdict === "approved" && this.d.sdlc?.config().mode === "off" && this.d.sdlc?.gh && task.sdlc?.repo && task.sdlc.pr
+      && this.ownerReviewHead(task) && !this.isPii(task)) {
+      const expected = reviewedHead ?? this.ownerReviewHead(task) ?? this.findingHead(task);
+      const currentHead = await this.currentPrHeadForReview(task, valid);
+      task = valid();
+      if (expected && currentHead && currentHead !== expected) throw this.reviewHeadMoveRefusal(task.id, expected, currentHead);
     }
     let candidate: Extract<CandidateInput, { kind: "fail" }> | undefined;
     if (verdict === "changes_requested" && !evidenceOnly && items.length && this.d.candidates && !withheld && !this.isPii(task) && !this.d.privateTurn?.(by)) {

package/src/hub/ui.ts

@@ -149,7 +149,9 @@ export function startDashboard(options: DashboardOptions) {
           return reject(403, "live-test dashboard cannot write person-attributed content; use peer tools");
         }
         if (input.action === "sdlc_queue" || input.action === "sdlc_release") server.timeout(req, 35);
+        else if (input.action === "worktrees_refresh_prs") server.timeout(req, 45); // #1057: bounded gh reads (25 s) and two git passes
         else if (input.action === "backlog_split") server.timeout(req, Math.ceil((BACKLOG_SPLIT_SCREEN_TIMEOUT_MS + HUB_DB_BUSY_TIMEOUT_MS + 5_000) / 1000) + 5);
+        else if (input.action === "intake") server.timeout(req, 95); // the CLI's 90 s intake cap plus the HTTP response margin
         return json(await options.action(input, sessionOf(cookie)));
       } catch {
         // Exceptions may quote private task text or backend details. Never echo them to the page.

package/src/hub/worktree-prs.ts

@@ -0,0 +1,100 @@
+import { readSdlcPr, type SdlcGh } from "./sdlc.ts";
+import type { PrObserver, WorktreeFact } from "./worktree-shelf.ts";
+
+/**
+ * #1057 D1: the explicit "refresh PR states" action. It is the ONLY code that lets the worktree shelf learn a PR state from GitHub, through `readSdlcPr`
+ * (the same readback the guarded merge uses), and it runs only when a person asks. A panel refresh, `ahub worktrees` and the inbox alert never reach it, so
+ * they make no GitHub call (AC5): `worktree-shelf.ts` imports nothing from here and holds no GitHub access.
+ *
+ * What it reads is kept in memory, keyed by repository and PR number, and offered back to the shelf as a `PrObserver`.
+ * ponytail: the observations live in the daemon's memory, so a restart forgets them and those rows read `unknown` again until the next refresh; the upgrade is a
+ * `worktree_pr` table beside `worktree_override`, which is not worth a schema change before live use shows people refresh often.
+ */
+export const REFRESH_MAX_PRS = 8, REFRESH_CALL_MS = 8_000, REFRESH_TOTAL_MS = 25_000, OBSERVATIONS_MAX = 512;
+
+/**
+ * When GitHub says a PR that is no longer open was merged or closed, in ms. A second, narrow read (`pr view <n> --json mergedAt,closedAt`) that only a refresh makes and
+ * only for a PR `readSdlcPr` found merged or closed, so the shared readback the guarded merge and the queue use is unchanged. A missing, malformed or non-finite time is undefined,
+ * never 0: a merged PR with no change time is `unknown` to the partition, not settled.
+ */
+export async function readPrChangeTime(repo: string, pr: number, state: "merged" | "closed", gh: SdlcGh): Promise<number | undefined> {
+  // An owner and a name, each starting with a letter or digit: `..`, `.x` and `-x` are never a repository, so a hostile slug cannot reach gh as a path or a flag.
+  if (!/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9_.][A-Za-z0-9_.-]*$/.test(repo) || repo.split("/").some(part => part === "." || part === "..") || !Number.isSafeInteger(pr) || pr < 1) return undefined;
+  try {
+    const view = await gh(["pr", "view", String(pr), "--repo", repo, "--json", "mergedAt,closedAt"], 8_000, undefined, 4096);
+    if (view.code !== 0) return undefined;
+    const value = JSON.parse(view.stdout) as { mergedAt?: unknown; closedAt?: unknown } | null;
+    const text = state === "merged" ? value?.mergedAt ?? value?.closedAt : value?.closedAt;
+    const at = typeof text === "string" && text.length <= 40 ? Date.parse(text) : NaN;
+    return Number.isFinite(at) && at > 0 ? at : undefined;
+  } catch { return undefined; }
+}
+
+export interface PrObservation { state: "open" | "merged" | "closed"; changedAt?: number; at: number }
+export interface RefreshResult {
+  /** PRs read and stored. */
+  read: number;
+  /** PRs GitHub could not answer for (unreadable, no access, a gh failure): their state stays what it was. */
+  failed: number;
+  /** PRs not asked about because the cap or the time budget was reached. */
+  skipped: number;
+}
+
+/** A bounded, insertion-ordered map of what the last refreshes read. */
+export class PrObservations {
+  private readonly seen = new Map<string, PrObservation>();
+  record(repo: string, pr: number, observation: PrObservation): void {
+    const key = `${repo}#${pr}`;
+    this.seen.delete(key); this.seen.set(key, observation);
+    while (this.seen.size > OBSERVATIONS_MAX) this.seen.delete(this.seen.keys().next().value!);
+  }
+  /** The shelf's view of it: state and change time only. */
+  observer: PrObserver = (repo, pr) => {
+    const found = this.seen.get(`${repo}#${pr}`);
+    return found ? { state: found.state, ...(found.changedAt !== undefined ? { changedAt: found.changedAt } : {}) } : undefined;
+  };
+  /** When the newest observation was read, or undefined when none was. */
+  get lastAt(): number | undefined { let at: number | undefined; for (const value of this.seen.values()) at = Math.max(at ?? 0, value.at); return at; }
+  get size(): number { return this.seen.size; }
+}
+
+/** The PRs a refresh would ask about: bound tasks with a repository and a PR that the board does not already show as merged, oldest activity first. */
+export function refreshTargets(facts: readonly WorktreeFact[], limit = REFRESH_MAX_PRS): { repo: string; pr: number }[] {
+  const seen = new Set<string>(), out: { repo: string; pr: number }[] = [];
+  const candidates = facts.filter(f => !f.main && !f.instance && f.task?.repo !== undefined && f.task.pr !== undefined && f.pr.state !== "merged")
+    .sort((a, b) => a.lastActiveAt - b.lastActiveAt);
+  for (const fact of candidates) {
+    const key = `${fact.task!.repo}#${fact.task!.pr}`;
+    if (seen.has(key)) continue;
+    seen.add(key); out.push({ repo: fact.task!.repo!, pr: fact.task!.pr! });
+  }
+  return out.slice(0, limit);
+}
+
+/**
+ * Read each target once, one at a time, under one total budget. `gh` is the host's runner (`sdlcGh` bound to the project), never an argument a request supplies.
+ * `readSdlcPr` validates the repository and PR number itself and builds a fixed read-only argv. Every failure is counted and the old state stands.
+ */
+export async function refreshPrStates(
+  targets: readonly { repo: string; pr: number }[],
+  gh: SdlcGh,
+  store: PrObservations,
+  options: { now?: () => number; totalMs?: number; callMs?: number; max?: number } = {},
+): Promise<RefreshResult> {
+  const now = options.now ?? Date.now, started = now(), total = options.totalMs ?? REFRESH_TOTAL_MS, perCall = options.callMs ?? REFRESH_CALL_MS;
+  const left = () => Math.max(0, started + total - now());
+  const bounded: SdlcGh = async (args, timeoutMs, cwd, maxOutputBytes) => left() <= 0 ? { code: 1, stdout: "" } : gh(args, Math.max(1, Math.min(timeoutMs ?? perCall, perCall, left())), cwd, maxOutputBytes);
+  const asked = targets.slice(0, options.max ?? REFRESH_MAX_PRS);
+  let read = 0, failed = 0, done = 0;
+  for (const target of asked) {
+    if (left() <= 0) break;
+    done++;
+    const evidence = await readSdlcPr({ stage: "pr", repo: target.repo, pr: target.pr }, bounded).catch(() => undefined);
+    if (!evidence) { failed++; continue; }
+    const state = evidence.state === "MERGED" ? "merged" : evidence.state === "CLOSED" ? "closed" : "open";
+    const changedAt = state === "open" ? undefined : await readPrChangeTime(target.repo, target.pr, state, bounded);
+    store.record(target.repo, target.pr, { state, ...(changedAt !== undefined ? { changedAt } : {}), at: now() });
+    read++;
+  }
+  return { read, failed, skipped: targets.length - done };
+}