@staix/agent-hub 0.28.0 → 0.29.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`);
     }
   }
 
@@ -4044,7 +4082,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 +4128,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 +4542,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 +5698,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 +5718,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);
@@ -5863,8 +5931,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 +5998,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 +6057,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 +6241,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 +6278,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 +6641,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 +6678,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 +7018,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 +7065,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 +7102,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/local/deny.ts

@@ -77,6 +77,54 @@ const hooksUnder = (parent: string): string => {
   return depth > MAX_ANCHOR_DEPTH ? `^.*/${hfsFoldedName("hooks")}(/|$)` : `^${"/[^/]+".repeat(depth)}/${hfsFoldedName("hooks")}(/|$)`;
 };
 
+/**
+ * #1123: a sandboxed command may not move what a branch, HEAD or a linked worktree points at. `refs/**` (branches, tags, `refs/stash`), `packed-refs*`, `HEAD*` (its lock too) and
+ * `worktrees/**` (a linked worktree's admin dir: its HEAD, index, logs) are refused directly under every plain `.git` and under each external git dir (the common dir and a linked
+ * worktree's own, whatever they are named). The hub's own git runs outside the sandbox and is unaffected, so #1115's hub commit still lands.
+ *
+ * Every name must sit DIRECTLY under its git dir. An unanchored `refs` or `worktrees` filter would also match an ANCESTOR of the project with that name, and a project under
+ * `~/worktrees/` would lose every `.git` write (the #520 `hooks` lesson). So each rule is adjacent by construction: one literal for `.git` + a short name, or, for the long names
+ * (`worktrees`, `packed-refs`, where `.git` + name would pass the 1024-byte literal limit), a front half and a back half that must both match, or a depth anchor for an external dir.
+ * A submodule's git dir (`.git/modules/<name>`, nested ones, and `.git/worktrees/<wt>/modules/<name>` for a linked worktree) is covered the same way (`subDirs`, the discovered
+ * ones: a git dir that is not discovered is refused whole by the #518/#520 rules), per the person's "deny .git writes" decision: nothing is listed as a residual.
+ */
+const refDepth = (d: string): number => d.split("/").filter(Boolean).length;
+/**
+ * `^(/[^/]+){depth}/<name>(/|$)`: `name` as the entry directly under `d`, the depth written out because seatbelt ignores `{n}`. The folded names cost (measured, bytes of regex): `refs` 334,
+ * `worktrees` 669, so past the depth where the path plus the name would near 1024 it falls back to the unanchored name, which over-refuses only under an ancestor with that name and
+ * never under-protects.
+ */
+const refUnder = (d: string, name: string): string => {
+  const depth = refDepth(d), cost = Buffer.byteLength(hfsFoldedName(name)) + depth * 6 + 8;
+  return cost > 1000 ? `^.*/${hfsFoldedName(name)}(/|$)` : `^${"/[^/]+".repeat(depth)}/${hfsFoldedName(name)}(/|$)`;
+};
+function gitRefRules(gitDirs: string[], subDirs: string[] = []): string[] {
+  const git = hfsFoldedName(".git");
+  const re = (s: string) => `(regex ${sbplString(s)})`;
+  const name = (n: string) => hfsFoldedName(n);
+  // A linked worktree's own submodule git dirs (`worktrees/<wt>/modules/**`) are governed by the #518/#520 rules, not these.
+  const plainSub = `(require-not ${re(`^.*/${git}/worktrees/[^/]+/modules(/|$)`)})`;
+  const plain = [
+    // `.git` (335 bytes) + `HEAD` or `refs` (334) fit one literal: adjacent by construction. `HEAD.lock` goes with `HEAD`.
+    re(`^.*/${git}/${name("HEAD")}(\\.lock)?$`),
+    re(`^.*/${git}/${name("refs")}(/|$)`),
+    // `.git` + `packed-refs` (803) and `.git` + `worktrees` (669) do not fit one literal. The front literal pins the start of the name right under a `.git`, and for `worktrees` the
+    // back literal pins its end; `packed` alone covers `packed-refs` and its lock/new files, which is the intent.
+    re(`^.*/${git}/${name("packed")}`),
+    `(require-all ${re(`^.*/${git}/${name("work")}`)} ${re(`^.*${name("trees")}(/|$)`)} ${plainSub})`,
+  ];
+  const external = [...gitDirs, ...subDirs].flatMap((d) => {
+    const own = sbplString(d), direct = re(`^${sbplEscape(d)}/[^/]+$`);
+    return [
+      `(require-all ${direct} ${re(`^.*/${name("HEAD")}(\\.lock)?$`)})`,
+      `(require-all ${direct} ${re(`^.*/${name("packed")}`)})`,
+      `(require-all (subpath ${own}) ${re(refUnder(d, "refs"))})`,
+      `(require-all (subpath ${own}) ${re(refUnder(d, "worktrees"))} (require-not ${re(`^${sbplEscape(d)}/worktrees/[^/]+/modules(/|$)`)}))`,
+    ];
+  });
+  return [...plain, ...external];
+}
+
 export function hubWriteRegexes(root: string, gitDirs: string[] = [], moduleGit: readonly { root: string; entries: string[]; dirs?: string[] }[] = [], worktreesRoot?: string): string[] {
   const git = hfsFoldedName(".git");
   const re = (s: string) => `(regex ${sbplString(s)})`;
@@ -157,6 +205,7 @@ export function hubWriteRegexes(root: string, gitDirs: string[] = [], moduleGit:
     `(require-all ${re(`^.*/${git}/[^/]+$`)} ${CONFIG_WORKTREE_NAME.map(re).join(" ")})`,
     re(`^.*/${git}/${hfsFoldedName("hooks")}(/|$)`),
     `(require-all ${re(`^.*/${git}/.*$`)} ${re(`^.*/${hfsFoldedName("commondir")}$`)})`,
+    ...gitRefRules(gitDirs, allDirs),
     ...modules,
     ...siblings,
     ...external,

package/src/local/tools.ts

@@ -117,7 +117,7 @@ export const TOOL_SCHEMAS = [
   fn("write", "Create or overwrite a file inside the project. Needs the user's approval.", { path: str, content: str }, ["path", "content"]),
   fn("edit", "Replace one exact, unique occurrence of `old` with `new` in a file. Needs the user's approval.", { path: str, old: str, new: str }, ["path", "old", "new"]),
   fn("bash", "Run a shell command in the project directory, sandboxed: no writes outside the project, no credential reads, no network unless the hub enables it. Follows hub permission policy: proven bounded read-only commands may run automatically in ask-when-needed; other commands ask.", { command: str, timeout_s: { type: "integer", minimum: 1, maximum: 600 } }, ["command"]),
-  fn("git", "Run git in the project. status, diff, log, show, ls-files, blame, rev-parse run freely; add, commit, restore, checkout, switch, stash, mv, rm, branch, merge, rebase, cherry-pick, revert, tag need approval; everything else (push, fetch, config, remote ...) is refused.", { args: { type: "array", items: str, minItems: 1 } }, ["args"]),
+  fn("git", "Run git in the project. status, diff, log, show, ls-files, blame, rev-parse run freely; add, commit, restore, checkout, switch, stash, mv, rm, branch, merge, rebase, cherry-pick, revert, tag need approval; everything else (push, fetch, config, remote ...) is refused. The sandbox does not let you move a branch, tag or HEAD anywhere (commit, branch, tag, stash, switch, merge, rebase and reset fail, submodules included), nor stage with add inside a linked worktree: edit files, and the hub commits and pushes them when you call hub_task_done.", { args: { type: "array", items: str, minItems: 1 } }, ["args"]),
   fn("hub_send", "Send a message to the other agents now, before your turn ends. Conclusions only. Your final answer is shared anyway; use this for something that cannot wait.", { text: str, to: { type: "array", items: str } }, ["text"]),
 ];
 
@@ -235,7 +235,9 @@ export async function runTool(name: string, rawArgs: string, ctx: ToolContext):
         // Sandboxed like bash: flags such as --output or an editor cannot write outside the project or reach the network.
         const res = await sandboxedExec(["git", "--no-pager", ...args], { cwd: ctx.cwd, profile: ctx.sandboxProfile, readOnlyData: !!ctx.readOnly?.length, ...(ctx.sandboxEnv ? { env: ctx.sandboxEnv } : {}), ...(ctx.signal ? { signal: ctx.signal } : {}) });
         try { ctx.onProcessExit?.(res.code); } catch { /* optional status observer never changes a tool result */ }
-        return `${res.output}\n(exit ${res.code})`;
+        // #1123: the profile refuses writes to refs, HEAD, packed-refs and a linked worktree's admin dir, so a commit, branch, tag, stash or switch cannot succeed here. Say so, with the next step.
+        const refused = res.code !== 0 && /(?:\.git\/(?:refs|HEAD|packed-refs|worktrees)\b|cannot lock ref|index\.lock)[^\n]*(?:Operation not permitted|not permitted)/i.test(res.output);
+        return `${res.output}${refused ? "\nnote: the sandbox does not let you move a branch, tag or HEAD, or stage inside a linked worktree (#1123). Leave your edits in the working tree and finish with hub_task_done. For implementation work the hub stages, commits and pushes them for you; for work that changes no files, or a private task, there is nothing for it to commit, so do not try to commit it yourself." : ""}\n(exit ${res.code})`;
       }
       case "doc_read": {
         if (!ctx.docRead) return "error: doc_read is not enabled for this project (local.doc_read in .agenthub/config.local.json)";

package/src/memory/brief.ts

@@ -1,4 +1,5 @@
 import { buildIntentBrief, type IntentBriefOptions, type IntentBriefSource } from "@staix/agent-mem";
+import { controlWriteSpan } from "../hub/control-write-trace.ts";
 import type { PeerId } from "../hub/envelope.ts";
 import type { MemoryClient } from "./client.ts";
 
@@ -70,6 +71,10 @@ export class Briefs {
   ) {}
 
   async forTask(peer: PeerId, task: BriefTask, priority: readonly NativeItem[] = []): Promise<string | undefined> {
+    return controlWriteSpan("memory", () => this.forTaskBody(peer, task, priority));
+  }
+
+  private async forTaskBody(peer: PeerId, task: BriefTask, priority: readonly NativeItem[]): Promise<string | undefined> {
     // A brief snapshots its configured cap once, before either optional source is selected.
     const maximum = typeof this.maxItems === "function" ? this.maxItems() : this.maxItems;
     let corpusRevision: string | undefined;

package/src/memory/client.ts

@@ -1,5 +1,6 @@
 import packageJson from "../../package.json";
 import { createHash } from "node:crypto";
+import { controlWriteSpan } from "../hub/control-write-trace.ts";
 import { CaptureStore, SearchIndex, looksSecret, memoryBase, readCaptureConfig, type CaptureOptions as StoreCaptureOptions, type MemoryStore, type CandidateStore, type View } from "@staix/agent-mem";
 
 export interface CaptureEvent {
@@ -54,8 +55,10 @@ export class MemoryClient {
   }
   close(): void { this.closed = true; this.releaseCapture(); }
   private run<T>(work: (o: MemoryClientOptions) => T): T | undefined {
-    try { if (!this.options || this.closed) return undefined; this.options.check(); return work(this.options); }
-    catch { this.releaseCapture(); this.options?.log?.("amem operation unavailable"); return undefined; }
+    return controlWriteSpan("memory", () => {
+      try { if (!this.options || this.closed) return undefined; this.options.check(); return work(this.options); }
+      catch { this.releaseCapture(); this.options?.log?.("amem operation unavailable"); return undefined; }
+    });
   }
   private rows(o: MemoryClientOptions): View[] {
     const store = o.store;