dev-loops 0.3.0 → 0.5.0

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

@@ -17,6 +17,7 @@ import {
   enforceExternalHealthyWaitTimeout,
 } from "@dev-loops/core/loop/timeout-policy";
 import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
 import {
   DEFAULT_POLL_INTERVAL_MS,
   COPILOT_REVIEW_WAIT_TIMEOUT_MS,
@@ -69,9 +70,11 @@ Error output (stderr, JSON):
     { "ok": false, "error": "...", "usage": "..." }
   gh/runtime failures:
     { "ok": false, "error": "..." }
+${JQ_OUTPUT_USAGE}
 Exit codes:
   0  Success
-  1  Argument error or gh failure`.trim();
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
 const WATCH_STATES = new Set([
   STATE.WAITING_FOR_COPILOT_REVIEW,
 ]);
@@ -134,6 +137,8 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
     repo: undefined,
     pr: undefined,
     watchStatus: undefined,
+    jq: undefined,
+    silent: false,
   };
   const { tokens } = parseArgs({
     args: [...argv],
@@ -142,6 +147,7 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
       repo: { type: "string" },
       pr: { type: "string" },
       "watch-status": { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
     },
     allowPositionals: true,
     strict: false,
@@ -177,6 +183,14 @@ export function parseHandoffCliArgs(argv, { cwd = process.cwd() } = {}) {
       options.watchStatus = watchStatus;
       continue;
     }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
     throw parseError(`Unknown argument: ${token.rawName}`);
   }
   if (options.pr === undefined) {
@@ -333,7 +347,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(
@@ -519,10 +533,14 @@ export async function runCli(
     return;
   }
   const result = await runHandoff(options, { env, ghCommand });
-  stdout.write(`${JSON.stringify(result)}\n`);
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout });
 }
 if (isDirectCliRun(import.meta.url)) {
-  runCli().catch((error) => {
+  runCli().then((code) => {
+    if (typeof code === "number") {
+      process.exitCode = code;
+    }
+  }).catch((error) => {
     process.stderr.write(`${formatCliError(error)}\n`);
     process.exitCode = 1;
   });

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

@@ -163,7 +163,7 @@ async function fetchRequestedReviewers({ repo, pr }, { env = process.env, ghComm
 async function fetchPrFacts({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
   const result = await runChild(
     ghCommand,
-    ["pr", "view", String(pr), "--repo", repo, "--json", "number,state,isDraft,headRefOid,mergeStateStatus,body,title,closingIssuesReferences,reviews,statusCheckRollup"],
+    ["pr", "view", String(pr), "--repo", repo, "--json", "number,state,isDraft,headRefOid,mergeable,mergeStateStatus,body,title,closingIssuesReferences,reviews,statusCheckRollup"],
     env,
   );
   if (result.code !== 0) {
@@ -172,6 +172,32 @@ async function fetchPrFacts({ repo, pr }, { env = process.env, ghCommand = "gh"
   }
   return parseJsonText(result.stdout, { label: "gh pr view" });
 }
+
+// GitHub computes `mergeable` asynchronously, so a freshly-pushed head briefly
+// reads `UNKNOWN`. After the initial fetch, re-poll up to `maxPolls` more times
+// while the value stays UNKNOWN (so at most 1 + maxPolls total fetches) before
+// deciding; never treat a transient UNKNOWN as a pass — the caller fails closed
+// to recheck if it never settles. (issue #980)
+export async function fetchPrFactsWithSettledMergeable(
+  options,
+  {
+    env = process.env,
+    ghCommand = "gh",
+    maxPolls = 3,
+    pollDelayMs = 1500,
+    sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+    fetch = fetchPrFacts,
+  } = {},
+) {
+  let prData = await fetch(options, { env, ghCommand });
+  let polls = 0;
+  while (String(prData?.mergeable || "").toUpperCase() === "UNKNOWN" && polls < maxPolls) {
+    polls += 1;
+    await sleep(pollDelayMs);
+    prData = await fetch(options, { env, ghCommand });
+  }
+  return prData;
+}
 export function resolveLinkedIssueFromPr(prData) {
   if (!prData || typeof prData !== "object") return null;
   const closing = Array.isArray(prData.closingIssuesReferences) ? prData.closingIssuesReferences : [];
@@ -290,7 +316,7 @@ async function loadRetrospectiveCheckpoint(repoRoot) {
   }
 }
 export async function loadPrGateCoordinationContext(options, runtime = {}) {
-  const prData = await fetchPrFacts(options, runtime);
+  const prData = await fetchPrFactsWithSettledMergeable(options, runtime);
   const currentHeadSha = typeof prData?.headRefOid === "string" && prData.headRefOid.trim().length > 0
     ? prData.headRefOid.trim()
     : null;
@@ -349,6 +375,9 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
   const mergeStateStatus = typeof prData?.mergeStateStatus === "string" && prData.mergeStateStatus.trim().length > 0
     ? prData.mergeStateStatus.trim().toUpperCase()
     : null;
+  const mergeable = typeof prData?.mergeable === "string" && prData.mergeable.trim().length > 0
+    ? prData.mergeable.trim().toUpperCase()
+    : null;
   const isDraft = Boolean(prData?.isDraft);
   const isClosed = String(prData?.state || "").toUpperCase() === "CLOSED";
   const isMerged = String(prData?.state || "").toUpperCase() === "MERGED";
@@ -361,6 +390,7 @@ export async function loadPrGateCoordinationContext(options, runtime = {}) {
     pr: options.pr,
     currentHeadSha,
     mergeStateStatus,
+    mergeable,
     conflictFiles,
     prData,
     snapshot,
@@ -396,6 +426,7 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
   const draftGateConfig = resolveGateConfig(config, "draft");
   const maxCopilotRounds = resolveRefinementConfig(config, "maxCopilotRounds");
   const requireRetrospectiveGate = resolveWorkflowConfig(config, "requireRetrospectiveGate");
+  const requireRetrospectiveInternalTooling = resolveWorkflowConfig(config, "requireRetrospectiveInternalTooling");
   const retrospectiveCheckpoint = await loadRetrospectiveCheckpoint(repoRoot);
   const result = evaluatePrGateCoordination({
     repo: context.repo,
@@ -406,6 +437,7 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     prMerged: String(context.prData?.state || "").toUpperCase() === "MERGED",
     prTitle: context.prData?.title,
     mergeStateStatus: context.mergeStateStatus,
+    mergeable: context.mergeable,
     conflictFiles: context.conflictFiles,
     lifecycleState: context.interpretation.state,
     loopDisposition: context.disposition.loopDisposition,
@@ -415,6 +447,7 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     sameHeadCleanConverged: context.interpretation.sameHeadCleanConverged,
     draftGateRequireCi: draftGateConfig.requireCi,
     requireRetrospectiveGate,
+    requireRetrospectiveInternalTooling,
     retrospectiveCheckpoint,
     draftGate: context.gateEvidence.draftGate,
     draftGateMarker: context.gateEvidence.draftGateMarker,

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/docs-grill-contract.mjs

@@ -0,0 +1,70 @@
+// Bounded docs-grill disposition classifier behind `dev-loop`. Sibling of
+// scripts/loop/slides-story-review-contract.mjs: this one codifies the keep/fix
+// rule for the autonomous docs-grill step (claims vs the actual contracts,
+// code-vs-doc drift, stale references, contract-surface accuracy). Pure module,
+// no I/O. See docs/docs-grill-step.md.
+
+// What each finding asserts is wrong. `drift` covers any divergence between a
+// claim/reference and the contract surface it points at; `stale_reference`
+// covers a link/path/command that no longer resolves; `cosmetic` covers
+// wording-only nits with no behavioral or reference impact.
+export const DOCS_GRILL_FINDING_KINDS = Object.freeze([
+  'drift',
+  'stale_reference',
+  'cosmetic',
+]);
+
+// The bounded disposition the step assigns to each finding.
+export const DOCS_GRILL_DISPOSITIONS = Object.freeze([
+  'record_finding', // real drift between code/behavior and a contract claim — record it
+  'fix_in_place', // doc-only drift the loop can correct on this branch
+  'route_followup', // doc-only drift too large for this branch — route a follow-up
+  'ignore_cosmetic', // wording nit that does not justify a block or a fix here
+]);
+
+/**
+ * Classify one docs-grill finding into its keep/fix disposition.
+ *
+ * The keep/fix rule (docs/docs-grill-step.md):
+ *   - real drift between code/behavior and a contract claim   -> record_finding
+ *   - doc-only drift the loop can correct here                -> fix_in_place
+ *   - doc-only drift too large for this branch                -> route_followup
+ *   - cosmetic wording nit                                    -> ignore_cosmetic
+ *
+ * A coerced/invalid finding returns a structured invalid result rather than
+ * throwing (the module's contract is a structured result, never an exception).
+ *
+ * @param {object} finding
+ * @param {string} finding.kind - one of DOCS_GRILL_FINDING_KINDS
+ * @param {boolean} [finding.docOnly] - true when only docs (no code/behavior) diverge
+ * @param {boolean} [finding.fixableHere] - true when a doc-only fix is small enough for this branch
+ * @returns {{ ok: boolean, disposition?: string, status: string, reason: string, invalid?: string[] }}
+ */
+export function classifyDocsGrillFinding(finding = {}) {
+  if (!finding || typeof finding !== 'object') finding = {};
+  if (!DOCS_GRILL_FINDING_KINDS.includes(finding.kind)) {
+    return {
+      ok: false,
+      status: 'invalid_finding',
+      reason: 'unknown_finding_kind',
+      invalid: ['kind'],
+    };
+  }
+
+  if (finding.kind === 'cosmetic') {
+    return { ok: true, disposition: 'ignore_cosmetic', status: 'classified', reason: 'cosmetic_nit' };
+  }
+
+  // drift | stale_reference against live code/behavior is always recorded; the
+  // reason reflects the kind so downstream filtering stays accurate.
+  if (finding.docOnly !== true) {
+    const reason = finding.kind === 'stale_reference' ? 'stale_reference' : 'real_drift';
+    return { ok: true, disposition: 'record_finding', status: 'classified', reason };
+  }
+
+  // Doc-only drift: fix it here when small, otherwise route a follow-up.
+  if (finding.fixableHere === true) {
+    return { ok: true, disposition: 'fix_in_place', status: 'classified', reason: 'doc_only_fixable_here' };
+  }
+  return { ok: true, disposition: 'route_followup', status: 'classified', reason: 'doc_only_too_large' };
+}

package/scripts/loop/ensure-worktree.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/**
+ * Ensure a loop-owned worktree exists at its canonical namespaced path, then
+ * provision it (issue #909). This is the lifecycle entrypoint: create OR reuse
+ * the worktree, then copy/link the configured gitignored files in one step.
+ *
+ * - Canonical path comes from the shared resolveWorktreePath (namespaced
+ *   `tmp/worktrees/dev-loops/<kind>-<n>`), so create/provision/cleanup agree.
+ * - `git fetch <base-origin>` then `git worktree add` if absent. If a worktree
+ *   already exists at the exact path it is REUSED (idempotent); if one exists
+ *   there on a DIFFERENT branch it is a hard conflict (we never clobber).
+ * - Provisioning is invoked via the imported provisionWorktree core (shared
+ *   with provision-worktree.mjs's CLI) — not shelled out. It fails soft: a
+ *   provision warning never aborts the worktree.
+ * - Does NOT run npm install (out of scope).
+ *
+ * Prints a JSON result to stdout:
+ *   { ok, path, created|reused, provision: { actions, summary } }
+ * (`provision` is the full provisionWorktree() result, not just its summary.)
+ * A git create failure is a hard error (exit 1); provisioning is fail-soft.
+ */
+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 } from "@dev-loops/core/loop/handoff-envelope";
+import { provisionWorktree } from "./provision-worktree.mjs";
+import { canonicalize } from "./_worktree-path.mjs";
+
+const USAGE = `Usage:
+  ensure-worktree.mjs --repo-root <p> (--issue <n> | --pr <n>) [--branch <name>] [--base <ref>]
+Create (or reuse) a loop-owned worktree at its canonical namespaced path
+(tmp/worktrees/dev-loops/<kind>-<n>) and provision it in one step.
+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).
+Optional:
+  --branch <name>   Branch to create/check out (default: <kind>-<n>).
+  --base <ref>      Base ref for a new worktree (default: origin/main).
+  -h, --help        Show this help.
+Output (stdout, JSON):
+  { "ok": true, "path": <p>, "created": bool, "reused": bool,
+    "provision": { "actions": [...], "summary": {...} } }`.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 parseEnsureWorktreeCliArgs(argv) {
+  const options = {
+    help: false,
+    repoRoot: undefined,
+    issue: undefined,
+    pr: undefined,
+    branch: undefined,
+    base: "origin/main",
+  };
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      "repo-root": { type: "string" },
+      issue: { type: "string" },
+      pr: { type: "string" },
+      branch: { type: "string" },
+      base: { 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 === "branch") {
+      options.branch = requireTokenValue(token, parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    if (token.name === "base") {
+      options.base = 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].filter((v) => v !== undefined);
+  if (selectors.length === 0) throw parseError("One of --issue or --pr is required");
+  if (selectors.length > 1) throw parseError("Provide exactly one of --issue or --pr");
+  return options;
+}
+
+/** Remote name from a base ref like "origin/main" → "origin". */
+function remoteFromBase(base) {
+  const slash = base.indexOf("/");
+  return slash > 0 ? base.slice(0, slash) : "origin";
+}
+
+function runGit(gitCommand, args, cwd) {
+  return execFileSync(gitCommand, args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+/** True when a local branch ref already exists (non-zero exit → absent). */
+function branchExists(gitCommand, branch, cwd) {
+  try {
+    runGit(gitCommand, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], cwd);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Parse `git worktree list --porcelain` into [{ path, branch }]. Branch is the
+ * short ref (refs/heads/foo → foo) or null for a detached/bare entry.
+ */
+function parseWorktreeList(porcelain) {
+  const entries = [];
+  let cur = null;
+  for (const line of porcelain.split("\n")) {
+    if (line.startsWith("worktree ")) {
+      cur = { path: line.slice("worktree ".length).trim(), branch: null };
+      entries.push(cur);
+    } else if (cur && line.startsWith("branch ")) {
+      cur.branch = line.slice("branch ".length).trim().replace(/^refs\/heads\//, "");
+    }
+  }
+  return entries;
+}
+
+export async function ensureWorktree(
+  { repoRoot, issue, pr, branch, base = "origin/main" },
+  { gitCommand = "git", provision = provisionWorktree } = {},
+) {
+  const root = path.resolve(repoRoot);
+  const kind = issue !== undefined ? "issue" : "pr";
+  const number = issue !== undefined ? issue : pr;
+  const target = resolveWorktreePath({ repoRoot: root, kind, number });
+  const wantBranch = branch || `${kind}-${number}`;
+
+  // Idempotency / conflict check BEFORE any mutation.
+  const list = parseWorktreeList(runGit(gitCommand, ["worktree", "list", "--porcelain"], root));
+  const canonicalTarget = canonicalize(target);
+  const existing = list.find((e) => canonicalize(e.path) === canonicalTarget);
+  if (existing) {
+    if (existing.branch && existing.branch !== wantBranch) {
+      // Hard conflict — never clobber an unrelated worktree at our path.
+      throw new Error(
+        `worktree conflict: ${target} already checked out on branch "${existing.branch}", not "${wantBranch}"`,
+      );
+    }
+    // Reuse: still (re-)provision — provisioning is idempotent.
+    const summary = await provision({ worktreePath: target, repoRoot: root });
+    return { ok: true, path: target, created: false, reused: true, provision: summary };
+  }
+
+  // Create. fetch is best-effort (offline reuse of a local base ref still works),
+  // but `git worktree add` failing is a HARD error.
+  try {
+    runGit(gitCommand, ["fetch", remoteFromBase(base)], root);
+  } catch (err) {
+    process.stderr.write(`[ensure-worktree] WARN fetch failed (continuing): ${(err.stderr ?? err.message ?? "").toString().trim()}\n`);
+  }
+  // The branch may already exist (worktree removed but branch left behind). `git
+  // worktree add -b` fails on an existing branch, so attach to it instead; only
+  // create-from-base when the branch is genuinely new.
+  if (branchExists(gitCommand, wantBranch, root)) {
+    runGit(gitCommand, ["worktree", "add", target, wantBranch], root);
+  } else {
+    runGit(gitCommand, ["worktree", "add", "-b", wantBranch, target, base], root);
+  }
+
+  const summary = await provision({ worktreePath: target, repoRoot: root });
+  return { ok: true, path: target, created: true, reused: false, provision: summary };
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseEnsureWorktreeCliArgs(argv);
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return;
+  }
+  const result = await ensureWorktree(options);
+  stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}