mandrel 1.76.0 → 1.78.0

package/.agents/scripts/lib/close-validation/runner.js

@@ -50,11 +50,18 @@ function applyChangedFileScope({ gate, spawnCwd, log }) {
   log(
     `[close-validation] ↳ ${gate.name} scoped to ${eligibleFiles.length} formatter-eligible changed file(s) from ${gate.changedFileScope.baseRef}...HEAD`,
   );
+  // The extension filter cannot see biome's own config-ignore axis
+  // (`files.includes` allowlist / `files.ignore` / `overrides`). When every
+  // eligible-by-extension path is also config-ignored, the scoped biome
+  // invocation exits 1 with "No files were processed" — a false negative for
+  // the gate (Story #4292). Flag the scoped run so the runner downgrades that
+  // specific exit to a clean skip instead of a formatting failure.
   return {
     gate,
     cmd: gate.cmd,
     args: [...args, ...eligibleFiles],
     skip: false,
+    tolerateNoFilesProcessed: true,
   };
 }
 
@@ -68,11 +75,18 @@ function applyChangedFileScope({ gate, spawnCwd, log }) {
  * `cwd` (the main checkout) because the per-Epic temp tree lives under
  * the main `.git/`. Failure messages name the worktree path.
  *
- * Evidence-aware: when both `storyId` and `epicId` are provided and
- * `useEvidence !== false`, each gate consults `validation-evidence
- * .shouldSkip()` against current HEAD + the gate's command-config hash. A
- * matching record skips the gate; a successful run is recorded so the
- * next caller in the local hot path can skip in turn.
+ * Evidence-aware: when `storyId` is provided alongside either `epicId` or
+ * `standalone: true`, and `useEvidence !== false`, each gate consults
+ * `validation-evidence.shouldSkip()` against current HEAD + the gate's
+ * command-config hash. A matching record skips the gate; a successful run
+ * is recorded so the next caller in the local hot path can skip in turn.
+ *
+ * Standalone keyspace (Story #4250): the standalone path has no parent
+ * Epic, so it passes `standalone: true` (and leaves `epicId` null) to route
+ * the evidence file to the storyId-anchored
+ * `<tempRoot>/standalone/stories/story-<id>/validation-evidence.json`
+ * keyspace instead of feeding a null `epicId` into the Epic-keyed path
+ * (which structurally disabled the cache before).
  *
  * `onGateStart` is invoked immediately before each gate's runner spawn.
  * story-close uses it to drive `phaseTimer.mark(...)` for per-gate
@@ -87,6 +101,7 @@ function applyChangedFileScope({ gate, spawnCwd, log }) {
  *   onGateStart?: (gate: Gate) => void,
  *   storyId?: number|null,
  *   epicId?: number|null,
+ *   standalone?: boolean,
  *   useEvidence?: boolean,
  *   evidenceClock?: () => number,
  *   getHeadSha?: (cwd: string) => string|null,
@@ -104,6 +119,7 @@ export async function runCloseValidation({
   onGateStart,
   storyId = null,
   epicId = null,
+  standalone = false,
   useEvidence = true,
   evidenceClock = () => Date.now(),
   getHeadSha = (resolvedCwd) => defaultGetHeadSha(resolvedCwd),
@@ -112,7 +128,15 @@ export async function runCloseValidation({
 } = {}) {
   const failed = [];
   const skipped = [];
-  const evidenceActive = useEvidence && storyId != null && epicId != null;
+  // Evidence is active when a Story id is present AND there is a keyspace to
+  // anchor on: either a real Epic id (Epic path) or `standalone: true`
+  // (Story #4250 — standalone storyId-anchored keyspace). A bare `epicId:
+  // null` without `standalone` keeps the cache off, as before.
+  const evidenceActive =
+    useEvidence && storyId != null && (epicId != null || standalone);
+  // The evidence-store opts: `standalone` routes to the storyId-anchored
+  // keyspace; otherwise the Epic-keyed path resolves under `epicId`.
+  const evidenceStoreOpts = { cwd, epicId, standalone };
   // Evidence keys against the main checkout's HEAD because the per-Epic
   // evidence file lives under the main `.git/`. Gate spawn, in contrast,
   // runs in the worktree when one is supplied — that's the whole point of
@@ -134,7 +158,7 @@ export async function runCloseValidation({
         configHash,
         inputFingerprint: gate.inputFingerprint ?? null,
       },
-      { cwd, epicId },
+      evidenceStoreOpts,
     );
     if (verdict.skip) {
       const tsHint = verdict.record?.timestamp
@@ -160,7 +184,7 @@ export async function runCloseValidation({
           durationMs,
           inputFingerprint: gate.inputFingerprint ?? null,
         },
-        { cwd, epicId },
+        evidenceStoreOpts,
       );
     } catch (err) {
       log(
@@ -192,6 +216,9 @@ export async function runCloseValidation({
       log,
       signal,
       ...(gate.env ? { env: gate.env } : {}),
+      ...(gate.tolerateNoFilesProcessed
+        ? { tolerateNoFilesProcessed: true }
+        : {}),
     });
     return { status: result?.status ?? 1 };
   };
@@ -238,7 +265,12 @@ export async function runCloseValidation({
     let result;
     try {
       result = await dispatchGate(
-        { ...gate, cmd: execution.cmd, args: execution.args },
+        {
+          ...gate,
+          cmd: execution.cmd,
+          args: execution.args,
+          tolerateNoFilesProcessed: execution.tolerateNoFilesProcessed,
+        },
         ac.signal,
       );
     } catch (err) {
@@ -304,6 +336,7 @@ export async function runCloseValidation({
       ...gate,
       cmd: execution.cmd,
       args: execution.args,
+      tolerateNoFilesProcessed: execution.tolerateNoFilesProcessed,
     });
     if (result.status !== 0) {
       failed.push({ gate, status: result.status, cwd: spawnCwd });

package/.agents/scripts/lib/config/temp-paths.js

@@ -128,7 +128,7 @@ export function _clearMainCheckoutRootCache() {
  * @param {string} tempRoot
  * @returns {string}
  */
-function anchorTempRoot(tempRoot) {
+export function anchorTempRoot(tempRoot) {
   if (path.isAbsolute(tempRoot)) return tempRoot;
   const root = mainCheckoutRoot();
   return root ? path.join(root, tempRoot) : tempRoot;

package/.agents/scripts/lib/config/worktree-isolation.js

@@ -10,10 +10,26 @@
  * silently disabling worktrees when the operator omitted the block).
  */
 
+/**
+ * Default `nodeModulesStrategy`, platform-aware (Story #4249).
+ *
+ * darwin/linux default to `clone` — a copy-on-write (clonefile/reflink) clone
+ * of the donor's `node_modules` that is effectively free in time and disk on
+ * APFS / reflink-capable filesystems, with a clean fall-back to `per-worktree`
+ * on any failure (unsupported fs, cross-volume, etc.). Windows has no reflink
+ * equivalent on this path, so it keeps the `per-worktree` install default.
+ *
+ * @param {NodeJS.Platform} [platform]
+ * @returns {'clone' | 'per-worktree'}
+ */
+export function defaultNodeModulesStrategy(platform = process.platform) {
+  return platform === 'win32' ? 'per-worktree' : 'clone';
+}
+
 export const WORKTREE_ISOLATION_DEFAULTS = Object.freeze({
   enabled: true,
   root: '.worktrees',
-  nodeModulesStrategy: 'per-worktree',
+  nodeModulesStrategy: defaultNodeModulesStrategy(),
   primeFromPath: null,
   allowSymlinkOnWindows: false,
   reapOnSuccess: true,
@@ -55,8 +71,7 @@ export function getWorktreeIsolation(config) {
         ? wi.enabled
         : WORKTREE_ISOLATION_DEFAULTS.enabled,
     root: wi.root ?? WORKTREE_ISOLATION_DEFAULTS.root,
-    nodeModulesStrategy:
-      wi.nodeModulesStrategy ?? WORKTREE_ISOLATION_DEFAULTS.nodeModulesStrategy,
+    nodeModulesStrategy: wi.nodeModulesStrategy ?? defaultNodeModulesStrategy(),
     primeFromPath:
       wi.primeFromPath === undefined
         ? WORKTREE_ISOLATION_DEFAULTS.primeFromPath

package/.agents/scripts/lib/config-resolver.js

@@ -63,7 +63,10 @@ export {
 } from './config/runtime.js';
 export { resolveListValue } from './config/shared.js';
 export { validateOrchestrationConfig } from './config/validate-orchestration.js';
-export { WORKTREE_ISOLATION_DEFAULTS } from './config/worktree-isolation.js';
+export {
+  defaultNodeModulesStrategy,
+  WORKTREE_ISOLATION_DEFAULTS,
+} from './config/worktree-isolation.js';
 export { PROJECT_ROOT } from './project-root.js';
 
 // Cache keyed by absolute root path so callers passing different cwds

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -105,7 +105,7 @@ const WORKTREE_ISOLATION_SCHEMA = {
     root: { type: 'string', minLength: 1 },
     nodeModulesStrategy: {
       type: 'string',
-      enum: ['per-worktree', 'symlink', 'pnpm-store'],
+      enum: ['per-worktree', 'clone', 'symlink', 'pnpm-store'],
     },
     primeFromPath: { type: ['string', 'null'], minLength: 1 },
     allowSymlinkOnWindows: { type: 'boolean' },

package/.agents/scripts/lib/git-branch-lifecycle.js

@@ -114,6 +114,96 @@ export function classifyBranchSeed({ localHas, remoteHas }) {
   return 'create';
 }
 
+/**
+ * Single-home for the story-branch seed-action *switch shell* that
+ * `single-story-init.js#seedStoryBranch` (standalone path) and
+ * `story-init/branch-initializer.js#ensureStoryBranchSeed` (Epic path) had
+ * each re-implemented (Story #4255). Both already delegated the (local,
+ * remote) decision to `classifyBranchSeed`; only the act-on-the-decision
+ * shell (reuse / fetch / create) was duplicated, and that shell was the
+ * drift surface for the seed-decision contract.
+ *
+ * The two callers differ in exactly two behavioural axes, both of which are
+ * parameters here — no other conditional branching is introduced:
+ *   - **`baseRef`** — the ref to branch from on `create` (`main` for the
+ *     standalone path, the Epic branch for the Epic path).
+ *   - **`swallowCreateRace`** — when `true`, a `git branch` that exits
+ *     non-zero with an "already exists" stderr is treated as reuse rather
+ *     than a fatal error (closes the probe→create race the Epic path runs
+ *     under concurrent wave dispatch). When `false`, any create failure
+ *     throws (the standalone path has no concurrent creator to race).
+ *
+ * The asymmetric surrounding wrappers (merged-sweep, fast-forward,
+ * donor-prime, workspace-verify, phase-timer) are deliberately NOT folded
+ * in — they stay in their respective callers.
+ *
+ * Caller-specific log lines and error text are passed in as the `messages`
+ * data bag so behaviour stays byte-identical to the pre-extraction switches.
+ * The git seams (`spawn`, `existsLocally`, `existsRemotely`) are injected so
+ * each caller can bind its own cwd (and tests can mock them).
+ *
+ * @param {object} opts
+ * @param {string} opts.storyBranch
+ * @param {string} opts.baseRef            Ref to branch from on `create`.
+ * @param {boolean} [opts.swallowCreateRace=false]
+ * @param {(args: string[]) => { status: number, stdout?: string, stderr?: string }} opts.spawn
+ * @param {(branch: string) => boolean} opts.existsLocally
+ * @param {(branch: string) => boolean} opts.existsRemotely
+ * @param {(level: string, message: string) => void} [opts.progress]
+ * @param {object} opts.messages
+ * @param {(b: string) => string} opts.messages.reuse
+ * @param {(b: string) => string} opts.messages.fetch
+ * @param {(b: string, ref: string) => string} opts.messages.create
+ * @param {(b: string) => string} [opts.messages.createRace]  Used when `swallowCreateRace`.
+ * @param {(b: string, ref: string, stderr: string) => string} opts.messages.createError
+ * @param {(b: string, stderr: string) => string} [opts.messages.fetchError]
+ *   When provided, a non-zero `fetch` exit throws with this message; when
+ *   omitted, the fetch exit status is not inspected.
+ */
+export function seedStoryBranchRef({
+  storyBranch,
+  baseRef,
+  swallowCreateRace = false,
+  spawn,
+  existsLocally,
+  existsRemotely,
+  progress = () => {},
+  messages,
+}) {
+  const action = classifyBranchSeed({
+    localHas: existsLocally(storyBranch),
+    remoteHas: existsRemotely(storyBranch),
+  });
+
+  if (action === 'local') {
+    progress('GIT', messages.reuse(storyBranch));
+    return;
+  }
+
+  if (action === 'fetch') {
+    progress('GIT', messages.fetch(storyBranch));
+    const r = spawn(['fetch', 'origin', `${storyBranch}:${storyBranch}`]);
+    if (messages.fetchError && r.status !== 0) {
+      throw new Error(
+        messages.fetchError(storyBranch, r.stderr || '(no stderr)'),
+      );
+    }
+    return;
+  }
+
+  // action === 'create'
+  progress('GIT', messages.create(storyBranch, baseRef));
+  const r = spawn(['branch', storyBranch, baseRef]);
+  if (r.status !== 0) {
+    const stderr = r.stderr || r.stdout || '';
+    if (swallowCreateRace && /already exists/i.test(stderr)) {
+      progress('GIT', messages.createRace(storyBranch));
+      return;
+    }
+    throw new Error(messages.createError(storyBranch, baseRef, stderr));
+  }
+}
+
 /**
  * Ensure an Epic branch exists and is published to `origin`. Handles all
  * four states of the (local, remote) matrix.

package/.agents/scripts/lib/loop-units/validate-loop-unit.js

@@ -0,0 +1,197 @@
+/**
+ * lib/loop-units/validate-loop-unit.js — loop-unit frontmatter validator.
+ *
+ * Parses a loop-unit markdown file's YAML frontmatter and AJV-validates
+ * it against `.agents/schemas/loop-unit.schema.json` (Ajv2020). Mirrors
+ * the validation pattern established by `lib/spec/loader.js` (Ajv2020 +
+ * ajv-formats + js-yaml, cached compiled validator, normalised
+ * `{ path, message }` issues).
+ *
+ * A "loop unit" is a markdown file under `.agents/workflows/loops/` whose
+ * leading `---`-fenced YAML frontmatter block defines a recurring unit of
+ * work (cadence, goal, conditional verify, round cap, exhaustion policy).
+ *
+ * Public surface:
+ *   • `parseFrontmatter(source)` → extracts and YAML-parses the leading
+ *     `---`-fenced block. Returns the parsed object (or `{}` for an empty
+ *     block). Throws `LoopUnitParseError` when the block is absent or the
+ *     YAML does not parse.
+ *   • `validateLoopUnit(filePath, opts?)` → reads the file, parses its
+ *     frontmatter, validates against the schema, and returns
+ *     `{ valid, issues, data }`. `issues` is an array of
+ *     `{ path, message }` (empty when valid). Never throws on a *validation*
+ *     failure — it reports it via `valid: false` — but does throw
+ *     `LoopUnitParseError` for an unreadable file or unparseable
+ *     frontmatter so callers can distinguish "structurally broken file"
+ *     from "schema-invalid unit".
+ *
+ * The module makes no GitHub calls and no process mutations; it is pure
+ * file I/O + schema validation. The `opts` bag accepts `{ schemaPath, fs }`
+ * so tests can point at a sandbox schema without monkey-patching globals.
+ */
+
+import {
+  existsSync as defaultExistsSync,
+  readFileSync as defaultReadFileSync,
+} from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import yaml from 'js-yaml';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// scripts/lib/loop-units/ → scripts/lib/ → scripts/ → .agents/
+const PROJECT_AGENTS_DIR = path.resolve(__dirname, '..', '..', '..');
+export const DEFAULT_SCHEMA_PATH = path.join(
+  PROJECT_AGENTS_DIR,
+  'schemas',
+  'loop-unit.schema.json',
+);
+
+const defaultFsAdapter = Object.freeze({
+  existsSync: defaultExistsSync,
+  readFileSync: defaultReadFileSync,
+});
+
+let cachedValidator = null;
+let cachedValidatorKey = null;
+
+/**
+ * Compile (and cache) the Ajv2020 validator for the loop-unit schema.
+ * Cached by absolute schema path so tests can swap to a sandbox schema.
+ *
+ * @param {string} schemaPath
+ * @param {{ readFileSync: typeof defaultReadFileSync }} fs
+ * @returns {(data: unknown) => boolean}
+ */
+function getValidator(schemaPath, fs) {
+  if (cachedValidator && cachedValidatorKey === schemaPath) {
+    return cachedValidator;
+  }
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+  cachedValidator = ajv.compile(schema);
+  cachedValidatorKey = schemaPath;
+  return cachedValidator;
+}
+
+/**
+ * Raised when a loop-unit file cannot be read, has no YAML frontmatter
+ * block, or the frontmatter does not parse as YAML.
+ */
+export class LoopUnitParseError extends Error {
+  /**
+   * @param {string} filePath
+   * @param {string} reason
+   */
+  constructor(filePath, reason) {
+    super(`Loop unit ${filePath} could not be parsed: ${reason}`);
+    this.name = 'LoopUnitParseError';
+    this.filePath = filePath;
+    this.reason = reason;
+  }
+}
+
+// Leading `---`-fenced YAML block. Tolerates CRLF and a leading BOM. The
+// closing fence is a `---` (or `...`) on its own line.
+const FRONTMATTER_RE = /^?---\r?\n([\s\S]*?)\r?\n(?:---|\.\.\.)\s*(?:\r?\n|$)/;
+
+/**
+ * Extract and YAML-parse the leading `---`-fenced frontmatter block from a
+ * markdown source string.
+ *
+ * @param {string} source        raw file contents
+ * @param {string} [filePath]    used only for error messages
+ * @returns {object}             the parsed frontmatter object (`{}` if empty)
+ * @throws {LoopUnitParseError}  when no fence is present or the YAML fails
+ */
+export function parseFrontmatter(source, filePath = '<string>') {
+  const match = FRONTMATTER_RE.exec(source);
+  if (!match) {
+    throw new LoopUnitParseError(
+      filePath,
+      'no YAML frontmatter block (expected a leading "---" fence)',
+    );
+  }
+  let parsed;
+  try {
+    parsed = yaml.load(match[1], { filename: filePath });
+  } catch (err) {
+    throw new LoopUnitParseError(
+      filePath,
+      `frontmatter is not valid YAML: ${err.message}`,
+    );
+  }
+  if (parsed == null) return {};
+  if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new LoopUnitParseError(
+      filePath,
+      'frontmatter must be a YAML mapping',
+    );
+  }
+  return parsed;
+}
+
+/**
+ * Convert Ajv's error array into a `{ path, message }` shape. For
+ * `required` errors Ajv leaves the missing property in
+ * `params.missingProperty` rather than the instance path, so we append it
+ * so the caller sees `/loop/verify` instead of `/loop` and the message
+ * names the missing field.
+ *
+ * @param {Array<{instancePath:string,message:string,keyword:string,params?:Record<string,unknown>}>} ajvErrors
+ * @returns {Array<{path:string,message:string}>}
+ */
+function normaliseAjvErrors(ajvErrors) {
+  return (ajvErrors ?? []).map((err) => {
+    let p = err.instancePath || '/';
+    let message = err.message ?? 'validation failed';
+    if (
+      err.keyword === 'required' &&
+      typeof err.params?.missingProperty === 'string'
+    ) {
+      const sep = p === '/' ? '' : '/';
+      p = `${p}${sep}${err.params.missingProperty}`;
+      message = `must have required property '${err.params.missingProperty}'`;
+    }
+    return { path: p, message };
+  });
+}
+
+/**
+ * Read, parse, and schema-validate a loop-unit markdown file.
+ *
+ * @param {string} filePath
+ * @param {{ schemaPath?: string, fs?: typeof defaultFsAdapter }} [opts]
+ * @returns {{ valid: boolean, issues: Array<{path:string,message:string}>, data: object }}
+ * @throws {LoopUnitParseError} when the file is unreadable or its
+ *   frontmatter is missing/unparseable.
+ */
+export function validateLoopUnit(filePath, opts = {}) {
+  const fs = opts.fs ?? defaultFsAdapter;
+  const schemaPath = opts.schemaPath ?? DEFAULT_SCHEMA_PATH;
+
+  if (!fs.existsSync(filePath)) {
+    throw new LoopUnitParseError(filePath, 'file does not exist');
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw new LoopUnitParseError(filePath, `unreadable: ${err.message}`);
+  }
+
+  const data = parseFrontmatter(raw, filePath);
+  const validate = getValidator(schemaPath, fs);
+  const ok = validate(data);
+
+  return {
+    valid: ok,
+    issues: ok ? [] : normaliseAjvErrors(validate.errors),
+    data,
+  };
+}

package/.agents/scripts/lib/mandrel-catalog.js

@@ -140,6 +140,42 @@ export function buildCatalog(workflowsDir) {
   return catalog;
 }
 
+/**
+ * Build the loop-unit catalog from a workflows directory's `loops/`
+ * namespace. Loop units live at `.agents/workflows/loops/<name>.md` and
+ * project to the namespaced `/loops:<name>` slash command (Story #4289).
+ * They are catalogued separately from the flat top-level commands because
+ * they carry a distinct invocation form.
+ *
+ * Returns an empty array when the `loops/` subdirectory is absent (the
+ * common case before the starter loops land in a later Story) — an absent
+ * namespace is a clean "no loop units", not an error.
+ *
+ * @param {string} workflowsDir — absolute path to `.agents/workflows/`.
+ * @returns {Array<{ name: string, description: string | null, vague: boolean }>}
+ */
+export function buildLoopCatalog(workflowsDir) {
+  const loopsDir = path.join(workflowsDir, 'loops');
+  if (!fs.existsSync(loopsDir)) return [];
+  const entries = fs.readdirSync(loopsDir, { withFileTypes: true });
+  const catalog = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    if (entry.name === 'README.md') continue;
+    const filePath = path.join(loopsDir, entry.name);
+    const source = fs.readFileSync(filePath, 'utf8');
+    const description = extractDescription(source);
+    catalog.push({
+      name: entry.name.replace(/\.md$/, ''),
+      description,
+      vague: isVagueDescription(description),
+    });
+  }
+  catalog.sort((a, b) => a.name.localeCompare(b.name));
+  return catalog;
+}
+
 /**
  * Render the catalog as a plain-markdown bullet list. Kept as a
  * lightweight alternative rendering of the same catalog backend that

package/.agents/scripts/lib/orchestration/auto-merge-cwd.js

@@ -0,0 +1,128 @@
+/**
+ * auto-merge-cwd.js — resolve a worktree-collision-safe cwd for arming
+ * GitHub native auto-merge (Story #4282).
+ *
+ * Root cause this module exists to defeat:
+ *   Arming auto-merge runs, in effect,
+ *   `gh pr merge <pr> --auto --squash --delete-branch`. The
+ *   `--delete-branch` flag makes `gh` shell out to local `git` to leave
+ *   and delete the PR head branch — including a `git checkout <base>` to
+ *   switch the working tree off the head branch. When the arm runs from a
+ *   per-Story worktree cwd (checked out on the head branch `story-<id>`)
+ *   while the base branch (`main`) is already occupied by the primary
+ *   worktree, `gh`'s internal `git checkout <base>` collides:
+ *
+ *     fatal: '<base>' is already used by worktree at '<primary>'
+ *
+ *   The arm fails (non-fatally), defeating the unattended auto-merge
+ *   contract — the operator must re-run the merge manually from a clean cwd.
+ *
+ * Fix (advisory direction #1 from the Story — "ensure the cwd is already
+ * on the base branch so gh's `git checkout <base>` is a no-op"):
+ *   Re-point the arm at the **primary worktree root** — the working tree
+ *   that holds the base branch — discovered via `git worktree list
+ *   --porcelain`. From the primary worktree, `gh`'s `--delete-branch`
+ *   cleanup never has to `git checkout <base>` (it is already there), so
+ *   the collision cannot occur. `--delete-branch` is preserved verbatim,
+ *   so the PR head branch is still removed on merge with no dependency on
+ *   the consumer's repo-level "auto-delete head branches" toggle.
+ *
+ * Non-fatal by construction: any failure to resolve the primary worktree
+ * (not a git repo, `git` missing, single-worktree layout, parse failure)
+ * degrades to returning the original `cwd` unchanged. Worst case is the
+ * pre-fix behaviour; this helper never throws and never blocks arming.
+ */
+
+import { gitSpawn as defaultGitSpawn } from '../git-utils.js';
+
+/**
+ * Parse `git worktree list --porcelain` output into structured records.
+ *
+ * The porcelain format emits one stanza per worktree, blank-line
+ * separated, e.g.:
+ *
+ *   worktree /abs/path/to/primary
+ *   HEAD <sha>
+ *   branch refs/heads/main
+ *
+ *   worktree /abs/path/to/.worktrees/story-4282
+ *   HEAD <sha>
+ *   branch refs/heads/story-4282
+ *
+ * A linked worktree with a detached HEAD emits `detached` instead of a
+ * `branch` line. Pure — exported for tests.
+ *
+ * @param {string} stdout
+ * @returns {Array<{ path: string, branch: string|null }>}
+ */
+export function parseWorktreeList(stdout) {
+  const text = String(stdout ?? '');
+  const records = [];
+  let current = null;
+  for (const rawLine of text.split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
+    if (line.startsWith('worktree ')) {
+      if (current) records.push(current);
+      current = { path: line.slice('worktree '.length).trim(), branch: null };
+    } else if (line.startsWith('branch ') && current) {
+      current.branch = line
+        .slice('branch '.length)
+        .trim()
+        .replace(/^refs\/heads\//, '');
+    }
+    // `HEAD <sha>`, `detached`, `bare`, `locked`, `prunable` lines carry
+    // no field we need; ignored.
+  }
+  if (current) records.push(current);
+  return records;
+}
+
+/**
+ * Pick the primary worktree from a parsed worktree list. The primary
+ * worktree is the first stanza `git worktree list` emits — it is the
+ * original (non-linked) working tree and, during delivery, the one that
+ * holds the base branch. Returns its absolute path, or `null` when the
+ * list is empty / unparseable.
+ *
+ * Pure — exported for tests.
+ *
+ * @param {Array<{ path: string, branch: string|null }>} records
+ * @returns {string|null}
+ */
+export function pickPrimaryWorktreePath(records) {
+  if (!Array.isArray(records) || records.length === 0) return null;
+  const first = records[0];
+  return first && typeof first.path === 'string' && first.path.length > 0
+    ? first.path
+    : null;
+}
+
+/**
+ * Resolve a worktree-collision-safe cwd for arming auto-merge.
+ *
+ * Returns the primary worktree root (which holds the base branch) when it
+ * can be discovered AND it differs from `cwd`; otherwise returns `cwd`
+ * unchanged. Never throws.
+ *
+ * @param {string} cwd — the cwd the caller would otherwise arm from
+ *   (often a per-Story worktree on the head branch).
+ * @param {{ gitSpawn?: typeof import('../git-utils.js').gitSpawn }} [deps]
+ * @returns {string} a cwd safe to run `gh pr merge --delete-branch` from.
+ */
+export function resolveAutoMergeArmCwd(
+  cwd,
+  { gitSpawn = defaultGitSpawn } = {},
+) {
+  if (typeof cwd !== 'string' || cwd.length === 0) return cwd;
+  try {
+    const result = gitSpawn(cwd, 'worktree', 'list', '--porcelain');
+    if (!result || result.status !== 0) return cwd;
+    const primary = pickPrimaryWorktreePath(parseWorktreeList(result.stdout));
+    if (!primary) return cwd;
+    return primary;
+  } catch {
+    // Any unexpected failure (git missing, non-repo cwd, etc.) degrades
+    // to the original cwd — arming stays best-effort.
+    return cwd;
+  }
+}