project-autopilot 12.0.0 → 12.0.1

package/scripts/plan-review-rounds.mjs

@@ -7,16 +7,37 @@ import { normalizeFindings } from "./review-feedback.mjs";
 import { normalizePreviousStatuses } from "./code-review-rounds.mjs";
 
 const STATE_KEY = "planReviewHistory";
+const NOTES_KEY = "planReviewNotes";
 const MAX_CUMULATIVE_CHARS = 16000;
 
+// The operator's severity split (backlog #8): only a problem that would make
+// the plan wrong or unexecutable may FAIL a review. Everything cosmetic or
+// optional is recorded as a note, so a fresh full read cannot keep looping on
+// line anchors and wording nits. Shared by every plan-review brief below.
+export const PLAN_REVIEW_SEVERITY_LINE =
+  'Classify every problem by severity. BLOCKING = wrong behaviour or logic, a missing or contradictory requirement, a wrong API or data contract, an unsafe data or permission path, a requirement or task that cannot be tested or executed, or a test the change will break that the plan does not list. MINOR = line-number anchors, wording or precision, cross-reference nits, style, and nice-to-have extra tests or coverage. Put only BLOCKING problems in "findings"; return FAIL only when there is at least one. List MINOR ones in a separate "notes" array of strings in the final sentinel — they do not fail the review.';
+
 export const PLAN_REVIEW_EXHAUSTIVE_LINE =
-  "This is review round 1 — make it EXHAUSTIVE: report every problem you can find in this first review, across all categories you check, not one batch at a time. Later rounds will only verify the fixes and the changes made, so anything you leave out now will not be looked for again.";
+  `This is review round 1 — make it EXHAUSTIVE: report every problem you can find in this first review, across all categories you check, not one batch at a time. Later rounds will only verify the fixes and the changes made, so anything you leave out now will not be looked for again. ${PLAN_REVIEW_SEVERITY_LINE}`;
 
 export const PLAN_REVIEW_VERIFY_LINE =
-  'This is a later review round. First verify each previous finding listed below was fixed (go through them one by one) and report the outcome in the final sentinel as "previous":[{"finding":"<the previous finding text, shortened>","status":"fixed"|"not_fixed"}] (one entry per previous finding; keep a not_fixed one in "findings" too). Raise NEW findings only if this revision introduced them, or if they would actually break execution; do not raise new style, preference or nice-to-have findings about content that was already reviewed.';
+  `This is a later review round. First verify each previous finding listed below was fixed (go through them one by one) and report the outcome in the final sentinel as "previous":[{"finding":"<the previous finding text, shortened>","status":"fixed"|"not_fixed"}] (one entry per previous finding; keep a not_fixed one in "findings" too). Raise NEW findings only if this revision introduced them, or if they would actually break execution; do not raise new style, preference or nice-to-have findings about content that was already reviewed. ${PLAN_REVIEW_SEVERITY_LINE}`;
 
 export const PLAN_REVIEW_FULL_LINE =
-  "Review the whole plan again from scratch. Report every problem you can find in the current revision, across all categories you check, not just whether the previously reported ones were fixed. Earlier fixes stay in scope: a regression or a newly visible problem anywhere in the plan is a valid finding.";
+  `Review the whole plan again from scratch. Report every problem you can find in the current revision, across all categories you check, not just whether the previously reported ones were fixed. Earlier fixes stay in scope: a regression or a newly visible problem anywhere in the plan is a valid finding. ${PLAN_REVIEW_SEVERITY_LINE}`;
+
+// A scoped PASS only verified the earlier findings and the changes made since.
+// Before it is accepted, one fresh FULL review must run with no previous
+// findings in its brief — marked so logs/run notes can identify it as the
+// confirmation round. It reviews everything again, but only BLOCKING problems
+// may fail it; minor points are notes, so the confirmation cannot loop on
+// line anchors or wording nits.
+export const PLAN_REVIEW_CONFIRMATION_LINE =
+  `This is a confirmation full review after a scoped re-review PASS: no previous findings are listed, so review the whole plan again from scratch, across all categories you check, not one batch at a time. ${PLAN_REVIEW_SEVERITY_LINE}`;
+
+const CONFIRMATION_KEY = "planReviewConfirmation";
+const REVISIONS_KEY = "planReviewRevisions";
+const REVIEWER_ROUNDS_KEY = "planReviewReviewerRounds";
 
 function slot(state, key) {
   const list = state?.[STATE_KEY]?.[key];
@@ -25,9 +46,35 @@ function slot(state, key) {
 
 export function planReviewRoundCount(state, key) { return slot(state, key).length; }
 
+// Rounds the plan reviewer actually ran. A deterministic verify-denylist
+// rejection records findings (the planner must fix them) but the reviewer
+// never saw the plan, so that round is NOT a full review: the next reviewer
+// call is effectively the first full review and its PASS needs no
+// confirmation. Kept separate from the findings history so that history can
+// still carry every earlier round to the planner/reviewer.
+export function planReviewReviewerRoundCount(state, key) {
+  const used = state?.[REVIEWER_ROUNDS_KEY]?.[key];
+  return Number.isInteger(used) && used >= 0 ? used : 0;
+}
+
+function recordPlanReviewReviewerRound(state, key) {
+  if (!state || typeof state !== "object" || !key) return 0;
+  const used = planReviewReviewerRoundCount(state, key) + 1;
+  if (!state[REVIEWER_ROUNDS_KEY] || typeof state[REVIEWER_ROUNDS_KEY] !== "object") state[REVIEWER_ROUNDS_KEY] = {};
+  state[REVIEWER_ROUNDS_KEY][key] = used;
+  return used;
+}
+
 // Append one failed round's findings (bounded, normalized). Empty -> no-op.
-export function recordPlanReviewRound(state, key, findings, previous = []) {
+// `reviewer:false` records a deterministic rejection (the reviewer did not
+// run), which must not count towards the confirmation decision nor turn the
+// next reviewer round into a scoped re-review.
+export function recordPlanReviewRound(state, key, findings, previous = [], {reviewer = true} = {}) {
   if (!state || typeof state !== "object" || !key) return 0;
+  // The reviewer ran even when it returned no findings: that still counts
+  // for the confirmation decision (a later scoped PASS follows a real full
+  // review). Only the findings history is a no-op when empty.
+  if (reviewer) recordPlanReviewReviewerRound(state, key);
   const normalized = normalizeFindings(findings);
   if (!normalized.length) return planReviewRoundCount(state, key);
   if (!state[STATE_KEY] || typeof state[STATE_KEY] !== "object") state[STATE_KEY] = {};
@@ -38,14 +85,110 @@ export function recordPlanReviewRound(state, key, findings, previous = []) {
 }
 
 // Resume from older state that has current findings but no history yet.
+// Nothing to seed (no findings) must not look like a reviewer round.
 export function seedPlanReviewHistory(state, key, findings) {
-  if (planReviewRoundCount(state, key) === 0) recordPlanReviewRound(state, key, findings);
+  if (planReviewRoundCount(state, key) === 0 && normalizeFindings(findings).length) recordPlanReviewRound(state, key, findings);
 }
 
 export function clearPlanReviewHistory(state, key) {
-  if (!state?.[STATE_KEY] || typeof state[STATE_KEY] !== "object") return;
-  if (key) delete state[STATE_KEY][key]; else delete state[STATE_KEY];
-  if (state[STATE_KEY] && !Object.keys(state[STATE_KEY]).length) delete state[STATE_KEY];
+  if (state?.[STATE_KEY] && typeof state[STATE_KEY] === "object") {
+    if (key) delete state[STATE_KEY][key]; else delete state[STATE_KEY];
+    if (!Object.keys(state[STATE_KEY]).length) delete state[STATE_KEY];
+  }
+  if (state?.[REVIEWER_ROUNDS_KEY] && typeof state[REVIEWER_ROUNDS_KEY] === "object") {
+    if (key) delete state[REVIEWER_ROUNDS_KEY][key]; else delete state[REVIEWER_ROUNDS_KEY];
+    if (!Object.keys(state[REVIEWER_ROUNDS_KEY]).length) delete state[REVIEWER_ROUNDS_KEY];
+  }
+  clearPlanReviewNotes(state, key);
+}
+
+// Minor notes from the latest plan-review verdict (backlog #8). Bounded and
+// fail-closed like findings: non-strings and unusable entries are dropped.
+export function normalizePlanReviewNotes(raw) {
+  return normalizeFindings(Array.isArray(raw) ? raw.filter(note => typeof note === "string") : []);
+}
+
+export function planReviewNotes(state, key) {
+  const list = state?.[NOTES_KEY]?.[key];
+  return Array.isArray(list) ? list : [];
+}
+
+// A REVIEW that returned no notes clears the slot, so a later revision never
+// inherits notes from an older, superseded review.
+export function recordPlanReviewNotes(state, key, notes) {
+  if (!state || typeof state !== "object" || !key) return [];
+  const normalized = normalizePlanReviewNotes(notes);
+  if (!state[NOTES_KEY] || typeof state[NOTES_KEY] !== "object") state[NOTES_KEY] = {};
+  if (normalized.length) state[NOTES_KEY][key] = normalized;
+  else delete state[NOTES_KEY][key];
+  if (!Object.keys(state[NOTES_KEY]).length) delete state[NOTES_KEY];
+  return normalized;
+}
+
+export function planReviewNotesText(state, key) {
+  const notes = planReviewNotes(state, key);
+  if (!notes.length) return "";
+  return `Minor notes (optional, fix if cheap):\n${notes.map((note, i) => `${i + 1}. ${note}`).join("\n")}`;
+}
+
+export function clearPlanReviewNotes(state, key) {
+  if (!state?.[NOTES_KEY] || typeof state[NOTES_KEY] !== "object") return;
+  if (key) delete state[NOTES_KEY][key]; else delete state[NOTES_KEY];
+  if (state[NOTES_KEY] && !Object.keys(state[NOTES_KEY]).length) delete state[NOTES_KEY];
+}
+
+// A PASS that only came after earlier FULL reviewer rounds is a SCOPED
+// re-review: it verified the fixes, it did not look at the rest of the plan
+// again. Such a PASS needs the one full confirmation review below before it
+// is accepted. A deterministic (denylist) rejection is not a full reviewer
+// round — the reviewer never ran — so the next reviewer PASS is simply the
+// first full review and is accepted without confirmation. With convergence
+// disabled every round is already a full re-review, so no confirmation round
+// is added there.
+export function planReviewPassNeedsConfirmation(state, key, converge = true) {
+  return converge !== false && planReviewReviewerRoundCount(state, key) > 0;
+}
+
+// Persisted "the next review is the confirmation full review" marker. It must
+// survive a kill during the confirmation call: on resume the loop reads it and
+// re-runs the full confirmation review instead of accepting the scoped PASS.
+export function planReviewConfirmationPending(state, key) {
+  return Boolean(state?.[CONFIRMATION_KEY]?.[key] === true);
+}
+
+export function markPlanReviewConfirmationPending(state, key) {
+  if (!state || typeof state !== "object" || !key) return;
+  if (!state[CONFIRMATION_KEY] || typeof state[CONFIRMATION_KEY] !== "object") state[CONFIRMATION_KEY] = {};
+  state[CONFIRMATION_KEY][key] = true;
+}
+
+export function clearPlanReviewConfirmation(state, key) {
+  if (!state?.[CONFIRMATION_KEY] || typeof state[CONFIRMATION_KEY] !== "object") return;
+  if (key) delete state[CONFIRMATION_KEY][key]; else delete state[CONFIRMATION_KEY];
+  if (state[CONFIRMATION_KEY] && !Object.keys(state[CONFIRMATION_KEY]).length) delete state[CONFIRMATION_KEY];
+}
+
+// Revision counter for the SpecKit gate loops (standalone keeps its own
+// `standalonePlanReview.revision`). A review FAIL that actually leads to a
+// Planner revision consumes one; a FAIL that escalates (no revision follows)
+// consumes none, and a PASS never consumes one.
+export function planReviewRevisionCount(state, key) {
+  const used = state?.[REVISIONS_KEY]?.[key];
+  return Number.isInteger(used) && used >= 0 ? used : 0;
+}
+
+export function recordPlanReviewRevision(state, key) {
+  const used = planReviewRevisionCount(state, key) + 1;
+  if (!state || typeof state !== "object" || !key) return used;
+  if (!state[REVISIONS_KEY] || typeof state[REVISIONS_KEY] !== "object") state[REVISIONS_KEY] = {};
+  state[REVISIONS_KEY][key] = used;
+  return used;
+}
+
+export function clearPlanReviewRevisions(state, key) {
+  if (!state?.[REVISIONS_KEY] || typeof state[REVISIONS_KEY] !== "object") return;
+  if (key) delete state[REVISIONS_KEY][key]; else delete state[REVISIONS_KEY];
+  if (state[REVISIONS_KEY] && !Object.keys(state[REVISIONS_KEY]).length) delete state[REVISIONS_KEY];
 }
 
 function render(rounds) {
@@ -59,11 +202,23 @@ function render(rounds) {
 // With convergence disabled every round is a full-plan re-review.
 export function planReviewerRoundLines(state, key, converge = true) {
   if (converge === false) return [PLAN_REVIEW_FULL_LINE];
+  // The next review is the confirmation full review: no previous findings.
+  if (planReviewConfirmationPending(state, key)) return planReviewerConfirmationLines();
   const rounds = slot(state, key);
-  if (!rounds.length) return [PLAN_REVIEW_EXHAUSTIVE_LINE];
+  // History exists but the plan reviewer has never run (only deterministic
+  // denylist rejections): this next call IS the first full review, so give it
+  // the exhaustive first-round brief rather than a scoped verification brief.
+  if (!rounds.length || planReviewReviewerRoundCount(state, key) === 0) return [PLAN_REVIEW_EXHAUSTIVE_LINE];
   return [PLAN_REVIEW_VERIFY_LINE, `Previous findings from all earlier review rounds (verify each):\n${render(rounds)}`];
 }
 
+// The confirmation round's reviewer brief: a fresh exhaustive full review with
+// NO previous findings listed. Never call planReviewerRoundLines() for it, or
+// it would become another scoped verification round.
+export function planReviewerConfirmationLines() {
+  return [PLAN_REVIEW_CONFIRMATION_LINE];
+}
+
 // Planner revision brief: findings of all rounds BEFORE the latest (the latest
 // is already quoted as the feedback that must be addressed).
 export function plannerEarlierRoundsText(state, key, converge = true) {

package/scripts/planning-boundary.mjs

@@ -33,7 +33,7 @@ import path from "node:path";
 export const CLAUDE_MD_MARKER_BEGIN = "<!-- SPECKIT START -->";
 export const CLAUDE_MD_MARKER_END = "<!-- SPECKIT END -->";
 
-function normalizeRel(p) {
+export function normalizeRel(p) {
   return String(p).replaceAll("\\", "/");
 }
 
@@ -65,17 +65,27 @@ function specifyAllowed(rel, featureDir) {
   if (rel.startsWith(`${base}checklists/`) && rel.length > `${base}checklists/`.length) return true;
   return false;
 }
-function planAllowed(rel, featureDir) {
+function planAllowed(rel, featureDir, revision = false) {
   if (rel === "CLAUDE.md") return true;
   if (!featureDir) return false;
   const base = `specs/${featureDir}/`;
   if ([`${base}plan.md`, `${base}research.md`, `${base}data-model.md`, `${base}quickstart.md`].includes(rel)) return true;
   if (rel.startsWith(`${base}contracts/`) && rel.length > `${base}contracts/`.length) return true;
+  // A gate revision answering review findings may also repair an EARLIER
+  // stage's artifact that a finding cites (spec.md during plan). Same feature
+  // dir only; never a later stage's artifact (tasks.md) nor feature.json.
+  if (revision && rel === `${base}spec.md`) return true;
   return false;
 }
-function tasksAllowed(rel, featureDir) {
+function tasksAllowed(rel, featureDir, revision = false) {
   if (!featureDir) return false;
-  return rel === `specs/${featureDir}/tasks.md`;
+  const base = `specs/${featureDir}/`;
+  if (rel === `${base}tasks.md`) return true;
+  // A gate revision answering review findings may also repair earlier stages'
+  // artifacts that a finding cites (spec.md, plan.md during tasks). Same
+  // feature dir only; never feature.json nor CLAUDE.md.
+  if (revision && (rel === `${base}spec.md` || rel === `${base}plan.md`)) return true;
+  return false;
 }
 const STAGE_ALLOW = { specify: specifyAllowed, plan: planAllowed, tasks: tasksAllowed };
 
@@ -237,7 +247,7 @@ function reasonForRejection(rel, stage, featureDir, preexistingFeatureDirs) {
 // claudeMdBaseline: CLAUDE.md content captured at session start, or null.
 export function evaluatePlanningWriteBoundary({
   stage, touchedFiles = [], preexistingFeatureDirs = [], resolvedFeatureDir = null,
-  readFile = () => null, claudeMdBaseline = null
+  readFile = () => null, claudeMdBaseline = null, revision = false
 } = {}) {
   const matcher = STAGE_ALLOW[stage];
   if (!matcher) throw new Error(`Unknown planning stage: ${stage}`);
@@ -276,7 +286,7 @@ export function evaluatePlanningWriteBoundary({
       violations.push({ path: rel, reason: "multiple_new_feature_directories" });
       continue;
     }
-    if (!matcher(rel, featureDir)) {
+    if (!matcher(rel, featureDir, revision)) {
       violations.push({ path: rel, reason: reasonForRejection(rel, stage, featureDir, preexistingFeatureDirs) });
       continue;
     }

package/scripts/planning-continuation.mjs

@@ -64,6 +64,10 @@ export { readRolloverDeadEnds };
 export const PLANNING_CONTINUATION_SCOPES = [
   "task:standalone:planning:planner",
   "task:standalone:planning:plan_reviewer",
+  "task:speckit:planning:planner",
+  "task:speckit:planning:plan_reviewer",
+  "task:gsd:planning:planner",
+  "task:gsd:planning:plan_reviewer",
 ];
 
 // Shared spent-continuation predicate: true when the scope is a planning
@@ -92,6 +96,44 @@ export function hasSpentPlanningContinuations(s) {
   return false;
 }
 
+// Drop one planning role scope's continuation entries: the
+// continuationBudgetKey(scope) entries from
+// continuationBudgets/noProgressGenerations/rolloverDeadEnds, the bare-scope
+// entry from planningProgressDigests, the backstopLedgerKey(scope) entry from
+// backstopFirings (via the existing clearBackstopFirings), and
+// lastContinuation when it names this scope. Implementer keys, failureBudgets
+// and every OTHER planning scope survive. Returns the number of entries
+// dropped. Called when that role finishes a run, so a new stage starts with a
+// fresh continuation allowance instead of inheriting the previous stage's.
+export function clearPlanningContinuationScope(s, scope) {
+  if (!s || typeof s !== "object" || !isPlanningContinuationScope(scope)) return 0;
+  let cleared = 0;
+  const budgetKey = continuationBudgetKey(scope);
+  if (s.continuationBudgets && typeof s.continuationBudgets === "object" && budgetKey in s.continuationBudgets) {
+    delete s.continuationBudgets[budgetKey];
+    cleared += 1;
+  }
+  if (s.noProgressGenerations && typeof s.noProgressGenerations === "object" && budgetKey in s.noProgressGenerations) {
+    delete s.noProgressGenerations[budgetKey];
+    cleared += 1;
+  }
+  if (s.rolloverDeadEnds && typeof s.rolloverDeadEnds === "object" && budgetKey in s.rolloverDeadEnds) {
+    delete s.rolloverDeadEnds[budgetKey];
+    cleared += 1;
+  }
+  if (s.planningProgressDigests && typeof s.planningProgressDigests === "object" && scope in s.planningProgressDigests) {
+    delete s.planningProgressDigests[scope];
+    cleared += 1;
+  }
+  if (clearBackstopFirings(s, scope)) cleared += 1;
+  if (s.lastContinuation && typeof s.lastContinuation === "object"
+    && s.lastContinuation.scope === scope) {
+    delete s.lastContinuation;
+    cleared += 1;
+  }
+  return cleared;
+}
+
 // Drop every planning continuation entry: the continuationBudgetKey(scope)
 // entries from continuationBudgets/noProgressGenerations/rolloverDeadEnds,
 // the bare-scope entries from planningProgressDigests, the
@@ -103,29 +145,7 @@ export function clearPlanningContinuations(s) {
   if (!s || typeof s !== "object") return 0;
   let cleared = 0;
   for (const scope of PLANNING_CONTINUATION_SCOPES) {
-    const budgetKey = continuationBudgetKey(scope);
-    if (s.continuationBudgets && typeof s.continuationBudgets === "object" && budgetKey in s.continuationBudgets) {
-      delete s.continuationBudgets[budgetKey];
-      cleared += 1;
-    }
-    if (s.noProgressGenerations && typeof s.noProgressGenerations === "object" && budgetKey in s.noProgressGenerations) {
-      delete s.noProgressGenerations[budgetKey];
-      cleared += 1;
-    }
-    if (s.rolloverDeadEnds && typeof s.rolloverDeadEnds === "object" && budgetKey in s.rolloverDeadEnds) {
-      delete s.rolloverDeadEnds[budgetKey];
-      cleared += 1;
-    }
-    if (s.planningProgressDigests && typeof s.planningProgressDigests === "object" && scope in s.planningProgressDigests) {
-      delete s.planningProgressDigests[scope];
-      cleared += 1;
-    }
-    if (clearBackstopFirings(s, scope)) cleared += 1;
-  }
-  if (s.lastContinuation && typeof s.lastContinuation === "object"
-    && isPlanningContinuationScope(s.lastContinuation.scope)) {
-    delete s.lastContinuation;
-    cleared += 1;
+    cleared += clearPlanningContinuationScope(s, scope);
   }
   return cleared;
 }

package/scripts/planning-review-decision.mjs

@@ -41,6 +41,9 @@
 const NON_RETRYABLE_ESCALATE_CLASSES = Object.freeze([
   "PATH_UNSUPPORTED",
   "PERMISSION_DENIED",
+  // The CLI is logged out: another reviewer attempt on the same adapter
+  // cannot succeed any more than another path/permission attempt can.
+  "AUTH_REQUIRED",
 ]);
 
 // Functional class that is never intercepted here: the caller runs its

package/scripts/planning-review-wiring.mjs

@@ -141,15 +141,19 @@ function escalate(recorded,{state,saveState,fatal,escalatePrefix,cause}){
   fatal(`${escalatePrefix} failed: ${cause} (${recorded.scope}): ${naming.detail}; human intervention required.`);
 }
 
-// Caller-facing RATE_LIMITED guard (imported by scripts/autopilot.mjs).
-// Returns false when the result is not rate-limited; otherwise escalates at
-// once through the shared helper above and never returns (the injected
-// fatal throws). Forces retryable:false on the recorded-shaped object so the
-// shared naming takes its immediate-escalation step even if the relay marked
-// the failure retryable, and writes zero failure-budget state.
+// Caller-facing immediate-escalation guard (imported by scripts/autopilot.mjs).
+// Returns false when the result is neither RATE_LIMITED nor AUTH_REQUIRED;
+// otherwise escalates at once through the shared helper above and never
+// returns (the injected fatal throws). Both classes are non-retryable and
+// spend zero failure budget: a provider limit lifts later, and a logged-out
+// CLI can only be fixed by the operator. Forces retryable:false on the
+// recorded-shaped object so the shared naming takes its immediate-escalation
+// step even if the relay marked the failure retryable, and writes zero
+// failure-budget state.
 export function escalateIfRateLimited(config,state,taskScope,result,{fatal,saveState,escalatePrefix}={}){
-  if(result?.failure?.class!=="RATE_LIMITED") return false;
-  const failureRecord={...result.failure,class:"RATE_LIMITED",retryable:false};
+  const failureClass=result?.failure?.class;
+  if(failureClass!=="RATE_LIMITED"&&failureClass!=="AUTH_REQUIRED") return false;
+  const failureRecord={...result.failure,class:failureClass,retryable:false};
   const scope=failureBudgetScope(failureRecord,taskScope,result);
   escalate({failure:failureRecord,budget:{allowed:false,budget:null,used:0,limit:0,scope},scope},
     {state,saveState:typeof saveState==="function"?saveState:()=>{},fatal:typeof fatal==="function"?fatal:(m)=>{throw new Error(String(m));},escalatePrefix,cause:`${failureRecord.class}/${failureRecord.domain}`});

package/scripts/relay-guards.mjs

@@ -148,6 +148,82 @@ export function keepEntryAfterEolFilter(entry,eolDirtySet){
   return entry.paths.some(p=>eolDirtySet.has(p));
 }
 
+// Batch bounds for the limited diffs: keep every git invocation's argv well
+// under the OS limit (~128 KB on Windows, more elsewhere) even with very long
+// paths. Both are soft limits; a rename pair may push a batch one path over.
+const SNAPSHOT_DIFF_PATHS_PER_BATCH=200;
+const SNAPSHOT_DIFF_ARG_BYTES_PER_BATCH=30*1024;
+
+function compareSnapshotPaths(a,b){
+  // Git emits changed paths in byte order, not UTF-16 code-unit order.
+  return Buffer.compare(Buffer.from(a,"utf8"),Buffer.from(b,"utf8"));
+}
+
+// Derive the tracked paths whose diff could contribute to the snapshot from
+// `git status`: every entry that is not untracked (`??`) or ignored (`!!`),
+// including both sides of a rename/copy. Root-level `.autopilot/` paths are
+// excluded because the binary diff already excludes them via pathspec.
+// A rename/copy pair must travel in one batch or the pair would degrade into
+// separate delete+add hunks. Git sorts a pair at its NEW path, so the pair is
+// anchored there (see snapshotDiffBatches) while its old path waits.
+function snapshotDiffCandidates(entries){
+  const candidates=new Set();
+  const pairs=[];
+  for(const entry of entries){
+    if(entry.xy==="??"||entry.xy==="!!") continue;
+    if(entry.xy===null||entry.xy===undefined) continue;
+    const included=[];
+    for(const p of entry.paths){
+      if(String(p).startsWith(".autopilot/")) continue;
+      candidates.add(p);
+      included.push(p);
+    }
+    if(entry.fromPath!==null&&entry.fromPath!==undefined&&included.length===2){
+      pairs.push([entry.toPath,entry.fromPath]);
+    }
+  }
+  const pairFromByTo=new Map();
+  const renameSources=new Set();
+  for(const [to,from] of pairs){
+    pairFromByTo.set(to,from);
+    renameSources.add(from);
+  }
+  return {
+    candidatePaths:[...candidates].sort(compareSnapshotPaths),
+    pairFromByTo,
+    renameSources
+  };
+}
+
+function snapshotDiffBatches(sortedPaths,pairFromByTo,renameSources){
+  const batches=[];
+  const assigned=new Set();
+  let i=0;
+  while(i<sortedPaths.length){
+    const batch=[];
+    let bytes=0;
+    const add=(p)=>{
+      if(assigned.has(p)) return;
+      assigned.add(p);
+      batch.push(p);
+      // ":(literal)" prefix plus the separating space.
+      bytes+=Buffer.byteLength(p,"utf8")+11;
+    };
+    while(i<sortedPaths.length&&batch.length<SNAPSHOT_DIFF_PATHS_PER_BATCH&&(batch.length===0||bytes<SNAPSHOT_DIFF_ARG_BYTES_PER_BATCH)){
+      const p=sortedPaths[i++];
+      if(assigned.has(p)) continue;
+      // A rename source is added by its destination's batch, at the position
+      // Git would emit the pair.
+      if(renameSources.has(p)) continue;
+      add(p);
+      const from=pairFromByTo.get(p);
+      if(from!==undefined) add(from);
+    }
+    if(batch.length) batches.push(batch);
+  }
+  return batches;
+}
+
 function eolNormalizedFileHash(file){
   try{
     const buf=fs.readFileSync(file);
@@ -374,11 +450,39 @@ export function gitSnapshot(startCwd){
   // Entries for tracked paths absent from this set are phantoms and are
   // dropped from the fingerprinted status. Untracked/ignored entries (`??`,
   // `!!`) are never in the diff-HEAD set and are always kept.
-  const eolDirtySet=new Set(gitOut(cwd,["-c","core.autocrlf=input","diff","--ignore-cr-at-eol","--name-only","-z","HEAD"]).toString().split("\0").filter(Boolean));
+  //
+  // Status runs FIRST so its tracked entries can bound both diffs to the
+  // paths that actually changed. On a large checkout this turns two ~12 s
+  // full-tree diffs into ~2 s limited diffs while producing byte-identical
+  // output: a path not reported by status cannot contribute to `diff HEAD`.
+  // Batches are sorted in Git's byte order and concatenated in that order so
+  // the fingerprinted binary diff matches the full-tree run exactly.
   const rawStatus=gitOut(cwd,["-c","core.autocrlf=input","status","--porcelain=v1","-z","--untracked-files=all"]);
   const statusText=rawStatus.toString("utf8");
+  const statusEntries=parsePorcelainV1ZEntries(statusText);
+  const {candidatePaths,pairFromByTo,renameSources}=snapshotDiffCandidates(statusEntries);
+  const eolDirtySet=new Set();
+  const diffParts=[];
+  for(const batch of snapshotDiffBatches(candidatePaths,pairFromByTo,renameSources)){
+    // Literal pathspecs: a tracked filename containing glob metacharacters
+    // must not pull an unrelated path into this batch (which would duplicate
+    // that path's diff across batches).
+    const pathspecs=batch.map(p=>`:(literal)${p}`);
+    for(const rel of gitOut(cwd,["-c","core.autocrlf=input","diff","--ignore-cr-at-eol","--name-only","-z","HEAD","--",...pathspecs]).toString().split("\0")){
+      if(rel) eolDirtySet.add(rel);
+    }
+    diffParts.push(gitOut(cwd,["-c","core.autocrlf=input","diff","--ignore-cr-at-eol","--no-ext-diff","--binary","HEAD","--",...pathspecs,":(exclude).autopilot/**"]));
+  }
+  // Preserve gitOut's historical type: Buffer.alloc(0) when the full-tree
+  // command would have produced no bytes, otherwise its UTF-8 string. Parts
+  // are already decoded per batch; concatenating decoded file diffs is
+  // identical to decoding the same full output (no multi-byte sequence spans
+  // two files).
+  const diff=diffParts.some(part=>part.length>0)
+    ?diffParts.map(part=>part.toString()).join("")
+    :Buffer.alloc(0);
   const statusKept=[];
-  for(const entry of parsePorcelainV1ZEntries(statusText)){
+  for(const entry of statusEntries){
     if(entry.paths.some(p=>String(p).includes(".autopilot/"))) continue;
     if(entry.xy===null){
       // Ungrouped continuation token (should not happen outside renames
@@ -392,11 +496,15 @@ export function gitSnapshot(startCwd){
     if(entry.fromPath!==null) statusKept.push(entry.fromPath);
   }
   const statusFiltered=Buffer.from(statusKept.join("\0")+(statusKept.length?"\0":""));
-  const diff=gitOut(cwd,["-c","core.autocrlf=input","diff","--ignore-cr-at-eol","--no-ext-diff","--binary","HEAD","--", ".", ":(exclude).autopilot/**"]);
 
   const fileSet=new Set([...eolDirtySet].filter(rel=>!rel.startsWith(".autopilot/")));
-  for(const rel of gitOut(cwd,["ls-files","--others","-z","--exclude-standard"]).toString().split("\0").filter(Boolean)){
-    if(!rel.startsWith(".autopilot/"))fileSet.add(rel);
+  // Untracked files come from the status already parsed above (`??` entries
+  // under --untracked-files=all): byte-identical to `git ls-files --others
+  // --exclude-standard` (plain, nested, spaces/unicode/newline names, nested
+  // git repos reported as `sub/`, empty dirs omitted by both) without a
+  // second full-tree walk.
+  for(const entry of statusEntries){
+    if(entry.xy==="??"&&!entry.toPath.startsWith(".autopilot/")) fileSet.add(entry.toPath);
   }
   // Ignored files: --directory reports a wholly-ignored dir as ONE entry
   // (e.g. `apps/web/.next/`) without descending, so git never walks
@@ -448,13 +556,22 @@ export function gitSnapshot(startCwd){
 
 // Snapshot scope (backlog #9 / TASK-31). Single place defining which
 // wholly-ignored directory segments are EXCLUDED from the fingerprint.
-// Framework build caches only: node_modules, .next, .turbo, .nuxt,
-// .svelte-kit, .parcel-cache, .vite. Deliberately NOT excluded: dist/,
-// build/, coverage/ — they are build outputs a read-only stage must not
-// change, so a write there must still trip read_only_violation.
+// Framework build caches (node_modules, .next, .turbo, .nuxt, .svelte-kit,
+// .parcel-cache, .vite) and build/coverage OUTPUT dirs (dist, build,
+// coverage, .nyc_output, out, .cache, __pycache__, .pytest_cache, target) are
+// never expanded or hashed: on a real repo they were hundreds of files / MBs
+// per snapshot. Playwright/browser artifact dirs (.playwright-mcp,
+// playwright-report, test-results) are deliberately NOT listed: a verifier's
+// screenshots/traces may hold sensitive data and must stay visible to
+// snapshot diffing (test-security-hardening.mjs). Applied to
+// IGNORED entries only — a TRACKED file under dist/ etc. is still covered by
+// status/diff. Agent-config dirs (.opencode, .claude, ...) are deliberately
+// NOT listed: they stay fingerprinted to catch writes by read-only roles.
 export const SNAPSHOT_EXCLUDED_DIR_SEGMENTS = Object.freeze([
   "node_modules", ".next", ".turbo", ".nuxt", ".svelte-kit",
-  ".parcel-cache", ".vite"
+  ".parcel-cache", ".vite",
+  "dist", "build", "coverage", ".nyc_output", "out", ".cache", "__pycache__", ".pytest_cache",
+  "target"
 ]);
 
 function snapshotPathExcluded(rel){
@@ -1373,9 +1490,14 @@ export function createGitMutationGuard(runDir,repositoryRoot=null){
   // structurally exempted (see isSafeSymbolicRefQuery in the generated
   // wrapper). symbolic-ref STAYS in BLOCKED_SUBCOMMANDS — the exemption is a
   // narrow allow-after-parse, never a reclassification.
+  // Backlog #24: a guard never logs into another guard's log. The shim writes
+  // only to the blocked.log beside itself (resolved at run time, so it holds when
+  // the guard dir is mounted elsewhere); an inherited AUTOPILOT_GIT_GUARD_LOG from
+  // an outer session is ignored. The one exception is the null device, which
+  // explicitWrapperSource() sets on purpose to drop the orchestrator's own entries.
   const wrapper=path.join(guardDir,"git-guard.mjs");
   const blockedList=JSON.stringify([...BLOCKED_SUBCOMMANDS]);
-  fs.writeFileSync(wrapper,`import fs from "node:fs"; import path from "node:path"; import {spawnSync} from "node:child_process"; import crypto from "node:crypto";\nconst SCOPE_FILE=new URL("./git-scope.conf",import.meta.url);const REAL_GIT=${JSON.stringify(realGit)};const GUARD_ENV_ALLOWLIST=${JSON.stringify(GUARD_ENV_ALLOWLIST)};if(process.argv[2]==="--autopilot-hook-scope-check"){let allow=false;try{allow=classifyGuardTarget(process.cwd(),SCOPE_FILE,process.env,REAL_GIT)==="outside";}catch{allow=false;}process.exit(allow?0:1);}\nif(process.argv[2]===\"--autopilot-hook-target\"){let t=\"unproven\";try{t=classifyGuardTarget(process.cwd(),SCOPE_FILE,process.env,REAL_GIT);}catch{}process.stdout.write(t);process.exit(0);}\nconst args=process.argv.slice(2);\nconst blocked=new Set(${blockedList});\nconst GLOBAL_VALUE_FLAGS=new Set(["-C","-c","--git-dir","--work-tree","--namespace","--super-prefix","--config-env"]);\nconst GLOBAL_VALUE_PREFIXES=[\"--git-dir=\",\"--work-tree=\",\"--namespace=\",\"--super-prefix=\",\"--config-env=\"];\nconst SAFE_SYMBOLIC_REF_OPTIONS=new Set([\"--quiet\",\"-q\",\"--short\",\"--no-recurse\"]);\nfunction isSafeSymbolicRefQuery(argumentList,commandIndex){\nlet operand=null;\nfor(let i=commandIndex+1;i<argumentList.length;i+=1){\nconst token=argumentList[i];\nif(token.startsWith(\"-\")){if(!SAFE_SYMBOLIC_REF_OPTIONS.has(token))return false;continue;}\nif(operand!==null)return false;\noperand=token;\n}\nreturn operand===\"HEAD\"||(typeof operand===\"string\"&&operand.startsWith(\"refs/\")&&operand.length>5);\n}\nconst MUTATING_BRANCH=new Set(["-d","-D","-m","-M","-c","-C","-f","--force","--delete","--move","--copy","--set-upstream-to","-u","--unset-upstream"]);\nconst READONLY_BRANCH_QUERY=new Set(["--list","-l","--show-current","--contains","--no-contains","--merged","--no-merged","--points-at","--format","-v","--verbose","-a","--all","-r","--remotes","--column","--sort"]);\nlet subcommandIndex=-1;\nfor(let index=0;index<args.length;index+=1){\n  const argument=args[index];\n  if(GLOBAL_VALUE_FLAGS.has(argument)){index+=1;continue;}\n  if(GLOBAL_VALUE_PREFIXES.some(prefix=>argument.startsWith(prefix)))continue;\n  if(argument.startsWith("-"))continue;\n  subcommandIndex=index;\n  break;\n}\nconst subcommand=subcommandIndex>=0?args[subcommandIndex]:null;\nlet readOnlyBranch=false;\nif(subcommand==="branch"){\n  const rest=args.slice(subcommandIndex+1);\n  readOnlyBranch=rest.some(a=>READONLY_BRANCH_QUERY.has(a.split("=")[0]))||(rest.every(a=>a.startsWith("-"))&&rest.every(a=>!MUTATING_BRANCH.has(a.split("=")[0])));\n}\nconst safeSymbolicRefQuery=subcommand===\"symbolic-ref\"&&subcommandIndex>=0&&isSafeSymbolicRefQuery(args,subcommandIndex);\nconst guardBlocks=!!(subcommand && blocked.has(subcommand) && !(subcommand===\"branch\"&&readOnlyBranch) && !safeSymbolicRefQuery);\nlet allowOutsideProtected=false;\nlet blockTarget="unproven";\nconst sanitizedArgs=stripOverridingConfigArgs(args,subcommandIndex);\nlet discardForm=null;\ntry{discardForm=classifyWorktreeDiscarding(args,subcommandIndex,function(operand){try{const allowNames={};for(let k=0;k<GUARD_ENV_ALLOWLIST.length;k+=1){allowNames[String(GUARD_ENV_ALLOWLIST[k]).toUpperCase()]=true;}const probeEnv={};const srcEnv=process.env||{};for(const name of Object.keys(srcEnv)){if(allowNames[String(name).toUpperCase()]){probeEnv[name]=srcEnv[name];}}const r=spawnSync(REAL_GIT,["rev-parse","--verify","--quiet",String(operand)+"^{commit}"],{stdio:["ignore","pipe","pipe"],timeout:5000,env:probeEnv,shell:false});return r.status===0;}catch(e){return false;}});}catch(e){discardForm=null;}\nif((guardBlocks||discardForm)&&SCOPE_FILE){\n  let probeCwd=process.cwd();\n  let gitDirOverride=null;\n  let workTreeOverride=null;\n  for(let index=0;index<args.length;index+=1){\n    const argument=args[index];\n    if(argument==="-C"){const target=args[index+1];if(typeof target==="string"&&target)probeCwd=path.resolve(probeCwd,target);index+=1;continue;}\n    if(argument==="--git-dir"){gitDirOverride=args[index+1];index+=1;continue;}\n    if(argument.startsWith("--git-dir=")){gitDirOverride=argument.slice("--git-dir=".length);continue;}\n    if(argument==="--work-tree"){workTreeOverride=args[index+1];index+=1;continue;}\n    if(argument.startsWith("--work-tree=")){workTreeOverride=argument.slice("--work-tree=".length);continue;}\n  }\n  const probeEnv={...process.env};\n  if(typeof gitDirOverride==="string"&&gitDirOverride)probeEnv.GIT_DIR=gitDirOverride;\n  if(typeof workTreeOverride==="string"&&workTreeOverride)probeEnv.GIT_WORK_TREE=workTreeOverride;\n  try{const wrappedClassification=classifyGuardTarget(probeCwd,SCOPE_FILE,probeEnv,REAL_GIT);allowOutsideProtected=wrappedClassification==="outside";blockTarget=allowOutsideProtected?"unproven":wrappedClassification;}catch{allowOutsideProtected=false;blockTarget="unproven";}\n}\nlet snapshotAllowsRestore=false;\ntry{if(discardForm&&!guardBlocks&&!allowOutsideProtected){snapshotAllowsRestore=guardBeforeSnapshotAllows(args,subcommandIndex,discardForm,SCOPE_FILE.href,REAL_GIT,GUARD_ENV_ALLOWLIST)===true;}}catch{snapshotAllowsRestore=false;}\nif((guardBlocks||discardForm)&&!allowOutsideProtected&&!snapshotAllowsRestore){\n  fs.appendFileSync(process.env.AUTOPILOT_GIT_GUARD_LOG||"${logFile.replace(/\\/g,"\\\\")}",JSON.stringify({time:new Date().toISOString(),args:args,layer:"path-shim",subcommand:subcommand,reason:discardForm?"worktree-restore":"history-ref-mutation",form:discardForm||subcommand,target:blockTarget})+"\\n");\n  console.error("AUTOPILOT GIT GUARD: '"+subcommand+"' is forbidden ("+(discardForm?"worktree restore":"history/ref mutation")+").");\n  process.exit(97);\n}\nconst env={...process.env};\nconst result=spawnSync(REAL_GIT,sanitizedArgs,{stdio:"inherit",shell:false,env});\nif(result.error){console.error(result.error.message);process.exit(127);}\nprocess.exit(result.status??1);\n`);
+  fs.writeFileSync(wrapper,`import fs from "node:fs"; import path from "node:path"; import {spawnSync} from "node:child_process"; import crypto from "node:crypto"; import {fileURLToPath} from "node:url";\nconst SCOPE_FILE=new URL("./git-scope.conf",import.meta.url);const GUARD_LOG=(()=>{const inherited=process.env.AUTOPILOT_GIT_GUARD_LOG;if(typeof inherited===\"string\"&&(process.platform===\"win32\"?inherited.toUpperCase()===\"NUL\":inherited===\"/dev/null\"))return inherited;return fileURLToPath(new URL(\"./blocked.log\",import.meta.url));})();const REAL_GIT=${JSON.stringify(realGit)};const GUARD_ENV_ALLOWLIST=${JSON.stringify(GUARD_ENV_ALLOWLIST)};if(process.argv[2]==="--autopilot-hook-scope-check"){let allow=false;try{allow=classifyGuardTarget(process.cwd(),SCOPE_FILE,process.env,REAL_GIT)==="outside";}catch{allow=false;}process.exit(allow?0:1);}\nif(process.argv[2]===\"--autopilot-hook-target\"){let t=\"unproven\";try{t=classifyGuardTarget(process.cwd(),SCOPE_FILE,process.env,REAL_GIT);}catch{}process.stdout.write(t);process.exit(0);}\nconst args=process.argv.slice(2);\nconst blocked=new Set(${blockedList});\nconst GLOBAL_VALUE_FLAGS=new Set(["-C","-c","--git-dir","--work-tree","--namespace","--super-prefix","--config-env"]);\nconst GLOBAL_VALUE_PREFIXES=[\"--git-dir=\",\"--work-tree=\",\"--namespace=\",\"--super-prefix=\",\"--config-env=\"];\nconst SAFE_SYMBOLIC_REF_OPTIONS=new Set([\"--quiet\",\"-q\",\"--short\",\"--no-recurse\"]);\nfunction isSafeSymbolicRefQuery(argumentList,commandIndex){\nlet operand=null;\nfor(let i=commandIndex+1;i<argumentList.length;i+=1){\nconst token=argumentList[i];\nif(token.startsWith(\"-\")){if(!SAFE_SYMBOLIC_REF_OPTIONS.has(token))return false;continue;}\nif(operand!==null)return false;\noperand=token;\n}\nreturn operand===\"HEAD\"||(typeof operand===\"string\"&&operand.startsWith(\"refs/\")&&operand.length>5);\n}\nconst MUTATING_BRANCH=new Set(["-d","-D","-m","-M","-c","-C","-f","--force","--delete","--move","--copy","--set-upstream-to","-u","--unset-upstream"]);\nconst READONLY_BRANCH_QUERY=new Set(["--list","-l","--show-current","--contains","--no-contains","--merged","--no-merged","--points-at","--format","-v","--verbose","-a","--all","-r","--remotes","--column","--sort"]);\nlet subcommandIndex=-1;\nfor(let index=0;index<args.length;index+=1){\n  const argument=args[index];\n  if(GLOBAL_VALUE_FLAGS.has(argument)){index+=1;continue;}\n  if(GLOBAL_VALUE_PREFIXES.some(prefix=>argument.startsWith(prefix)))continue;\n  if(argument.startsWith("-"))continue;\n  subcommandIndex=index;\n  break;\n}\nconst subcommand=subcommandIndex>=0?args[subcommandIndex]:null;\nlet readOnlyBranch=false;\nif(subcommand==="branch"){\n  const rest=args.slice(subcommandIndex+1);\n  readOnlyBranch=rest.some(a=>READONLY_BRANCH_QUERY.has(a.split("=")[0]))||(rest.every(a=>a.startsWith("-"))&&rest.every(a=>!MUTATING_BRANCH.has(a.split("=")[0])));\n}\nconst safeSymbolicRefQuery=subcommand===\"symbolic-ref\"&&subcommandIndex>=0&&isSafeSymbolicRefQuery(args,subcommandIndex);\nconst guardBlocks=!!(subcommand && blocked.has(subcommand) && !(subcommand===\"branch\"&&readOnlyBranch) && !safeSymbolicRefQuery);\nlet allowOutsideProtected=false;\nlet blockTarget="unproven";\nconst sanitizedArgs=stripOverridingConfigArgs(args,subcommandIndex);\nlet discardForm=null;\ntry{discardForm=classifyWorktreeDiscarding(args,subcommandIndex,function(operand){try{const allowNames={};for(let k=0;k<GUARD_ENV_ALLOWLIST.length;k+=1){allowNames[String(GUARD_ENV_ALLOWLIST[k]).toUpperCase()]=true;}const probeEnv={};const srcEnv=process.env||{};for(const name of Object.keys(srcEnv)){if(allowNames[String(name).toUpperCase()]){probeEnv[name]=srcEnv[name];}}const r=spawnSync(REAL_GIT,["rev-parse","--verify","--quiet",String(operand)+"^{commit}"],{stdio:["ignore","pipe","pipe"],timeout:5000,env:probeEnv,shell:false});return r.status===0;}catch(e){return false;}});}catch(e){discardForm=null;}\nif((guardBlocks||discardForm)&&SCOPE_FILE){\n  let probeCwd=process.cwd();\n  let gitDirOverride=null;\n  let workTreeOverride=null;\n  for(let index=0;index<args.length;index+=1){\n    const argument=args[index];\n    if(argument==="-C"){const target=args[index+1];if(typeof target==="string"&&target)probeCwd=path.resolve(probeCwd,target);index+=1;continue;}\n    if(argument==="--git-dir"){gitDirOverride=args[index+1];index+=1;continue;}\n    if(argument.startsWith("--git-dir=")){gitDirOverride=argument.slice("--git-dir=".length);continue;}\n    if(argument==="--work-tree"){workTreeOverride=args[index+1];index+=1;continue;}\n    if(argument.startsWith("--work-tree=")){workTreeOverride=argument.slice("--work-tree=".length);continue;}\n  }\n  const probeEnv={...process.env};\n  if(typeof gitDirOverride==="string"&&gitDirOverride)probeEnv.GIT_DIR=gitDirOverride;\n  if(typeof workTreeOverride==="string"&&workTreeOverride)probeEnv.GIT_WORK_TREE=workTreeOverride;\n  try{const wrappedClassification=classifyGuardTarget(probeCwd,SCOPE_FILE,probeEnv,REAL_GIT);allowOutsideProtected=wrappedClassification==="outside";blockTarget=allowOutsideProtected?"unproven":wrappedClassification;}catch{allowOutsideProtected=false;blockTarget="unproven";}\n}\nlet snapshotAllowsRestore=false;\ntry{if(discardForm&&!guardBlocks&&!allowOutsideProtected){snapshotAllowsRestore=guardBeforeSnapshotAllows(args,subcommandIndex,discardForm,SCOPE_FILE.href,REAL_GIT,GUARD_ENV_ALLOWLIST)===true;}}catch{snapshotAllowsRestore=false;}\nif((guardBlocks||discardForm)&&!allowOutsideProtected&&!snapshotAllowsRestore){\n  fs.appendFileSync(GUARD_LOG,JSON.stringify({time:new Date().toISOString(),args:args,layer:"path-shim",subcommand:subcommand,reason:discardForm?"worktree-restore":"history-ref-mutation",form:discardForm||subcommand,target:blockTarget})+"\\n");\n  console.error("AUTOPILOT GIT GUARD: '"+subcommand+"' is forbidden ("+(discardForm?"worktree restore":"history/ref mutation")+").");\n  process.exit(97);\n}\nconst env={...process.env};\nconst result=spawnSync(REAL_GIT,sanitizedArgs,{stdio:"inherit",shell:false,env});\nif(result.error){console.error(result.error.message);process.exit(127);}\nprocess.exit(result.status??1);\n`);
   // TASK 6: embed the Layer-1 scoping helpers. Function declarations are
   // hoisted, so the wrapper body above can call them; all are closure-free by
   // design. The GUARD_ENV_ALLOWLIST they consult is emitted at the TOP of the

package/scripts/review-canary.mjs

@@ -356,7 +356,10 @@ function runSlicedBriefProbe(repo, fileDiff) {
   //    /workspace/repository envelope, so the review never happens and the
   //    probe silently produces no AUTOPILOT_REVIEW sentinel (observed live:
   //    "permission requested: external_directory (.../src/*); auto-rejecting").
-  //  - claude: its own --permission-mode plan.
+  //  - claude: default mode + an explicit read-only allow list (same shape
+  //    the production read-only roles launch with after backlog #2). No
+  //    Write/Edit rule is granted: the canary probe has no scratch hand-off
+  //    note to keep, so the probe stays read-only without plan mode.
   const PROBE_OPENCODE_AGENT = "review_canary_probe";
   const opencodeProbeConfig = JSON.stringify({
     "$schema": "https://opencode.ai/config.json",
@@ -369,7 +372,7 @@ function runSlicedBriefProbe(repo, fileDiff) {
   });
   const baseArgs = REVIEWER_ADAPTER === "opencode"
     ? ["run", "--format", "json", "--agent", PROBE_OPENCODE_AGENT]
-    : ["-p", "--output-format", "stream-json", "--input-format", "text", "--verbose", "--permission-mode", "plan"];
+    : ["-p", "--output-format", "stream-json", "--input-format", "text", "--verbose", "--allowedTools", "Read", "Glob", "Grep", "Bash", "--disallowedTools", "Monitor", "TaskStop", "--settings", "{\"env\":{\"CLAUDE_CODE_DISABLE_BACKGROUND_TASKS\":\"1\"}}", "--permission-mode", "default"];
 
   // Every driver delivers the prompt on stdin (no driver declares a
   // transportPrompt prompt-as-CLI-argument path), so the prompt always goes