@seanyao/roll 4.719.3 → 4.721.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## Unreleased
 
+## v4.721.1 — 2026-07-21
+
+### 稳定性
+- loop 看门狗的"进展"判定从 stdout 改为 git 状态（新 commit / 工作区文件变动）：输出缓冲型 agent 写文件时不再被 15 分钟无进展误杀；新增 `no-state-change` 杀因——默认 25 分钟无 commit 且无文件变动即终止（即使 stdout 仍在输出），原地打转的 cycle 不再烧满 45 分钟墙钟；阈值可用 `ROLL_CYCLE_NO_STATE_CHANGE_SEC` 覆盖（FIX-1477）[loop]
+- attest 闸的"无 AC 块豁免"提前到渲染之前评估：无 AC 块的卡不再因渲染失败或空壳报告被硬拦，直接合法放行（FIX-1476）[loop]
+
+## v4.720.1 — 2026-07-20
+
+### 稳定性
+- `roll worktree cleanup` 现在能认出压缩合并的交付，未交付分支仍会保留（FIX-1471）[loop]
+- 暂停后可用 `roll loop go --cards` 只跑指定卡，其他启动方式继续保持暂停（FIX-1472）[loop]
+
 ## v4.719.3 — 2026-07-19
 
 ### 稳定性

package/dist/roll.mjs

