dev-loops 0.2.7 → 0.4.0

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;
+  });
+}

package/scripts/loop/outer-loop.mjs

@@ -72,7 +72,7 @@ Stop reasons:
 Async-start contract:
   This loop must run within a visible harness-managed async context when
   workflow.asyncStartMode is set to required (default). It fails closed unless
-  DEVLOOPS_RUN_ID (or the PI_SUBAGENT_RUN_ID alias) is set, to prevent hidden detached-process fallback
+  DEVLOOPS_RUN_ID is set, to prevent hidden detached-process fallback
   (nohup, disowned shell jobs, etc.). Snapshot/test input mode
   (both --copilot-input and --reviewer-input) is exempt. Any relaxed
   async-start posture is maintainer-controlled repository policy, not an

package/scripts/loop/pr-runner-coordination.mjs

@@ -19,7 +19,7 @@ const USAGE = `Usage:
   pr-runner-coordination.mjs release --repo <owner/name> --pr <number> [--run-id <id>]
 Durable one-runner-per-PR coordination helper.
 If --run-id is omitted for claim/assert/release/takeover, DEVLOOPS_RUN_ID is used
-(falling back to the PI_SUBAGENT_RUN_ID alias).
+(via DEVLOOPS_RUN_ID).
 Output:
   stdout: { "ok": true, ... }
   stderr: { "ok": false, "error": "...", ... }

package/scripts/loop/pre-flight-gate.mjs

@@ -12,7 +12,7 @@ import {
   isListedWorktree,
   detectSubagentAvailability,
 } from "@dev-loops/core/loop/worktree-guard";
-const PI_PREFLIGHT_BYPASS_VAR = "PI_PREFLIGHT_BYPASS";
+const DEVLOOPS_PREFLIGHT_BYPASS_VAR = "DEVLOOPS_PREFLIGHT_BYPASS";
 const USAGE = `Usage:
   pre-flight-gate.mjs [--expected-branch <name>] [--check-subagents]
 Gate local implementation mutations before planning or editing.
@@ -28,7 +28,7 @@ Violation output (stderr, JSON, exit 1):
   { "ok": false, "error": "<error_code>", "checks": { ... },
     "guidance": "<actionable instruction for the agent>" }
 Bypass:
