dev-loops 0.3.0 → 0.4.0

package/scripts/github/resolve-handoff-candidates.mjs

@@ -0,0 +1,412 @@
+#!/usr/bin/env node
+import { readFile as fsReadFile } from "node:fs/promises";
+import path from "node:path";
+
+import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parsePrNumber, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import {
+  loadDevLoopConfig,
+  resolveHumanHandoffConfig,
+} from "@dev-loops/core/config";
+
+const USAGE = `Usage: resolve-handoff-candidates.mjs --repo <owner/name> --pr <number> [--changed-files <a,b,c>] [--pr-author <login>]
+Resolve an ordered, deduped list of human-handoff reviewer/assignee candidates
+for a PR, from the sources configured under \`approval.humanHandoff\` (#920).
+This is the "offer" side: it surfaces candidates only — it never assigns anyone.
+
+Sources (in priority order):
+  assignees          Static configured list (approval.humanHandoff.assignees).
+  codeowners         .github/CODEOWNERS / CODEOWNERS / docs/CODEOWNERS matched
+                     against the PR's changed paths (last-match-wins per
+                     CODEOWNERS semantics). Team handles (@org/team) are
+                     included, flagged with isTeam:true.
+  recent-committers  git log authors on the PR's changed paths (recent commits),
+                     by GitHub login where derivable from the commit email,
+                     excluding the PR author and bots.
+
+Which sources run is controlled by approval.humanHandoff.candidatesFrom.
+Disabled (default) => no-op: ok:true with an empty candidate list.
+
+Required:
+  --repo <owner/name>
+  --pr <number>
+Optional:
+  --changed-files <csv>   Comma-separated changed paths. When omitted, derived
+                          from \`gh pr view --json files\`.
+  --pr-author <login>     PR author login (excluded from recent-committers).
+                          When omitted, derived from \`gh pr view --json author\`.
+Output (stdout, JSON):
+  { "ok": true, "enabled": bool, "candidates": [{ "login", "source", "isTeam"?, "paths"? }],
+    "changedFiles": [...], "sources": [...], "warnings": [...] }
+Exit codes:
+  0  Success (including disabled no-op and fail-soft per-source skips)
+  1  Argument error`.trim();
+
+const parseError = buildParseError(USAGE);
+
+function nextValue(args, i, flag) {
+  const value = args[i];
+  if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
+    throw parseError(`Missing value for ${flag}`);
+  }
+  return value;
+}
+
+const RECENT_COMMITTERS_LIMIT = 50;
+const CODEOWNERS_PATHS = [".github/CODEOWNERS", "CODEOWNERS", "docs/CODEOWNERS"];
+// Bot author handles to exclude from recent-committers.
+const BOT_PATTERN = /\[bot\]$|^(?:dependabot|github-actions|copilot|renovate)$/i;
+
+export function parseResolveCandidatesCliArgs(argv) {
+  const args = [...argv];
+  if (args.includes("--help") || args.includes("-h")) {
+    return { help: true };
+  }
+  const options = { help: false, repo: undefined, pr: undefined, changedFiles: undefined, prAuthor: undefined };
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (token === "--repo") { options.repo = nextValue(args, ++i, "--repo"); continue; }
+    if (token === "--pr") { options.pr = parsePrNumber(nextValue(args, ++i, "--pr"), parseError); continue; }
+    if (token === "--changed-files") {
+      options.changedFiles = nextValue(args, ++i, "--changed-files")
+        .split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+      continue;
+    }
+    if (token === "--pr-author") { options.prAuthor = nextValue(args, ++i, "--pr-author").trim().replace(/^@/, ""); continue; }
+    throw parseError(`Unknown argument: ${token}`);
+  }
+  if (options.repo === undefined || options.pr === undefined) {
+    throw parseError("Resolving handoff candidates requires both --repo <owner/name> and --pr <number>");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+// ---------------------------------------------------------------------------
+// CODEOWNERS — parse + match
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse CODEOWNERS content into ordered { pattern, owners } rules.
+ * Comments (#...) and blank lines are skipped. Owners keep their leading `@`.
+ * @param {string} content
+ * @returns {{ pattern: string, owners: string[] }[]}
+ */
+export function parseCodeowners(content) {
+  const rules = [];
+  for (const rawLine of String(content).split("\n")) {
+    // A `#` starts a comment only at line start (after leading whitespace) or
+    // when preceded by whitespace; a mid-token `#` is part of the pattern/owner
+    // (gitignore/CODEOWNERS semantics).
+    const line = rawLine.replace(/(^|\s)#.*$/, "").trim();
+    if (line === "") continue;
+    const [pattern, ...owners] = line.split(/\s+/);
+    if (!pattern) continue;
+    rules.push({ pattern, owners: owners.filter((o) => o.length > 0) });
+  }
+  return rules;
+}
+
+/**
+ * Match a CODEOWNERS pattern against a repo-relative path (gitignore-ish).
+ * Leading `/` anchors to repo root; trailing `/` matches a directory subtree;
+ * `*` matches within a path segment, `**` across segments; a bare pattern with
+ * no slash matches the path's basename or any segment.
+ * @param {string} pattern
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function codeownersMatch(pattern, filePath) {
+  const file = filePath.replace(/^\.?\//, "");
+  let pat = pattern;
+  const dirOnly = pat.endsWith("/");
+  if (dirOnly) pat = pat.slice(0, -1);
+  // Bare name (no slash, not anchored): match any path segment subtree.
+  const anchored = pat.startsWith("/");
+  if (anchored) pat = pat.slice(1);
+
+  const toRegex = (p) => {
+    let re = "";
+    for (let i = 0; i < p.length; i += 1) {
+      const c = p[i];
+      if (c === "*") {
+        if (p[i + 1] === "*") { re += ".*"; i += 1; }
+        else re += "[^/]*";
+      } else if ("\\^$.|?+()[]{}".includes(c)) {
+        re += `\\${c}`;
+      } else {
+        re += c;
+      }
+    }
+    return re;
+  };
+
+  // Bare-vs-anchored is decided on the NORMALIZED pattern: a trailing-only `/`
+  // (e.g. `build/`) normalizes to a bare token with no leading/internal slash,
+  // so it matches at any depth like gitignore. Only a leading or internal slash
+  // anchors the match.
+  if (!anchored && !pat.includes("/")) {
+    // Bare token: match a full segment anywhere, plus its subtree.
+    const seg = toRegex(pat);
+    return new RegExp(`(?:^|/)${seg}(?:/|$)`).test(file);
+  }
+
+  const body = toRegex(pat);
+  // Anchored (or contains slash): match from root, allow subtree under it.
+  const re = new RegExp(`^${body}(?:/|$)`);
+  if (re.test(file)) return true;
+  // Directory pattern also matches the directory's whole subtree.
+  if (dirOnly) return new RegExp(`^${body}/`).test(file);
+  return false;
+}
+
+/**
+ * Resolve CODEOWNERS owners for a set of changed paths. Last-match-wins per
+ * CODEOWNERS semantics: the final matching rule for each path wins.
+ * @param {{ pattern: string, owners: string[] }[]} rules
+ * @param {string[]} changedFiles
+ * @returns {Map<string, Set<string>>} owner login (no `@`) -> set of paths
+ */
+export function ownersForPaths(rules, changedFiles) {
+  /** @type {Map<string, Set<string>>} */
+  const byOwner = new Map();
+  for (const file of changedFiles) {
+    let winner = null;
+    for (const rule of rules) {
+      if (codeownersMatch(rule.pattern, file)) winner = rule;
+    }
+    if (!winner || winner.owners.length === 0) continue;
+    for (const owner of winner.owners) {
+      const login = owner.replace(/^@/, "");
+      if (login === "") continue;
+      if (!byOwner.has(login)) byOwner.set(login, new Set());
+      byOwner.get(login).add(file);
+    }
+  }
+  return byOwner;
+}
+
+// ---------------------------------------------------------------------------
+// Source resolvers (each fail-soft: returns candidates + a warning on error)
+// ---------------------------------------------------------------------------
+
+async function resolveCodeownersSource(changedFiles, { repoRoot, readFile }) {
+  const warnings = [];
+  for (const rel of CODEOWNERS_PATHS) {
+    let content;
+    try {
+      content = await readFile(path.join(repoRoot, rel), "utf8");
+    } catch (error) {
+      // ENOENT => genuinely absent at this location: try the next path quietly.
+      // Any other error (EACCES / IO) is real: surface it rather than silently
+      // claiming "no CODEOWNERS file found".
+      if (error && error.code === "ENOENT") continue;
+      warnings.push(`codeowners: failed to read ${rel}: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    const rules = parseCodeowners(content);
+    const byOwner = ownersForPaths(rules, changedFiles);
+    return {
+      candidates: [...byOwner.entries()].map(([login, paths]) => ({
+        login,
+        source: "codeowners",
+        isTeam: login.includes("/"),
+        paths: [...paths],
+      })),
+      warnings,
+    };
+  }
+  // Fail-soft: no CODEOWNERS file anywhere -> no candidates, no abort. Keep any
+  // non-ENOENT read warnings so a permissions/IO failure is not masked.
+  return { candidates: [], warnings: [...warnings, "codeowners: no CODEOWNERS file found"] };
+}
+
+/**
+ * Map a git author email to a GitHub login. `<login>@users.noreply.github.com`
+ * (optionally `<id>+<login>@...`) carries the login directly; otherwise fall
+ * back to the local-part of the email as a best-effort handle.
+ */
+export function loginFromCommitEmail(email) {
+  const e = String(email).trim().toLowerCase();
+  const noreply = e.match(/^(?:\d+\+)?([^@]+)@users\.noreply\.github\.com$/);
+  if (noreply) return noreply[1];
+  const at = e.indexOf("@");
+  return at > 0 ? e.slice(0, at) : null;
+}
+
+async function resolveRecentCommittersSource(changedFiles, { repoRoot, prAuthor, run }) {
+  if (changedFiles.length === 0) {
+    return { candidates: [], warnings: [] };
+  }
+  let stdout;
+  try {
+    const result = await run("git", [
+      "-C", repoRoot,
+      "log", `-n${RECENT_COMMITTERS_LIMIT}`, "--no-merges", "--pretty=format:%ae",
+      "--", ...changedFiles,
+    ]);
+    if (result.code !== 0) {
+      return { candidates: [], warnings: [`recent-committers: git log exited ${result.code}`] };
+    }
+    stdout = result.stdout;
+  } catch (error) {
+    return { candidates: [], warnings: [`recent-committers: ${error instanceof Error ? error.message : String(error)}`] };
+  }
+  const author = prAuthor ? prAuthor.toLowerCase() : null;
+  const seen = new Set();
+  const candidates = [];
+  for (const line of stdout.split("\n")) {
+    const email = line.trim();
+    if (email === "") continue;
+    const login = loginFromCommitEmail(email);
+    if (!login) continue;
+    const key = login.toLowerCase();
+    if (seen.has(key)) continue;
+    if (BOT_PATTERN.test(login)) continue;
+    if (author && key === author) continue;
+    seen.add(key);
+    candidates.push({ login, source: "recent-committers" });
+  }
+  return { candidates, warnings: [] };
+}
+
+// ---------------------------------------------------------------------------
+// gh lookups for changed files / author (only when not supplied)
+// ---------------------------------------------------------------------------
+
+async function fetchPrFacts(repo, pr, { run, ghCommand }) {
+  const result = await run(ghCommand, [
+    "pr", "view", String(pr), "--repo", repo, "--json", "files,author",
+  ]);
+  if (result.code !== 0) {
+    throw new Error(result.stderr.trim() || `gh pr view exited ${result.code}`);
+  }
+  const payload = JSON.parse(result.stdout);
+  const files = Array.isArray(payload?.files)
+    ? payload.files.map((f) => (typeof f?.path === "string" ? f.path : "")).filter((p) => p.length > 0)
+    : [];
+  const author = typeof payload?.author?.login === "string" ? payload.author.login : null;
+  return { files, author };
+}
+
+// ---------------------------------------------------------------------------
+// Orchestration
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve handoff candidates. Pure-ish: all IO is injected.
+ * @param {{ repo: string, pr: number, changedFiles?: string[], prAuthor?: string|null }} input
+ * @param {object} deps
+ * @returns {Promise<object>}
+ */
+export async function resolveHandoffCandidates(input, deps = {}) {
+  const {
+    config,
+    repoRoot = process.cwd(),
+    ghCommand = "gh",
+    run = (cmd, args) => runChild(cmd, args),
+    readFile = fsReadFile,
+  } = deps;
+
+  const handoff = resolveHumanHandoffConfig(config);
+  const warnings = [];
+
+  if (!handoff.enabled) {
+    return {
+      ok: true,
+      enabled: false,
+      candidates: [],
+      changedFiles: input.changedFiles ?? [],
+      sources: [],
+      warnings: [],
+    };
+  }
+
+  let changedFiles = input.changedFiles;
+  let prAuthor = input.prAuthor ?? null;
+  if (changedFiles === undefined || prAuthor === null) {
+    try {
+      const facts = await fetchPrFacts(input.repo, input.pr, { run, ghCommand });
+      if (changedFiles === undefined) changedFiles = facts.files;
+      if (prAuthor === null) prAuthor = facts.author;
+    } catch (error) {
+      warnings.push(`pr-facts: ${error instanceof Error ? error.message : String(error)}`);
+      if (changedFiles === undefined) changedFiles = [];
+    }
+  }
+
+  const ordered = [];
+  // 1. Static assignees — highest priority.
+  for (const login of handoff.assignees) {
+    ordered.push({ login: login.replace(/^@/, ""), source: "assignees", isTeam: login.includes("/") });
+  }
+
+  // 2/3. Other sources, in the CANONICAL priority order
+  // (assignees > codeowners > recent-committers), regardless of the order they
+  // appear in candidatesFrom. candidatesFrom only selects WHICH sources run,
+  // not their relative rank.
+  const enabledSources = new Set(handoff.candidatesFrom);
+  if (enabledSources.has("codeowners")) {
+    const result = await resolveCodeownersSource(changedFiles, { repoRoot, readFile });
+    ordered.push(...result.candidates);
+    warnings.push(...result.warnings);
+  }
+  if (enabledSources.has("recent-committers")) {
+    const result = await resolveRecentCommittersSource(changedFiles, { repoRoot, prAuthor, run });
+    ordered.push(...result.candidates);
+    warnings.push(...result.warnings);
+  }
+
+  // Dedup by login (case-insensitive), first occurrence wins (preserves the
+  // assignees > codeowners > recent-committers priority).
+  const seen = new Set();
+  const candidates = [];
+  for (const c of ordered) {
+    const key = c.login.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    candidates.push(c);
+  }
+
+  return {
+    ok: true,
+    enabled: true,
+    candidates,
+    changedFiles,
+    sources: handoff.candidatesFrom,
+    warnings,
+  };
+}
+
+export async function main(argv = process.argv.slice(2), deps = {}) {
+  let options;
+  try {
+    options = parseResolveCandidatesCliArgs(argv);
+  } catch (error) {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  const repoRoot = deps.repoRoot ?? process.cwd();
+  const { config } = deps.config !== undefined
+    ? { config: deps.config }
+    : await loadDevLoopConfig({ repoRoot });
+  const result = await resolveHandoffCandidates(
+    { repo: options.repo, pr: options.pr, changedFiles: options.changedFiles, prAuthor: options.prAuthor ?? null },
+    { ...deps, config, repoRoot },
+  );
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  return 0;
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  main().then((code) => { process.exitCode = code; });
+}

package/scripts/github/upsert-checkpoint-verdict.mjs

@@ -1194,7 +1194,7 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
   if (existing) {
     const updated = await updateComment({ repo: options.repo, commentId: existing.commentId, body: desiredBody }, { env, ghCommand });
     // Post-update verification: verify the updated comment is visible via direct API fetch by comment ID.
-    // A run id is set (production context) — DEVLOOPS_RUN_ID, or the PI_SUBAGENT_RUN_ID alias.
+    // A run id is set (production context) — DEVLOOPS_RUN_ID.
     let updateVerificationWarning = null;
     if (envRunId) {
       let verified = await verifyComment({ repo: options.repo, commentId: updated.commentId }, { env, ghCommand });
@@ -1229,7 +1229,7 @@ export async function upsertCheckpointVerdict(options, { env = process.env, ghCo
   // comment is not yet returned by paginated list endpoints. A direct fetch
   // by comment ID confirms the comment is persisted, preventing the evidence
   // checker from falsely reporting "missing" and triggering a duplicate post.
-  // Only active when a run id is set (production context) — DEVLOOPS_RUN_ID or the PI_SUBAGENT_RUN_ID alias.
+  // Only active when a run id is set (production context) — DEVLOOPS_RUN_ID.
   let verified = true;
   let verificationWarning = null;
   if (envRunId) {

package/scripts/loop/_stale-runner-detection.mjs

@@ -18,7 +18,7 @@ export function resolveStaleRunnerMaxAgeMs(options = {}, env = process.env) {
   if (Number.isFinite(explicit) && explicit > 0) {
     return Math.floor(explicit);
   }
-  const fromEnv = parsePositiveIntegerMs(env?.PI_DEV_LOOP_STALE_RUNNER_MAX_AGE_MS, NaN);
+  const fromEnv = parsePositiveIntegerMs(env?.DEVLOOPS_STALE_RUNNER_MAX_AGE_MS, NaN);
   if (Number.isFinite(fromEnv) && fromEnv > 0) {
     return fromEnv;
   }

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-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,