dev-loops 0.2.7 → 0.4.0

package/scripts/loop/_worktree-path.mjs

@@ -0,0 +1,27 @@
+/**
+ * Shared worktree-path helpers (issue #909). Extracted so create/cleanup agree
+ * on how a path is canonicalized for comparison/safety checks.
+ */
+import { realpathSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Canonicalize for comparison: resolve symlinks on the longest existing prefix
+ * (macOS /var → /private/var), keeping any not-yet-created leaf. Lets us match a
+ * git-reported worktree path against a target that may not exist yet, and lets a
+ * safety prefix-check see through a symlinked namespace dir.
+ */
+export function canonicalize(p) {
+  let cur = path.resolve(p);
+  const tail = [];
+  for (;;) {
+    try {
+      return path.join(realpathSync(cur), ...tail);
+    } catch {
+      const parent = path.dirname(cur);
+      if (parent === cur) return path.resolve(p); // hit root without resolving
+      tail.unshift(path.basename(cur));
+      cur = parent;
+    }
+  }
+}

package/scripts/loop/cleanup-worktree.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * Namespace-scoped post-merge worktree cleanup (issue #909).
+ *
+ * Resolves the canonical worktree path via the shared resolver, then runs
+ * `git worktree remove --force <path>` + `git worktree prune` from the main
+ * checkout (so it never removes the cwd).
+ *
+ * CLEANUP-SAFETY INVARIANT: refuses to remove any path NOT under
+ * `tmp/worktrees/dev-loops/`. A hand-made `tmp/worktrees/my-experiment` can
+ * never be force-removed by the loop.
+ *
+ * FAIL-SOFT: a git error is logged and reported but does NOT fail the process
+ * (exit 0 with a reason) so it never breaks a merge-completion flow. Prints a
+ * JSON result to stdout.
+ */
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { requireTokenValue } from "../_cli-primitives.mjs";
+import { parseArgs } from "node:util";
+import { resolveWorktreePath, WORKTREE_NAMESPACE } from "@dev-loops/core/loop/handoff-envelope";
+import { canonicalize } from "./_worktree-path.mjs";
+
+const USAGE = `Usage:
+  cleanup-worktree.mjs --repo-root <p> (--issue <n> | --pr <n> | --path <p>)
+Remove a loop-owned worktree after merge: git worktree remove --force + prune.
+Refuses any path not under ${WORKTREE_NAMESPACE}/.
+Required:
+  --repo-root <p>   Absolute path to the main checkout (git runs here).
+  one of:
+  --issue <n>       Issue number (resolves the canonical path).
+  --pr <n>          PR number (resolves the canonical path).
+  --path <p>        Explicit worktree path (must be under the namespace).
+Optional:
+  -h, --help        Show this help.
+Output (stdout, JSON):
+  { "ok": bool, "removed": <path>|null, "reason": "<why>" }
+  ok is true on success/skip (incl. fail-soft git errors); false ONLY when the
+  path is refused for being outside ${WORKTREE_NAMESPACE}/ (removed: null).`.trim();
+
+const parseError = buildParseError(USAGE);
+
+function parsePositiveInt(value, flag) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1) throw parseError(`${flag} must be a positive integer`);
+  return n;
+}
+
+export function parseCleanupWorktreeCliArgs(argv) {
+  const options = { help: false, repoRoot: undefined, issue: undefined, pr: undefined, path: undefined };
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      "repo-root": { type: "string" },
+      issue: { type: "string" },
+      pr: { type: "string" },
+      path: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  for (const token of tokens) {
+    if (token.kind === "positional") throw parseError(`Unknown argument: ${token.value}`);
+    if (token.kind !== "option") continue;
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "repo-root") {
+      options.repoRoot = requireTokenValue(token, parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    if (token.name === "issue") {
+      options.issue = parsePositiveInt(requireTokenValue(token, parseError, { flagPattern: /^-/u }), "--issue");
+      continue;
+    }
+    if (token.name === "pr") {
+      options.pr = parsePositiveInt(requireTokenValue(token, parseError, { flagPattern: /^-/u }), "--pr");
+      continue;
+    }
+    if (token.name === "path") {
+      options.path = requireTokenValue(token, parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (options.help) return options;
+  if (!options.repoRoot) throw parseError("Missing required --repo-root");
+  const selectors = [options.issue, options.pr, options.path].filter((v) => v !== undefined);
+  if (selectors.length === 0) throw parseError("One of --issue, --pr, or --path is required");
+  if (selectors.length > 1) throw parseError("Provide exactly one of --issue, --pr, or --path");
+  return options;
+}
+
+/**
+ * True when `target` is at or under `<repoRoot>/tmp/worktrees/dev-loops/`.
+ * Canonicalizes (realpath) every side first: a purely lexical prefix check is
+ * bypassable when the namespace dir (or a parent) is a symlink pointing outside
+ * the repo — `git worktree remove --force` would then delete outside the repo.
+ * Two checks close that hole: (1) the resolved namespace must still live inside
+ * the resolved repo-root, and (2) the resolved target must live inside the
+ * resolved namespace.
+ */
+function isUnderNamespace(target, repoRoot) {
+  const realRoot = canonicalize(repoRoot);
+  const nsRoot = canonicalize(path.join(repoRoot, WORKTREE_NAMESPACE));
+  const real = canonicalize(target);
+  const within = (child, parent) => child === parent || child.startsWith(parent + path.sep);
+  // Namespace must resolve inside the repo (refuses a symlinked-out namespace),
+  // and the target must resolve inside that namespace.
+  return within(nsRoot, realRoot) && within(real, nsRoot);
+}
+
+export function cleanupWorktree({ repoRoot, issue, pr, path: explicitPath }, { gitCommand = "git" } = {}) {
+  const root = path.resolve(repoRoot);
+
+  let target;
+  if (explicitPath !== undefined) {
+    target = path.resolve(root, explicitPath);
+  } else {
+    const kind = issue !== undefined ? "issue" : "pr";
+    const number = issue !== undefined ? issue : pr;
+    target = resolveWorktreePath({ repoRoot: root, kind, number });
+  }
+
+  // Cleanup-safety invariant: only ever remove loop-owned worktrees.
+  if (!isUnderNamespace(target, root)) {
+    return {
+      ok: false,
+      removed: null,
+      reason: `refused: ${target} is not under ${WORKTREE_NAMESPACE}/`,
+    };
+  }
+
+  try {
+    execFileSync(gitCommand, ["worktree", "remove", "--force", target], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    execFileSync(gitCommand, ["worktree", "prune"], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (err) {
+    // Fail-soft: never break a merge-completion flow on a git error.
+    const detail = (err.stderr ?? err.message ?? "").toString().trim();
+    return { ok: true, removed: null, reason: `git error (non-fatal): ${detail}` };
+  }
+
+  return { ok: true, removed: target, reason: "removed" };
+}
+
+export function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseCleanupWorktreeCliArgs(argv);
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return;
+  }
+  const result = cleanupWorktree(options);
+  stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  try {
+    runCli();
+  } catch (error) {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  }
+}

package/scripts/loop/copilot-pr-handoff.mjs

@@ -333,7 +333,7 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
   let interpretation = interpretLoopState(snapshot, refinementConfig);
 
   // Check for human comments since last subagent action
-  // Only active in async subagent context (DEVLOOPS_RUN_ID, or the PI_SUBAGENT_RUN_ID alias, set)
+  // Only active in async subagent context (DEVLOOPS_RUN_ID set)
   let humanCommentCheck = { paused: false };
   if (resolveRunId(env)) {
     humanCommentCheck = await detectRecentHumanComments(

package/scripts/loop/detect-change-scope.mjs

@@ -1,12 +1,9 @@
 #!/usr/bin/env node
 import { execFileSync } from "node:child_process";
 import process from "node:process";
-function parseArgs() {
-  const args = process.argv.slice(2);
-  const opts = { base: null, head: null };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--help" || args[i] === "-h") {
-      process.stdout.write(`Usage: detect-change-scope.mjs [--base <ref>] [--head <ref>]
+import { parseArgs } from "node:util";
+
+const USAGE = `Usage: detect-change-scope.mjs [--base <ref>] [--head <ref>]
 Detect change scope from git diff for light-mode eligibility.
 Options:
   --base <ref>   Override base ref (default: HEAD~1)
@@ -15,11 +12,39 @@ Options:
 Exit codes:
   0   Success
   1   Error
-`);
-      process.exit(0);
+`;
+
+function parseCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      base: { type: "string" },
+      head: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  const opts = { base: null, head: null };
+  for (const token of tokens) {
+    if (token.kind === "option") {
+      if (token.name === "help") {
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
+        process.stdout.write(USAGE);
+        process.exit(0);
+      }
+      if (token.name === "base") {
+        opts.base = token.value ?? null;
+        continue;
+      }
+      if (token.name === "head") {
+        opts.head = token.value ?? null;
+      }
     }
-    if (args[i] === "--base" && i + 1 < args.length) opts.base = args[++i];
-    else if (args[i] === "--head" && i + 1 < args.length) opts.head = args[++i];
   }
   return opts;
 }
@@ -64,7 +89,7 @@ function isEligibleForLightMode(scope, threshold) {
   return scope.filesChanged <= threshold.maxFiles && scope.linesChanged <= threshold.maxLines;
 }
 async function main() {
-  const opts = parseArgs();
+  const opts = parseCliArgs(process.argv.slice(2));
   const scope = detectScope(opts);
   let threshold = { maxFiles: 3, maxLines: 200 };
   let eligible = false;

package/scripts/loop/detect-pr-gate-coordination-state.mjs

@@ -6,13 +6,13 @@ import {
   formatCliError,
   isCopilotLogin,
   isDirectCliRun,
-  normalizeTimestamp,
   parseJsonText,
   parseReviewThreads,
+  resolveDraftGateRoundResetMs,
   summarizeCopilotReviews,
 } from "../_core-helpers.mjs";
 import { parsePrNumber, requireTokenValue, runChild } from "../_cli-primitives.mjs";
-import { loadDevLoopConfig, resolveGateConfig, resolveRefinementConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
+import { loadDevLoopConfig, resolveGateConfig, resolveRefinement, resolveRefinementConfig, resolveWorkflowConfig } from "@dev-loops/core/config";
 import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { buildSnapshotFromPrFacts, interpretLoopState, summarizeLoopInterpretation } from "@dev-loops/core/loop/copilot-loop-state";
 import { evaluatePrGateCoordination, PR_CHECKPOINT, PR_CHECKPOINT_ACTION } from "@dev-loops/core/loop/pr-gate-coordination";
@@ -303,18 +303,13 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
   const gateEvidence = await detectCheckpointEvidence(options, runtime);
   // When draft gate was re-passed on a different head, use its timestamp
   // to reset the Copilot round count — only reviews after the re-pass count.
-  // Use prefix matching for the head SHA comparison so shortened SHAs (7+)
-  // from gate comments match the full headRefOid.
-  const draftGateHeadSha = gateEvidence.draftGate?.headSha;
-  const draftGateOnCurrentHead = typeof draftGateHeadSha === "string"
-    && typeof currentHeadSha === "string"
-    && currentHeadSha.startsWith(draftGateHeadSha);
-  const draftGateResetAtMs = gateEvidence.draftGate?.verdict === "clean"
-    && typeof draftGateHeadSha === "string"
-    && !draftGateOnCurrentHead
-    && typeof gateEvidence.draftGate?.updatedAt === "string"
-    ? normalizeTimestamp(gateEvidence.draftGate.updatedAt)
-    : null;
+  // Shared with request-copilot-review so both scripts compute the same
+  // completed round count / cap (#896). Prefix matching for the head SHA lets
+  // shortened SHAs (7+) from gate comments match the full headRefOid.
+  const draftGateResetAtMs = resolveDraftGateRoundResetMs({
+    draftGate: gateEvidence.draftGate,
+    currentHeadSha,
+  });
   const reviewSummary = summarizeCopilotReviews(prData?.reviews, { headSha: currentHeadSha, draftGateResetAtMs });
   const reviewRequestStatus = requestedReviewers.requested
     ? "requested"
@@ -338,8 +333,19 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
   if (gateEvidence.currentHeadSha !== currentHeadSha) {
     throw new Error(`PR head changed while loading gate coordination facts for ${options.repo}#${options.pr}; refuse to evaluate mixed-head gate state.`);
   }
-  const interpretation = interpretLoopState(snapshot);
-  const disposition = summarizeLoopInterpretation(interpretation);
+  // Resolve the refinement config (round cap, low-signal heuristic) and feed it to
+  // the interpreter. Without it, the interpreter cannot see maxCopilotRounds and so
+  // never resolves ROUND_CAP_CLEAN_FALLBACK — a post-cap clean head would fall to
+  // READY_TO_REREQUEST_REVIEW, dead-ending the loop at the round cap (#896). This
+  // keeps the gate-coordination interpretation consistent with the standalone
+  // detect-copilot-loop-state path and with request-copilot-review's cap logic.
+  const interpreterRepoRoot = runtime.repoRoot ?? process.cwd();
+  const interpreterConfigResult = await loadDevLoopConfig({ repoRoot: interpreterRepoRoot });
+  const interpreterRefinementConfig = (Array.isArray(interpreterConfigResult.errors) && interpreterConfigResult.errors.length > 0)
+    ? resolveRefinement({ version: 1 })
+    : resolveRefinement(interpreterConfigResult.config ?? { version: 1 });
+  const interpretation = interpretLoopState(snapshot, interpreterRefinementConfig);
+  const disposition = summarizeLoopInterpretation(interpretation, interpreterRefinementConfig);
   const mergeStateStatus = typeof prData?.mergeStateStatus === "string" && prData.mergeStateStatus.trim().length > 0
     ? prData.mergeStateStatus.trim().toUpperCase()
     : null;
@@ -362,6 +368,7 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
     interpretation,
     disposition,
     refinementArtifact,
+    refinementConfig: interpreterRefinementConfig,
   };
 }
 
@@ -429,9 +436,13 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     && typeof (context.snapshot?.copilotReviewRoundCount) === "number"
     && context.snapshot?.copilotReviewRoundCount >= maxCopilotRounds;
   const sameHeadCleanConverged = context.interpretation?.sameHeadCleanConverged ?? false;
+  // Round-cap clean fallback (#896): the interpreter resolved a clean post-cap head
+  // (zero unresolved threads + green CI) that Copilot will not re-review. The formal
+  // request guard must not fire here — pre_approval_gate reviews the post-cap head.
+  const roundCapCleanFallback = context.interpretation?.roundCapCleanEligible ?? false;
   const copilotReviewEverFormallyRequested = copilotReviewRequestStatus === "none"
     && guardBoundaries.has(result.gateBoundary)
-    && !(roundCapReached && sameHeadCleanConverged)
+    && !(roundCapReached && (sameHeadCleanConverged || roundCapCleanFallback))
     ? await fetchCopilotEverFormallyRequested(
         { repo: context.repo, pr: context.pr },
         runtime,
@@ -442,7 +453,8 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     copilotReviewRoundCount: context.snapshot?.copilotReviewRoundCount ?? 0,
     copilotReviewEverFormallyRequested,
     maxCopilotRounds,
-    sameHeadCleanConverged: context.interpretation?.sameHeadCleanConverged ?? false,
+    sameHeadCleanConverged,
+    roundCapCleanFallback,
     gateBoundary: result.gateBoundary,
   })) {
     result.gateBoundary = PR_CHECKPOINT.POST_DRAFT_EXTERNAL_REVIEW;

package/scripts/loop/detect-stale-runner.mjs

@@ -19,11 +19,10 @@ Required:
 Optional:
   --stale-runner-max-age-ms <ms>
                         Override the staleness threshold (default 30 minutes,
-                        or $PI_DEV_LOOP_STALE_RUNNER_MAX_AGE_MS).
+                        or $DEVLOOPS_STALE_RUNNER_MAX_AGE_MS).
   --run-id <id>         Override the active run id (default: read from
-                        DEVLOOPS_RUN_ID, falling back to the PI_SUBAGENT_RUN_ID
-                        alias). When supplied, the detector additionally verifies
-                        the current run id is still the active owner.
+                        DEVLOOPS_RUN_ID). When supplied, the detector additionally
+                        verifies the current run id is still the active owner.
 Output (stdout, JSON; always includes staleRunnerCheck):
   {
     "ok": true,

package/scripts/loop/detect-tracker-first-loop-state.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import process from "node:process";
 import { execFileSync } from "node:child_process";
+import { parseArgs } from "node:util";
 import { interpretTrackerLoopState } from "@dev-loops/core/loop/tracker-first-loop-state";
+
 function showHelp() {
   process.stdout.write(`Usage: detect-tracker-first-loop-state.mjs --repo <owner/name> --issue <number>
 Detect tracker-first loop state for a GitHub issue.
@@ -15,40 +17,65 @@ Exit codes:
 `);
   process.exit(0);
 }
-function parseArgs() {
-  const args = process.argv.slice(2);
+
+function parseCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      repo: { type: "string" },
+      issue: { type: "string" },
+      help: { type: "boolean", short: "h" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
   const opts = { repo: null, issue: null };
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === "--help" || args[i] === "-h") {
-      showHelp();
+  for (const token of tokens) {
+    if (token.kind === "option") {
+      if (token.name === "help") {
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
+        showHelp();
+      }
+      if (token.name === "repo") {
+        opts.repo = token.value ?? null;
+        continue;
+      }
+      if (token.name === "issue") {
+        opts.issue = token.value ?? null;
+      }
     }
-    if (args[i] === "--repo" && i + 1 < args.length) opts.repo = args[++i];
-    else if (args[i] === "--issue" && i + 1 < args.length) opts.issue = args[++i];
   }
   return opts;
 }
+
 async function main() {
-  const opts = parseArgs();
-  if (!opts.repo || !opts.issue) {
+  const rawOpts = parseCliArgs(process.argv.slice(2));
+  if (!rawOpts.repo || !rawOpts.issue) {
     process.stderr.write(
       JSON.stringify({ ok: false, error: "--repo and --issue required" }) + "\n"
     );
     process.exitCode = 1;
     return;
   }
+  const repo = rawOpts.repo;
+  const issue = rawOpts.issue;
   let rawState = "";
   let prContext = null;
   try {
     const issueJson = execFileSync(
       "gh",
-      ["issue", "view", String(opts.issue), "--repo", opts.repo, "--json", "state,title", "--jq", ".state"],
+      ["issue", "view", String(issue), "--repo", repo, "--json", "state,title", "--jq", ".state"],
       { encoding: "utf8" }
     ).trim();
     rawState = issueJson;
     try {
       const prJson = execFileSync(
         "gh",
-        ["pr", "list", "--repo", opts.repo, "--search", `${opts.issue} in:body`, "--state", "open", "--json", "number,state,headRefName", "--jq", ".[0]"],
+        ["pr", "list", "--repo", repo, "--search", `${issue} in:body`, "--state", "open", "--json", "number,state,headRefName", "--jq", ".[0]"],
         { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }
       ).trim();
       if (prJson) prContext = JSON.parse(prJson);