-  PI_PREFLIGHT_BYPASS=1   Skip all checks (for development/testing only).`.trim();
+  DEVLOOPS_PREFLIGHT_BYPASS=1   Skip all checks (for development/testing only).`.trim();
 const parseError = buildParseError(USAGE);
 export function parsePreFlightGateCliArgs(argv) {
   const options = {
@@ -95,7 +95,8 @@ function checkWorktreeIsolation({ cwd, env, gitCommand = "git" }) {
         guidance:
           `Current directory appears to be the main git checkout (${mainWorktreePath}).\n` +
           "Local implementation requires worktree isolation. Create a worktree:\n" +
-          "  git worktree add -b <branch> tmp/worktrees/<slug>/ origin/main\n" +
+          "  node scripts/loop/ensure-worktree.mjs --repo-root <main> --issue <n>\n" +
+          "  (creates+provisions tmp/worktrees/dev-loops/<kind>-<n> from origin/main)\n" +
           "Then re-run from the worktree directory.",
         mainWorktreePath,
       };
@@ -105,7 +106,8 @@ function checkWorktreeIsolation({ cwd, env, gitCommand = "git" }) {
       error: "not_in_worktree",
       guidance:
         "Local implementation requires worktree isolation. Create a worktree:\n" +
-        "  git worktree add -b <branch> tmp/worktrees/<slug>/ origin/main\n" +
+        "  node scripts/loop/ensure-worktree.mjs --repo-root <main> --issue <n>\n" +
+        "  (creates+provisions tmp/worktrees/dev-loops/<kind>-<n> from origin/main)\n" +
         "Then re-run from the worktree directory.",
       mainWorktreePath: mainWorktreePath ?? undefined,
     };
@@ -118,7 +120,8 @@ function checkWorktreeIsolation({ cwd, env, gitCommand = "git" }) {
       guidance:
         "Current directory is under tmp/worktrees/ but is not a real git worktree.\n" +
         "Create a worktree with:\n" +
-        "  git worktree add -b <branch> tmp/worktrees/<slug>/ origin/main\n" +
+        "  node scripts/loop/ensure-worktree.mjs --repo-root <main> --issue <n>\n" +
+        "  (creates+provisions tmp/worktrees/dev-loops/<kind>-<n> from origin/main)\n" +
         "Then re-run from the worktree directory.",
       mainWorktreePath: mainWorktreePath ?? undefined,
     };
@@ -180,11 +183,11 @@ export async function runCli(
     stdout.write(`${USAGE}\n`);
     return { ok: true, help: true };
   }
-  if ((effectiveEnv[PI_PREFLIGHT_BYPASS_VAR] ?? "").trim() === "1") {
+  if ((effectiveEnv[DEVLOOPS_PREFLIGHT_BYPASS_VAR] ?? "").trim() === "1") {
     const payload = {
       ok: true,
       checks: { worktree: true, branch: "skipped", subagents: "skipped" },
-      summary: "pre-flight gate bypassed via PI_PREFLIGHT_BYPASS=1",
+      summary: "pre-flight gate bypassed via DEVLOOPS_PREFLIGHT_BYPASS=1",
     };
     stdout.write(`${JSON.stringify(payload)}\n`);
     return payload;

package/scripts/loop/pre-push-main-guard.mjs

@@ -3,7 +3,7 @@ import { createInterface } from "node:readline";
 import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
 import { parseArgs } from "node:util";
 
-const PI_PREPUSH_BYPASS_VAR = "PI_PREPUSH_BYPASS";
+const DEVLOOPS_PREPUSH_BYPASS_VAR = "DEVLOOPS_PREPUSH_BYPASS";
 const BLOCKED_REFS = ["refs/heads/main"];
 
 const USAGE = `Usage:
@@ -17,7 +17,7 @@ Exit codes:
   1  Push blocked (target is a protected ref)
 
 Bypass:
-  PI_PREPUSH_BYPASS=1   Skip all checks (for emergencies only).
+  DEVLOOPS_PREPUSH_BYPASS=1   Skip all checks (for emergencies only).
                          Preferred: push a feature branch and open a PR.`.trim();
 
 const parseError = buildParseError(USAGE);
@@ -88,8 +88,8 @@ export async function runCli(argv = process.argv.slice(2), { stdout = process.st
   const options = parsePrePushGuardCliArgs(argv);
   if (options.help) { stdout.write(`${USAGE}\n`); return { ok: true, help: true }; }
 
-  if (env[PI_PREPUSH_BYPASS_VAR] === "1") {
-    stdout.write(JSON.stringify({ ok: true, bypassed: true, reason: `${PI_PREPUSH_BYPASS_VAR}=1` }) + "\n");
+  if ((env[DEVLOOPS_PREPUSH_BYPASS_VAR] ?? "").trim() === "1") {
+    stdout.write(JSON.stringify({ ok: true, bypassed: true, reason: `${DEVLOOPS_PREPUSH_BYPASS_VAR}=1` }) + "\n");
     return { ok: true, bypassed: true };
   }
 

package/scripts/loop/provision-worktree.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * Provision a freshly-created worktree with the gitignored files/dirs the app
+ * and tests need, copied/symlinked from the main checkout per `.devloops`
+ * `worktree.copyOnInit` / `worktree.linkOnInit` (issue #909).
+ *
+ * - Sources resolve against the main checkout (`--repo-root`), never cwd.
+ * - Entries are repo-relative literal paths OR glob patterns (native fsp.glob).
+ * - copy = `fs.cp(recursive)`; link = absolute symlink into the main checkout.
+ * - Every resolved source MUST resolve inside the main checkout (traversal guard).
+ * - Fail-soft: a missing source / empty glob logs one warning and continues.
+ * - Idempotent: skips a dest that is already correct.
+ * - Does NOT run npm install (deps belong to `npm ci`-in-worktree).
+ *
+ * Prints a JSON summary of actions to stdout. Never throws on a per-entry
+ * problem; exits 0 unless its own arguments are invalid.
+ */
+import fsp from "node:fs/promises";
+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 { loadDevLoopConfig, resolveWorktreeConfig } from "@dev-loops/core/config";
+
+const USAGE = `Usage:
+  provision-worktree.mjs --worktree-path <p> --repo-root <p>
+Provision a worktree with gitignored files/dirs from the main checkout,
+driven by .devloops worktree.copyOnInit / worktree.linkOnInit.
+Required:
+  --worktree-path <p>   Absolute path to the target worktree.
+  --repo-root <p>       Absolute path to the main checkout (source of files).
+Optional:
+  -h, --help            Show this help.
+Output (stdout, JSON):
+  { "ok": true, "actions": [ { "mode": "copy"|"link"|"skip"|"reject", ... } ],
+    "summary": { "copied": n, "linked": n, "skipped": n, "rejected": n,
+                 "warnings": n } }`.trim();
+
+const parseError = buildParseError(USAGE);
+
+export function parseProvisionWorktreeCliArgs(argv) {
+  const options = { help: false, worktreePath: undefined, repoRoot: undefined };
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      "worktree-path": { type: "string" },
+      "repo-root": { 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 === "worktree-path") {
+      options.worktreePath = requireTokenValue(token, parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    if (token.name === "repo-root") {
+      options.repoRoot = requireTokenValue(token, parseError, { flagPattern: /^-/u });
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (!options.worktreePath) throw parseError("Missing required --worktree-path");
+  if (!options.repoRoot) throw parseError("Missing required --repo-root");
+  return options;
+}
+
+/**
+ * Resolve a repo-relative entry (literal or glob) to matched absolute sources
+ * inside repoRoot. Returns `{ matches: string[], traversal: string[] }`.
+ * `traversal` holds matches that escaped repoRoot (rejected by caller).
+ */
+async function expandEntry(entry, repoRoot) {
+  const matches = [];
+  const traversal = [];
+  const isGlob = /[*?[\]{}]/.test(entry);
+  const inside = (abs) => abs === repoRoot || abs.startsWith(repoRoot + path.sep);
+
+  if (isGlob) {
+    // native fsp.glob (Node >=22) — expand against the main checkout.
+    for await (const rel of fsp.glob(entry, { cwd: repoRoot })) {
+      const abs = path.resolve(repoRoot, rel);
+      (inside(abs) ? matches : traversal).push(abs);
+    }
+  } else {
+    const abs = path.resolve(repoRoot, entry);
+    (inside(abs) ? matches : traversal).push(abs);
+  }
+  return { matches, traversal };
+}
+
+async function pathExists(p) {
+  try {
+    await fsp.lstat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The lexical `inside()` guard in expandEntry can't see through symlinks: a
+ * source that is itself a symlink (or sits under a symlinked dir) pointing
+ * OUTSIDE repoRoot resolves clean lexically but escapes on realpath. Re-check
+ * the realpath here BEFORE any copy/link. Returns true when the resolved
+ * source is genuinely inside repoRoot. Non-existent source → treat as inside
+ * (the copy/link helpers handle missing sources with their own warning).
+ */
+async function realpathInside(src, repoRoot) {
+  let real;
+  try {
+    real = await fsp.realpath(src);
+  } catch {
+    return true; // missing/broken — let the copy/link helper report it
+  }
+  const realRoot = await fsp.realpath(repoRoot).catch(() => repoRoot);
+  return real === realRoot || real.startsWith(realRoot + path.sep);
+}
+
+/** Copy: idempotent skip when dest already exists (worktree reuse). */
+async function provisionCopy(src, dest, logWarn) {
+  if (!(await pathExists(src))) {
+    logWarn(`copyOnInit source missing, skipping: ${src}`);
+    return { mode: "skip", reason: "source-missing", src, dest };
+  }
+  if (await pathExists(dest)) return { mode: "skip", reason: "exists", src, dest };
+  await fsp.mkdir(path.dirname(dest), { recursive: true });
+  await fsp.cp(src, dest, { recursive: true });
+  return { mode: "copy", src, dest };
+}
+
+/** Symlink: absolute link into the main checkout. Idempotent when correct. */
+async function provisionLink(src, dest, logWarn) {
+  if (!(await pathExists(src))) {
+    logWarn(`linkOnInit source missing, skipping: ${src}`);
+    return { mode: "skip", reason: "source-missing", src, dest };
+  }
+  const existing = await fsp.readlink(dest).catch(() => null);
+  if (existing !== null) {
+    if (path.resolve(path.dirname(dest), existing) === src) {
+      return { mode: "skip", reason: "exists", src, dest };
+    }
+    return { mode: "skip", reason: "dest-conflict", src, dest };
+  }
+  if (await pathExists(dest)) return { mode: "skip", reason: "dest-conflict", src, dest };
+  await fsp.mkdir(path.dirname(dest), { recursive: true });
+  await fsp.symlink(src, dest); // absolute target — survives worktree moves under tmp/
+  return { mode: "link", src, dest };
+}
+
+export async function provisionWorktree({ worktreePath, repoRoot }, { loadConfig = loadDevLoopConfig } = {}) {
+  const root = path.resolve(repoRoot);
+  const dst = path.resolve(worktreePath);
+  const actions = [];
+  const warnings = [];
+  const logWarn = (msg) => {
+    warnings.push(msg);
+    process.stderr.write(`[provision-worktree] WARN ${msg}\n`);
+  };
+
+  // Fail-closed (repo convention): a config that failed to load/validate is
+  // treated as EMPTY — zero provisioning actions, one WARN. We never act on an
+  // unvalidated config (a bad entry could copy/link the wrong source).
+  const { config, errors } = await loadConfig({ repoRoot: root });
+  const safeConfig = errors && errors.length > 0 ? null : config;
+  if (safeConfig === null && errors && errors.length > 0) {
+    logWarn(`dev-loop config invalid (${errors.length} error(s)) — provisioning EMPTY config (no copy/link)`);
+  }
+  const { copyOnInit, linkOnInit } = resolveWorktreeConfig(safeConfig);
+
+  for (const [entries, kind] of [[copyOnInit, "copy"], [linkOnInit, "link"]]) {
+    for (const entry of entries) {
+      const { matches, traversal } = await expandEntry(entry, root);
+      for (const abs of traversal) {
+        logWarn(`rejected (outside main checkout): ${entry} → ${abs}`);
+        actions.push({ mode: "reject", reason: "traversal", entry, src: abs });
+      }
+      if (matches.length === 0 && traversal.length === 0) {
+        logWarn(`no match for ${kind}OnInit entry: ${entry}`);
+        actions.push({ mode: "skip", reason: "no-match", entry });
+        continue;
+      }
+      for (const src of matches) {
+        // Symlink-aware traversal guard: a source whose realpath escapes the
+        // main checkout is rejected before any copy/link (the lexical inside()
+        // above cannot see through symlinks).
+        if (!(await realpathInside(src, root))) {
+          logWarn(`rejected (symlink escapes main checkout): ${entry} → ${src}`);
+          actions.push({ mode: "reject", reason: "traversal", entry, src });
+          continue;
+        }
+        const dest = path.join(dst, path.relative(root, src));
+        // Fail-soft per the header promise: a per-entry copy/link failure (e.g.
+        // EACCES, dest conflict the helper didn't catch) logs ONE WARN, records
+        // a skip action, and continues — it never aborts the whole run.
+        try {
+          const res = kind === "copy"
+            ? await provisionCopy(src, dest, logWarn)
+            : await provisionLink(src, dest, logWarn);
+          actions.push({ entry, ...res });
+        } catch (err) {
+          const msg = (err && err.message) ? err.message : String(err);
+          logWarn(`${kind} failed, skipping: ${src} → ${dest}: ${msg}`);
+          actions.push({ entry, mode: "skip", reason: `${kind}-failed: ${msg}`, src, dest });
+        }
+      }
+    }
+  }
+
+  const summary = { copied: 0, linked: 0, skipped: 0, rejected: 0, warnings: warnings.length };
+  for (const a of actions) {
+    if (a.mode === "copy") summary.copied++;
+    else if (a.mode === "link") summary.linked++;
+    else if (a.mode === "skip") summary.skipped++;
+    else if (a.mode === "reject") summary.rejected++;
+  }
+  return { ok: true, actions, summary };
+}
+
+export async function runCli(argv = process.argv.slice(2), { stdout = process.stdout } = {}) {
+  const options = parseProvisionWorktreeCliArgs(argv);
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return;
+  }
+  const result = await provisionWorktree(options);
+  stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/loop/resolve-dev-loop-startup.mjs

@@ -437,10 +437,10 @@ export function buildResolveDevLoopStartupResult(input, { adapter = createPiAdap
       return buildAsyncStartRejection(validation);
     }
   }
-  const PI_WORKTREE_BYPASS_VAR = "PI_WORKTREE_BYPASS";
+  const DEVLOOPS_WORKTREE_BYPASS_VAR = "DEVLOOPS_WORKTREE_BYPASS";
   if (
     strategyKey === "local_implementation" &&
-    (effectiveEnv[PI_WORKTREE_BYPASS_VAR] ?? "").trim() !== "1"
+    (effectiveEnv[DEVLOOPS_WORKTREE_BYPASS_VAR] ?? "").trim() !== "1"
   ) {
     try {
       const worktreeOutput = execFileSync("git", ["worktree", "list"], {
@@ -453,8 +453,8 @@ export function buildResolveDevLoopStartupResult(input, { adapter = createPiAdap
       const allPaths = parseAllWorktreePaths(worktreeOutput);
       if (!isUnderWorktreePath(effectiveCwd)) {
         const reason = mainPath !== null && isMainCheckout(effectiveCwd, mainPath)
-          ? `Local implementation requires worktree isolation. Current directory is the main git checkout (${mainPath}). Create a worktree under tmp/worktrees/<slug>/ and re-run.`
-          : "Local implementation requires worktree isolation. Current directory is not under tmp/worktrees/. Create a worktree and re-run.";
+          ? `Local implementation requires worktree isolation. Current directory is the main git checkout (${mainPath}). Run \`node scripts/loop/ensure-worktree.mjs --repo-root ${mainPath} --issue <n>\` to create+provision the worktree under tmp/worktrees/dev-loops/<kind>-<n>, then re-run from there.`
+          : "Local implementation requires worktree isolation. Current directory is not under tmp/worktrees/. Run `node scripts/loop/ensure-worktree.mjs --repo-root <main> --issue <n>` to create+provision a worktree under tmp/worktrees/dev-loops/<kind>-<n>, then re-run from there.";
         return {
           ok: true,
           bundleKind: "needs_reconcile",
@@ -466,7 +466,7 @@ export function buildResolveDevLoopStartupResult(input, { adapter = createPiAdap
         };
       }
       if (!isListedWorktree(effectiveCwd, allPaths)) {
-        const reason = `Local implementation requires worktree isolation. Current directory is under tmp/worktrees/ but is not listed as a git worktree by \`git worktree list\`. Create a proper worktree with \`git worktree add\` and re-run.`;
+        const reason = `Local implementation requires worktree isolation. Current directory is under tmp/worktrees/ but is not listed as a git worktree by \`git worktree list\`. Create a proper worktree with \`node scripts/loop/ensure-worktree.mjs --repo-root <main> --issue <n>\` and re-run.`;
         return {
           ok: true,
           bundleKind: "needs_reconcile",