@@ -14642,15 +14642,20 @@ function timeoutTeardownCommands(ctx) {
 function cycleTimeoutVerdict(input) {
   const wall = input.wallLimitSec ?? CYCLE_WALL_TIMEOUT_SEC;
   const idle = input.noProgressLimitSec ?? CYCLE_NO_PROGRESS_SEC;
+  const stateIdle = input.noStateChangeLimitSec ?? CYCLE_NO_STATE_CHANGE_SEC;
   if (wall > 0 && input.elapsedSec >= wall) {
     return { timedOut: true, reason: "wall", elapsedSec: input.elapsedSec, idleSec: input.idleSec };
   }
   if (idle > 0 && input.idleSec >= idle) {
     return { timedOut: true, reason: "no-progress", elapsedSec: input.elapsedSec, idleSec: input.idleSec };
   }
+  if (input.stateIdleSec !== void 0 && stateIdle > 0 && input.stateIdleSec >= stateIdle) {
+    return { timedOut: true, reason: "no-state-change", elapsedSec: input.elapsedSec, idleSec: input.idleSec };
+  }
   const wallRemain = wall > 0 ? wall - input.elapsedSec : Number.POSITIVE_INFINITY;
   const idleRemain = idle > 0 ? idle - input.idleSec : Number.POSITIVE_INFINITY;
-  return { timedOut: false, remainingSec: Math.min(wallRemain, idleRemain) };
+  const stateRemain = input.stateIdleSec !== void 0 && stateIdle > 0 ? stateIdle - input.stateIdleSec : Number.POSITIVE_INFINITY;
+  return { timedOut: false, remainingSec: Math.min(wallRemain, idleRemain, stateRemain) };
 }
 function stallVerdict(input) {
   const threshold = input.stallThresholdSec ?? CYCLE_STALL_THRESHOLD_SEC;
@@ -15141,7 +15146,7 @@ function adversarialDegradedCmd(cycleId, storyId, cause, from = "adversarial") {
 function initialCycleState(ctx) {
   return { phase: "pick", ctx, attempt: 0, done: false };
 }
-var CYCLE_TIMEOUT_SEC, WATCHDOG_KILL_GRACE_SEC, CYCLE_WALL_TIMEOUT_SEC, CYCLE_NO_PROGRESS_SEC, CYCLE_STALL_THRESHOLD_SEC, STALL_STARTUP_GRACE_SEC, MAX_AGENT_ATTEMPTS, RETRY_BASE_BACKOFF_SEC, EVENT_VALID_PHASES;
+var CYCLE_TIMEOUT_SEC, WATCHDOG_KILL_GRACE_SEC, CYCLE_WALL_TIMEOUT_SEC, CYCLE_NO_PROGRESS_SEC, CYCLE_NO_STATE_CHANGE_SEC, CYCLE_STALL_THRESHOLD_SEC, STALL_STARTUP_GRACE_SEC, MAX_AGENT_ATTEMPTS, RETRY_BASE_BACKOFF_SEC, EVENT_VALID_PHASES;
 var init_orchestrator = __esm({
   "packages/core/dist/loop/orchestrator.js"() {
     "use strict";
@@ -15153,6 +15158,7 @@ var init_orchestrator = __esm({
     WATCHDOG_KILL_GRACE_SEC = 5;
     CYCLE_WALL_TIMEOUT_SEC = 2700;
     CYCLE_NO_PROGRESS_SEC = 900;
+    CYCLE_NO_STATE_CHANGE_SEC = 1500;
     CYCLE_STALL_THRESHOLD_SEC = 600;
     STALL_STARTUP_GRACE_SEC = 120;
     MAX_AGENT_ATTEMPTS = 3;
@@ -247550,6 +247556,7 @@ Loop \u5DF2\u5904\u4E8E\u6682\u505C
 Loop \u5DF2\u6682\u505C \u2014 \u540E\u7EED\u6392\u7A0B\u5468\u671F\u5C06\u8DF3\u8FC7
 `);
   process.stdout.write("mode: guided \u2014 scheduler will not start long-running Story execution until `roll loop resume`\n");
+  process.stdout.write("  supervisor one-shot: `roll loop go --cards <ids> --max-cycles 1` runs exactly those cards while staying paused (no autonomous scheduling).\n");
   return 0;
 }
 async function loopResumeCommand(_args, deps = realDeps()) {
@@ -251253,6 +251260,11 @@ function runAttestGate(worktreeCwd, storyId, cycleId, mode, sinceSec, sinks, sco
       sinks.event({ cycleId, verdict: "skipped", reasons: reasons2 });
       return { verdict: "skipped", mode, reasons: reasons2, blocked: blocked4 };
     }
+    if (storyHasAcBlock(specRepoCwd, storyId) === false) {
+      const reasons2 = ["story has no AC block; acceptance report not required"];
+      sinks.event({ cycleId, verdict: "produced", reasons: reasons2 });
+      return { verdict: "produced", mode, reasons: reasons2, blocked: false };
+    }
     if (renderExitCode !== 0) {
       const reasons2 = [`attest render failed for ${storyId} (exit ${renderExitCode})`];
       const blocked4 = mode === "hard";
@@ -251260,11 +251272,6 @@ function runAttestGate(worktreeCwd, storyId, cycleId, mode, sinceSec, sinks, sco
       sinks.event({ cycleId, verdict: "skipped", reasons: reasons2 });
       return { verdict: "skipped", mode, reasons: reasons2, blocked: blocked4 };
     }
-    if (storyHasAcBlock(specRepoCwd, storyId) === false) {
-      const reasons2 = ["story has no AC block; acceptance report not required"];
-      sinks.event({ cycleId, verdict: "produced", reasons: reasons2 });
-      return { verdict: "produced", mode, reasons: reasons2, blocked: false };
-    }
     const diagnostics = violatesMustDeclareSurface(specRepoCwd, storyId) ? [MUST_DECLARE_FAIL_REASON] : [];
     const redAcs = redAcFailures(worktreeCwd, storyId, scoreRepoCwd);
     if (redAcs.length > 0) {
@@ -264497,6 +264504,7 @@ import { createInterface as createInterface3 } from "node:readline";
 // packages/cli/dist/lib/goal-progress.js
 init_dist();
 var GOAL_ALLOWED_CARDS_ENV = "ROLL_LOOP_GO_ALLOWED_CARDS";
+var GOAL_GUIDED_ENV = "ROLL_LOOP_GO_GUIDED";
 var DELIVERY_STATUSES = /* @__PURE__ */ new Set(["built", "published", "done", "merged"]);
 var DELIVERY_OUTCOMES = /* @__PURE__ */ new Set(["published_pending_merge", "delivered"]);
 function parseAllowedCardsEnv(env = process.env) {
@@ -264505,6 +264513,11 @@ function parseAllowedCardsEnv(env = process.env) {
   const raw = env[GOAL_ALLOWED_CARDS_ENV] ?? "";
   return new Set(raw.split(",").map((s) => s.trim()).filter((s) => s !== ""));
 }
+function isGuidedRunOnce(allowed2, env = process.env) {
+  if ((env[GOAL_GUIDED_ENV] ?? "").trim() !== "1")
+    return false;
+  return allowed2 !== void 0 && allowed2.size > 0;
+}
 var OUT_OF_SCOPE_STATUS = "\u{1F6AB} Hold (outside goal scope)";
 function scopeBacklogForAllowedCards(items, allowed2) {
   if (allowed2 === void 0)
@@ -265428,6 +265441,7 @@ function parseOptions(args) {
   let noTmux = false;
   let attach = false;
   let scopeSpecified = false;
+  let cardsFlagSpecified = false;
   let reviewMode = "auto";
   let reviewModeSpecified = false;
   for (let i = 0; i < args.length; i += 1) {
@@ -265497,11 +265511,13 @@ function parseOptions(args) {
     }
     if (arg === "--cards") {
       cards.push(...parseCards(args[i + 1]));
+      cardsFlagSpecified = true;
       i += 1;
       continue;
     }
     if (arg.startsWith("--cards=")) {
       cards.push(...parseCards(arg.slice("--cards=".length)));
+      cardsFlagSpecified = true;
       continue;
     }
     if (!arg.startsWith("-"))
@@ -265517,6 +265533,7 @@ function parseOptions(args) {
     attach,
     scope,
     scopeSpecified,
+    cardsFlagSpecified,
     reviewMode,
     reviewModeSpecified,
     ...maxCycles !== void 0 ? { maxCycles } : {},
@@ -265526,6 +265543,9 @@ function parseOptions(args) {
 function hasHelpArg2(args) {
   return args.includes("--help") || args.includes("-h");
 }
+function isGuidedRun(opts) {
+  return opts.cardsFlagSpecified && opts.scopeSpecified && opts.scope.kind === "cards" && opts.scope.cards.length > 0;
+}
 function loopGoHelp() {
   return [
     "Usage: roll loop go [--epic <name>|--cards <ids>|--all] [--for <duration>] [--max-cycles <n>] [--review <auto|hetero|self|off>] [--attach] [--no-tmux]",
@@ -265550,6 +265570,12 @@ function loopGoHelp() {
     "  The startup banner shows the EFFECTIVE scope; an inherited scope is flagged so a flagless go can never silently narrow. Pass --all to reset to the full backlog.",
     "  \u542F\u52A8\u6A2A\u5E45\u663E\u793A\u751F\u6548\u7684 scope\uFF1B\u6CBF\u7528\u7684 scope \u4F1A\u88AB\u6807\u6CE8\uFF0Cflagless go \u7EDD\u4E0D\u9759\u9ED8\u6536\u7A84\u3002\u7528 --all \u91CD\u7F6E\u56DE\u5168\u91CF\u3002",
     "",
+    "Guided one-shot while paused (FIX-1472):",
+    "  An explicit `roll loop go --cards X` runs the named card(s) even while `roll loop pause` is in effect \u2014 it is a supervisor action, not autonomous scheduling. It installs no scheduler and picks no other card; bound it with --max-cycles.",
+    "  \u663E\u5F0F\u7684 `roll loop go --cards X` \u5373\u4F7F\u5728 `roll loop pause` \u751F\u6548\u65F6\u4E5F\u4F1A\u6267\u884C\u6307\u5B9A\u5361\u2014\u2014\u8FD9\u662F Supervisor \u624B\u52A8\u52A8\u4F5C\uFF0C\u4E0D\u662F\u81EA\u4E3B\u6392\u7A0B\u3002\u5B83\u4E0D\u5B89\u88C5\u6392\u7A0B\u3001\u4E0D\u9009\u522B\u7684\u5361\uFF1B\u7528 --max-cycles \u9650\u5B9A\u6B21\u6570\u3002",
+    "  Pause still stops autonomous scheduling; only an explicitly-named --cards scope bypasses it (a flagless/inherited/--all/--epic go keeps honoring the pause).",
+    "  pause \u4ECD\u7136\u505C\u6B62\u81EA\u4E3B\u6392\u7A0B\uFF1B\u53EA\u6709\u672C\u6B21\u663E\u5F0F\u6307\u5B9A\u7684 --cards \u8303\u56F4\u624D\u4F1A\u7ED5\u8FC7\uFF08flagless/\u6CBF\u7528/--all/--epic \u7684 go \u4ECD\u9075\u5B88\u6682\u505C\uFF09\u3002",
+    "",
     "Progress guardrails (the loop stops on NO PROGRESS, not on cost):",
     "  productivity floor  A cycle whose agent EXECUTED but produced 0 commits and no delivery is a `gave_up` terminal \u2014 alerted on the first occurrence (no streak).",
     "  dead-loop breaker   A card is skipped after consecutive no-progress cycles; the whole goal STOPS after K consecutive no-progress cycles (a loud ALERT) \u2014 an unmergeable card can never spin forever.",
@@ -265673,6 +265699,20 @@ function followGoLiveFeed(projectPath3, rollBin4) {
     watch.on("error", finish);
   });
 }
+function buildRunOnceChildEnv(input, base = process.env) {
+  return {
+    ...base,
+    ROLL_LOOP_GO_CHILD: "1",
+    // FIX-1022: unattended go-driver child must never trigger the macOS
+    // screencapture TCC prompt (isTTY is unreliable under PTY wrapping).
+    ROLL_NO_SCREENCAP: base["ROLL_NO_SCREENCAP"] ?? "1",
+    ...input.allowedCards !== void 0 ? { [GOAL_ALLOWED_CARDS_ENV]: input.allowedCards.join(",") } : {},
+    // FIX-1472: guided is set on EVERY call (never conditionally spread) so an
+    // inherited ambient "1" cannot survive into an unguided child. Fail closed
+    // to "0" — isGuidedRunOnce treats anything but "1" as not guided.
+    [GOAL_GUIDED_ENV]: input.guided === true ? "1" : "0"
+  };
+}
 function realRunOnce(input) {
   const bin = rollBin();
   const cmd = bin.endsWith(".js") || bin.endsWith(".mjs") ? process.execPath : bin;
@@ -265681,14 +265721,7 @@ function realRunOnce(input) {
     const child = spawn8(cmd, args, {
       cwd: input.projectPath,
       detached: true,
-      env: {
-        ...process.env,
-        ROLL_LOOP_GO_CHILD: "1",
-        // FIX-1022: unattended go-driver child must never trigger the macOS
-        // screencapture TCC prompt (isTTY is unreliable under PTY wrapping).
-        ROLL_NO_SCREENCAP: process.env["ROLL_NO_SCREENCAP"] ?? "1",
-        ...input.allowedCards !== void 0 ? { [GOAL_ALLOWED_CARDS_ENV]: input.allowedCards.join(",") } : {}
-      },
+      env: buildRunOnceChildEnv(input),
       stdio: "inherit"
     });
     child.on("exit", (code) => resolve17(code ?? 1));
@@ -266587,11 +266620,12 @@ async function runGoWorker(id, opts, deps) {
     progress = progressFromGoal(goal);
     initialUsage = runSummaryFromGoal(goal);
     const deadlineSec = timeboxDeadlineSec(goal, opts, startedSec);
+    const guided = isGuidedRun(opts);
     bus.appendEvent(evPath, { type: "goal:session_start", sessionId: sid, scope: goal.scope, ts: startedSec });
     while (true) {
       if (stopRequested)
         break;
-      if (existsSync64(pauseMarkerPath2(id.path, id.slug))) {
+      if (!guided && existsSync64(pauseMarkerPath2(id.path, id.slug))) {
         stopReason2 = "pause_marker";
         break;
       }
@@ -266647,10 +266681,10 @@ async function runGoWorker(id, opts, deps) {
       }
       if (stopRequested)
         break;
-      if (existsSync64(pauseMarkerPath2(id.path, id.slug)))
+      if (!guided && existsSync64(pauseMarkerPath2(id.path, id.slug)))
         continue;
       const before = readRunSnapshot(runsPath2(id.path));
-      await deps.runOnce({ projectPath: id.path, allowedCards });
+      await deps.runOnce({ projectPath: id.path, allowedCards, ...guided ? { guided: true } : {} });
       goal = updateUsage(id.path, goal, baseline, initialUsage, deps.nowIso());
       writeGoal(gPath, goal);
       const after = readRunSnapshot(runsPath2(id.path));
@@ -266707,7 +266741,7 @@ async function runGoWorker(id, opts, deps) {
         stopReason2 = "safety_pause";
         break;
       }
-      if (existsSync64(pauseMarkerPath2(id.path, id.slug))) {
+      if (!guided && existsSync64(pauseMarkerPath2(id.path, id.slug))) {
         stopReason2 = "pause_marker";
         break;
       }
@@ -284487,7 +284521,8 @@ function readCycleTimeoutThresholds(repoCwd) {
   }
   return {
     wallSec: envNum("ROLL_CYCLE_WALL_TIMEOUT_SEC") ?? wallSec,
-    noProgressSec: envNum("ROLL_CYCLE_NO_PROGRESS_SEC") ?? noProgressSec
+    noProgressSec: envNum("ROLL_CYCLE_NO_PROGRESS_SEC") ?? noProgressSec,
+    noStateChangeSec: envNum("ROLL_CYCLE_NO_STATE_CHANGE_SEC") ?? CYCLE_NO_STATE_CHANGE_SEC
   };
 }
 function readStallThreshold(repoCwd) {
@@ -284503,15 +284538,18 @@ function readStallThreshold(repoCwd) {
 }
 function startSpawnTimeoutWatchdog(opts) {
   const { cycleId, thresholds, clock: clock2, commitCount, appendEvent: appendEvent3 } = opts;
+  const stateSignature = opts.stateSignature;
   const kill = opts.kill ?? (() => killLiveAgents("SIGKILL"));
   const pollMs = opts.pollMs ?? (Number((process.env["ROLL_TIMEOUT_POLL_MS"] ?? "").trim()) || TIMEOUT_POLL_MS);
-  if (thresholds.wallSec <= 0 && thresholds.noProgressSec <= 0) {
+  if (thresholds.wallSec <= 0 && thresholds.noProgressSec <= 0 && thresholds.noStateChangeSec <= 0) {
     return { markProgress: () => {
     }, stop: () => ({ firedReason: null }) };
   }
   const startSec = clock2();
   let lastProgressSec = startSec;
+  let lastStateSec = startSec;
   let lastCommitCount = -1;
+  let lastSignature;
   let firedReason = null;
   let running = false;
   const markProgress = () => {
@@ -284526,16 +284564,32 @@ function startSpawnTimeoutWatchdog(opts) {
         const n = await commitCount();
         if (n > lastCommitCount) {
           lastCommitCount = n;
-          lastProgressSec = clock2();
+          const now3 = clock2();
+          lastProgressSec = now3;
+          lastStateSec = now3;
         }
       } catch {
       }
+      if (stateSignature !== void 0) {
+        try {
+          const sig = await stateSignature();
+          if (lastSignature !== void 0 && sig !== lastSignature) {
+            const now3 = clock2();
+            lastProgressSec = now3;
+            lastStateSec = now3;
+          }
+          lastSignature = sig;
+        } catch {
+        }
+      }
       const now2 = clock2();
       const verdict = cycleTimeoutVerdict({
         elapsedSec: now2 - startSec,
         idleSec: now2 - lastProgressSec,
+        stateIdleSec: now2 - lastStateSec,
         wallLimitSec: thresholds.wallSec,
-        noProgressLimitSec: thresholds.noProgressSec
+        noProgressLimitSec: thresholds.noProgressSec,
+        noStateChangeLimitSec: thresholds.noStateChangeSec
       });
       if (verdict.timedOut) {
         firedReason = verdict.reason;
@@ -284565,6 +284619,12 @@ function startSpawnTimeoutWatchdog(opts) {
       lastCommitCount = await commitCount();
     } catch {
     }
+    if (stateSignature !== void 0) {
+      try {
+        lastSignature = await stateSignature();
+      } catch {
+      }
+    }
   })();
   const timer = setInterval(() => void tick(), pollMs);
   timer.unref?.();
@@ -284732,11 +284792,13 @@ async function executeSpawnAgentCommand(cmd, ports, ctx) {
         appendEvent: (ev) => ports.events.appendEvent(ports.paths.eventsPath, ev),
         thresholdSec: readStallThreshold(ports.repoCwd).thresholdSec
       });
+      const statusSignature = ports.git.worktreeStatusSignature;
       const timeoutWatchdog = startSpawnTimeoutWatchdog({
         cycleId: ctx.cycleId ?? "",
         thresholds: readCycleTimeoutThresholds(ports.repoCwd),
         clock: ports.clock,
         commitCount: () => ports.git.commitsAhead(execCwd, observeBase),
+        ...statusSignature !== void 0 ? { stateSignature: () => statusSignature(execCwd) } : {},
         appendEvent: (ev) => ports.events.appendEvent(ports.paths.eventsPath, ev)
       });
       const skillBodyForSpawn = maybeInjectProjectMap(
@@ -287724,6 +287786,13 @@ function nodePorts(opts) {
         const n = Number((r.stdout ?? "0").trim());
         return Number.isFinite(n) ? n : 0;
       },
+      async worktreeStatusSignature(worktreeCwd) {
+        const r = await execFileAsync17("git", ["status", "--porcelain"], {
+          cwd: worktreeCwd,
+          encoding: "utf8"
+        });
+        return r.stdout ?? "";
+      },
       async mainAhead(repoCwd) {
         const r = await execFileAsync17("git", ["rev-list", "--count", "origin/main..main"], {
           cwd: repoCwd,
@@ -288829,7 +288898,7 @@ import { execFileSync as execFileSync32 } from "node:child_process";
 import { homedir as homedir34 } from "node:os";
 import { appendFileSync as appendFileSync20, existsSync as existsSync134, mkdirSync as mkdirSync73, rmSync as rmSync25 } from "node:fs";
 import { dirname as dirname73, join as join157, relative as relative14, resolve as resolve14, sep as sep8 } from "node:path";
-var MERGED_KINDS = /* @__PURE__ */ new Set(["ancestor", "patch_equivalent"]);
+var MERGED_KINDS = /* @__PURE__ */ new Set(["ancestor", "patch_equivalent", "final_tree"]);
 function isSafelyDisposable(rec) {
   return rec.owner === "loop" && rec.active === false && rec.dirtyTracked === false && rec.disposition === "disposable_candidate" && MERGED_KINDS.has(rec.mergeEvidence.kind) && typeof rec.head === "string" && rec.head.length > 0;
 }
@@ -288906,9 +288975,12 @@ function planWorktreeCleanup(audit, threshold, standaloneMergedBranches = []) {
     preserved
   };
 }
-function defaultRemoveBranch(repositoryRoot, branch) {
+function defaultRemoveBranch(repositoryRoot, branch, expectedSha) {
+  if (!isFullGitOid(expectedSha)) {
+    return { ok: false, detail: `refused: expected sha ${expectedSha} is not a full git OID` };
+  }
   try {
-    execFileSync32("git", ["-C", repositoryRoot, "branch", "-D", branch], {
+    execFileSync32("git", ["-C", repositoryRoot, "update-ref", "-d", `refs/heads/${branch}`, expectedSha], {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"]
     });
@@ -289111,7 +289183,7 @@ async function applyWorktreeCleanup(plan, options) {
         branchesRemoved.push(removalB);
         continue;
       }
-      const r = removeBranchFn(repositoryRoot, bc.branch);
+      const r = removeBranchFn(repositoryRoot, bc.branch, bc.expectedSha);
       if (!r.ok) {
         refuseB(`delete-failed: ${r.detail}`);
         continue;
@@ -289257,7 +289329,7 @@ function renderResultHuman(result2) {
   }
   return lines3.join("\n").trimEnd() + "\n";
 }
-var CLEANUP_USAGE = "Usage: roll worktree cleanup [--dry-run | --apply] [--json] [--repo <path>]\n  Safely recover from branch/worktree canary pressure using the worktree\n  audit as the SOLE authority. Removes ONLY inactive, merged, clean\n  `disposable_candidate` loop worktrees, plus (FIX-1454) standalone ephemeral\n  branches that are verifiably merged (ancestor of the integration branch or a\n  merged GitHub PR) and attached to no worktree \u2014 never a path/ref that is\n  merely old or counted, and never a preserved (unpublished / dirty / active /\n  external / current / protected / unmerged) one.\n\n  Always dry-run first. Default (no flag) is --dry-run.\n  --dry-run  print counted refs/dirs, audit dispositions, and the minimal\n             candidate set to clear pressure. Never mutates git state.\n  --apply    re-run the audit before EVERY removal; remove only revalidated\n             candidates via git, prune registration, emit events. A changed\n             head / new dirt / missing path / concurrent activation fails\n             closed (no substitution). Then resume explicitly: roll loop resume\n  --json     emit the schema-1 plan (dry-run) or result (apply) as JSON\n  --repo     override the project root (default: current directory)\n  --reclaim-orphan <path>  (FIX-1460) bounded-rm ONE named orphan loop dir\n             (deregistered from git; delivery not auto-provable) after you\n             review it. Fails closed unless it is an inactive loop orphan\n             inside .roll/loop/worktrees. Auto-reclaim of provably-delivered\n             orphans happens under --apply.\n\n  \u5B89\u5168\u6E05\u7406:\u4EC5\u79FB\u9664\u5BA1\u8BA1\u5224\u5B9A\u4E3A\u5DF2\u5408\u5E76\u3001\u5E72\u51C0\u3001\u975E\u6D3B\u8DC3\u7684 disposable_candidate;\n  \u5148\u8DD1 --dry-run,\u518D --apply,\u6700\u540E\u624B\u52A8 roll loop resume\u3002";
+var CLEANUP_USAGE = "Usage: roll worktree cleanup [--dry-run | --apply] [--json] [--repo <path>]\n  Safely recover from branch/worktree canary pressure using the worktree\n  audit as the SOLE authority. Removes ONLY inactive, merged, clean\n  `disposable_candidate` loop worktrees, plus (FIX-1454) standalone ephemeral\n  branches that are verifiably delivered and attached to no worktree. Delivery\n  is PROVEN by one of: every commit is an ancestor of the integration branch;\n  `git cherry` shows every commit already has an equivalent patch upstream; or\n  (FIX-1471, squash merges) the branch tip tree is byte-identical to the merge\n  commit of the branch's OWN merged GitHub PR (matched by exact head ref) AND\n  that merge commit is an ancestor of the integration branch. A merged PR alone\n  is NEVER sufficient, and no arbitrary same-tree commit on the integration\n  branch is ever used. Never a path/ref that is merely old or counted, and never\n  a preserved (unpublished / dirty / active / external / current / protected /\n  unmerged) one.\n\n  Always dry-run first. Default (no flag) is --dry-run.\n  --dry-run  print counted refs/dirs, audit dispositions, and the minimal\n             candidate set to clear pressure. Never mutates git state.\n  --apply    re-run the audit before EVERY removal; remove only revalidated\n             candidates via git, prune registration, emit events. A changed\n             head / new dirt / missing path / concurrent activation fails\n             closed (no substitution). Then resume explicitly: roll loop resume\n  --json     emit the schema-1 plan (dry-run) or result (apply) as JSON\n  --repo     override the project root (default: current directory)\n  --reclaim-orphan <path>  (FIX-1460) bounded-rm ONE named orphan loop dir\n             (deregistered from git; delivery not auto-provable) after you\n             review it. Fails closed unless it is an inactive loop orphan\n             inside .roll/loop/worktrees. Auto-reclaim of provably-delivered\n             orphans happens under --apply.\n\n  \u5B89\u5168\u6E05\u7406:\u4EC5\u79FB\u9664\u5BA1\u8BA1\u5224\u5B9A\u4E3A\u5DF2\u5408\u5E76\u3001\u5E72\u51C0\u3001\u975E\u6D3B\u8DC3\u7684 disposable_candidate;\n  \u5148\u8DD1 --dry-run,\u518D --apply,\u6700\u540E\u624B\u52A8 roll loop resume\u3002";
 function resolveThreshold() {
   const parsed = parseInt(process.env["ROLL_BRANCH_CANARY_MAX"] ?? "", 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_BRANCH_CANARY_MAX;
@@ -289265,20 +289337,41 @@ function resolveThreshold() {
 function gitCap(repoRoot3, args) {
   return execFileSync32("git", ["-C", repoRoot3, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
 }
-function classifyBranchMerge(branch, integrationBranch, git5) {
+function classifyBranchMerge(branch, integrationBranch, git5, prMergeCommit) {
   if (git5(["merge-base", "--is-ancestor", branch, integrationBranch]).ok)
     return "ancestor";
   const cherry = git5(["cherry", integrationBranch, branch]);
-  if (!cherry.ok)
+  if (cherry.ok) {
+    const lines3 = cherry.stdout.split("\n").map((l) => l.trim()).filter((l) => l !== "");
+    if (lines3.length > 0 && lines3.every((l) => l.startsWith("-")))
+      return "patch_equivalent";
+  }
+  return classifyFinalTreeDelivery(branch, integrationBranch, git5, prMergeCommit);
+}
+function classifyFinalTreeDelivery(branch, integrationBranch, git5, prMergeCommit) {
+  const rawMerge = prMergeCommit(branch);
+  if (rawMerge === null)
     return null;
-  const lines3 = cherry.stdout.split("\n").map((l) => l.trim()).filter((l) => l !== "");
-  if (lines3.length === 0)
+  const merge = rawMerge.trim();
+  if (!isFullGitOid(merge))
     return null;
-  if (lines3.some((l) => l.startsWith("+")))
+  if (!git5(["merge-base", "--is-ancestor", merge, integrationBranch]).ok)
     return null;
-  if (lines3.every((l) => l.startsWith("-")))
-    return "patch_equivalent";
-  return null;
+  const branchTreeProbe = git5(["rev-parse", `${branch}^{tree}`]);
+  if (!branchTreeProbe.ok)
+    return null;
+  const branchTree = branchTreeProbe.stdout.trim();
+  if (branchTree === "")
+    return null;
+  const mergeTreeProbe = git5(["rev-parse", `${merge}^{tree}`]);
+  if (!mergeTreeProbe.ok)
+    return null;
+  const mergeTree = mergeTreeProbe.stdout.trim();
+  if (mergeTree === "")
+    return null;
+  if (branchTree !== mergeTree)
+    return null;
+  return "final_tree";
 }
 function buildStandaloneBranchDeps(repoRoot3, audit, integrationBranch) {
   const attachedBranches = new Set(audit.records.filter((r) => r.owner === "loop" && typeof r.branch === "string" && r.branch !== "").map((r) => r.branch.replace(/^refs\/heads\//, "")));
@@ -289298,11 +289391,12 @@ function buildStandaloneBranchDeps(repoRoot3, audit, integrationBranch) {
         return null;
       }
     },
-    // FIX-1458 (#1465): delivery is proven ONLY by fresh git patch evidence via
-    // classifyBranchMerge (ancestor OR `git cherry` patch-equivalence). A merged
-    // GitHub PR is deliberately NOT consulted: a squash merge leaves the exact
-    // branch tips undelivered, so authorizing deletion on a merged PR alone
-    // silently discards unique commits (US-ORG-003/007/004 in the report).
+    // FIX-1458 (#1465), FIX-1471: delivery is proven by fresh git patch evidence
+    // (ancestor OR `git cherry` patch-equivalence) OR, for the squash-merge case,
+    // by the branch tip tree matching the merge commit of the branch's OWN merged
+    // GitHub PR (an ancestor of integration). A merged PR label alone never
+    // authorizes deletion, and no arbitrary same-tree integration commit is ever
+    // consulted — that would silently discard unique commits (US-ORG-003/007/004).
     branchMerge: (branch) => classifyBranchMerge(branch, integrationBranch, (args) => {
       try {
         return { ok: true, stdout: gitCap(repoRoot3, args) };
@@ -289310,9 +289404,39 @@ function buildStandaloneBranchDeps(repoRoot3, audit, integrationBranch) {
         const stdout = typeof err16.stdout === "string" ? err16.stdout : "";
         return { ok: false, stdout };
       }
-    })
+    }, (b) => ghMergedPrMergeCommit(repoRoot3, b))
   };
 }
+function isFullGitOid(value) {
+  return /^[0-9a-f]{40}$/.test(value) || /^[0-9a-f]{64}$/.test(value);
+}
+function parseMergedPrMergeCommit(raw, branch) {
+  let j;
+  try {
+    j = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (j.state !== "MERGED")
+    return null;
+  if (typeof j.mergedAt !== "string" || j.mergedAt === "")
+    return null;
+  if (typeof j.headRefName !== "string" || j.headRefName !== branch)
+    return null;
+  const oid = j.mergeCommit?.oid;
+  if (typeof oid !== "string" || !isFullGitOid(oid))
+    return null;
+  return oid;
+}
+function ghMergedPrMergeCommit(repoRoot3, branch) {
+  let out3;
+  try {
+    out3 = execFileSync32("gh", ["pr", "view", branch, "--json", "state,mergedAt,mergeCommit,headRefName"], { cwd: repoRoot3, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  } catch {
+    return null;
+  }
+  return parseMergedPrMergeCommit(out3, branch);
+}
 function resolveIntegrationForCleanup(repoRoot3) {
   try {
     const head = gitCap(repoRoot3, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]).trim();
@@ -290111,7 +290235,7 @@ async function loopRunOnceCommand(args) {
       removePendingPublish(rt, storyId);
     }
   }
-  if (isLoopPaused(id.path, id.slug)) {
+  if (isLoopPaused(id.path, id.slug) && !isGuidedRunOnce(allowedCards)) {
     const lang10 = resolveLang({
       rollLang: process.env["ROLL_LANG"],
       lcAll: process.env["LC_ALL"],
@@ -292823,28 +292947,49 @@ function assertTestProofFresh(exec) {
     throw new Error("code changed since last test run \u2014 run `roll test` on the current staged tree");
   }
 }
+function hasOnlyPreparedReleaseChanges(exec) {
+  const status2 = exec("git", ["status", "--porcelain", "--untracked-files=all"]).trim();
+  if (status2 === "")
+    return false;
+  const allowed2 = /* @__PURE__ */ new Set(["package.json", "CHANGELOG.md"]);
+  const unexpected = status2.split("\n").map((line) => line.slice(2).trim()).filter((path) => !allowed2.has(path));
+  if (unexpected.length > 0) {
+    throw new Error(`unexpected worktree changes during release recovery: ${unexpected.join(", ")}`);
+  }
+  return true;
+}
 function commitPushWithGate(opts) {
   const { branch, message, rollManaged, exec } = opts;
   const original = exec("git", ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+  const preparedChanges = hasOnlyPreparedReleaseChanges(exec);
   let createdLocal = false;
+  const checkoutExistingBranch = () => {
+    if (preparedChanges) {
+      exec("git", ["checkout", "--merge", branch]);
+      return;
+    }
+    exec("git", ["checkout", branch]);
+  };
   const checkoutBranch = () => {
+    let localSha = "";
     try {
-      const localSha = exec("git", ["rev-parse", "--verify", `refs/heads/${branch}`]).trim();
-      if (localSha !== "") {
-        exec("git", ["checkout", branch]);
-        return;
-      }
+      localSha = exec("git", ["rev-parse", "--verify", `refs/heads/${branch}`]).trim();
     } catch {
     }
+    if (localSha !== "") {
+      checkoutExistingBranch();
+      return;
+    }
+    let remote = "";
     try {
-      const remote = exec("git", ["ls-remote", "--heads", "origin", branch]).trim();
-      if (remote !== "") {
-        exec("git", ["fetch", "origin", `${branch}:${branch}`]);
-        exec("git", ["checkout", branch]);
-        return;
-      }
+      remote = exec("git", ["ls-remote", "--heads", "origin", branch]).trim();
     } catch {
     }
+    if (remote !== "") {
+      exec("git", ["fetch", "origin", `${branch}:${branch}`]);
+      checkoutExistingBranch();
+      return;
+    }
     createdLocal = true;
     exec("git", ["checkout", "-b", branch]);
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "4.719.3",
+  "version": "4.721.1",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {