mandrel 1.76.0 → 1.77.0

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

package/.agents/scripts/lib/orchestration/column-sync.js

@@ -35,6 +35,11 @@
  */
 
 import { AGENT_LABELS } from '../label-constants.js';
+import {
+  invalidateProjectMetaCache,
+  readProjectMetaCache,
+  writeProjectMetaCache,
+} from './project-meta-cache.js';
 import { resolveProjectMeta } from './project-meta-resolver.js';
 
 export const LABEL_TO_COLUMN = Object.freeze({
@@ -74,6 +79,7 @@ export class ColumnSync {
    *   projectNumber?: number | null,
    *   projectOwner?: string | null,
    *   logger?: { info: Function, warn: Function },
+   *   config?: object,
    *   ctx?: { provider?: object, config?: { github?: { projectNumber?: number|null } }, logger?: object },
    * }} opts
    */
@@ -89,7 +95,16 @@ export class ColumnSync {
       null;
     this.projectOwner = opts.projectOwner ?? provider.projectOwner ?? null;
     this.logger = opts.logger ?? ctx?.logger ?? console;
+    // Resolved config bag used to locate the on-disk meta cache's tempRoot.
+    // Optional — when omitted, the cache resolves the framework-default
+    // `temp` root (Story #4252).
+    this.config = opts.config ?? ctx?.config ?? undefined;
     this._meta = null; // lazy-cached { projectId, fieldId, options: Map<name, id> }
+    // Records whether the in-process `_meta` was hydrated from the on-disk
+    // cache, so a GraphQL error against possibly-stale cached metadata can
+    // invalidate the disk entry and force a fresh resolve on the next flip
+    // (Story #4252).
+    this._metaFromDiskCache = false;
   }
 
   /**
@@ -117,8 +132,9 @@ export class ColumnSync {
     const itemId = await this.#getProjectItemId(issueId, meta.projectId);
     if (!itemId) return { status: 'skipped', reason: 'not-on-project' };
 
-    await this.provider.graphql(
-      `
+    try {
+      await this.provider.graphql(
+        `
       mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
         updateProjectV2ItemFieldValue(
           input: {
@@ -129,18 +145,71 @@ export class ColumnSync {
           }
         ) { projectV2Item { id } }
       }`,
-      {
-        projectId: meta.projectId,
-        itemId,
-        fieldId: meta.fieldId,
-        optionId,
-      },
-    );
+        {
+          projectId: meta.projectId,
+          itemId,
+          fieldId: meta.fieldId,
+          optionId,
+        },
+      );
+    } catch (err) {
+      // A failed mutation against metadata that came from the disk cache
+      // most likely means the board was reconfigured since the entry was
+      // written (a stale projectId / fieldId / optionId). Invalidate the
+      // disk entry so the next flip re-resolves against the live board and
+      // self-heals (Story #4252). Re-throw so the caller's existing error
+      // handling (e.g. `syncProjectStatusColumn`'s warn) is preserved.
+      this.#invalidateMetaCache();
+      throw err;
+    }
     return { status: 'synced', column };
   }
 
+  /**
+   * The `(owner, projectNumber)` pair the disk cache is keyed by. Mirrors
+   * the owner that `#loadMeta` resolves the board against so a cache hit and
+   * a live resolve agree on the same board identity.
+   *
+   * @returns {{ owner: string|null, projectNumber: number|null }}
+   */
+  get #cacheBoard() {
+    return {
+      owner: this.projectOwner ?? this.provider.owner ?? null,
+      projectNumber: this.projectNumber,
+    };
+  }
+
+  /**
+   * Invalidate the on-disk metadata cache entry for this board and drop the
+   * in-process copy, so the next `#loadMeta` re-resolves from the live
+   * board. Only fires when the current `_meta` came from the disk cache —
+   * a freshly-resolved entry that fails the mutation is a transient/live
+   * problem, not a stale-cache problem.
+   */
+  #invalidateMetaCache() {
+    if (!this._metaFromDiskCache) return;
+    const { owner, projectNumber } = this.#cacheBoard;
+    invalidateProjectMetaCache({ owner, projectNumber, config: this.config });
+    this._meta = null;
+    this._metaFromDiskCache = false;
+  }
+
   async #loadMeta() {
     if (this._meta !== null) return this._meta || null;
+    // Disk cache hit short-circuits the ~2 metadata GraphQL round-trips
+    // (resolveProjectMeta) — repo-invariant board metadata persists across
+    // the cold CLI processes of a single-story delivery (Story #4252).
+    const cachedBoard = this.#cacheBoard;
+    const cached = readProjectMetaCache({
+      owner: cachedBoard.owner,
+      projectNumber: cachedBoard.projectNumber,
+      config: this.config,
+    });
+    if (cached) {
+      this._meta = cached;
+      this._metaFromDiskCache = true;
+      return this._meta;
+    }
     try {
       // Resolve the board by walking the owner-type ladder
       // (organization → user → viewer) via the shared resolver so the
@@ -176,6 +245,16 @@ export class ColumnSync {
         fieldId: field.id,
         options,
       };
+      // Persist the freshly-resolved, repo-invariant metadata so the next
+      // cold flip reads it from disk instead of re-paying the resolve
+      // (Story #4252). Best-effort: a write failure never blocks the sync.
+      writeProjectMetaCache({
+        owner: cachedBoard.owner,
+        projectNumber: cachedBoard.projectNumber,
+        meta: this._meta,
+        config: this.config,
+      });
+      this._metaFromDiskCache = false;
       return this._meta;
     } catch (err) {
       this.logger.warn?.(

package/.agents/scripts/lib/orchestration/lifecycle/listeners/automerge-armer.js

@@ -54,6 +54,8 @@
 
 import { spawnSync } from 'node:child_process';
 
+import { resolveAutoMergeArmCwd } from '../../auto-merge-cwd.js';
+
 /**
  * Default `gh pr view --json autoMergeRequest` probe. Pure-spawn helper
  * — exported so tests can stub the shell-out without touching the
@@ -77,12 +79,28 @@ export function ghPrViewAutoMerge({ prUrl, cwd, spawnFn = spawnSync }) {
  * helper. Exported so tests can stub. The arg list is captured in a
  * single helper so the merge-lockout lint allow-list narrows to one
  * literal site.
+ *
+ * Story #4282: `--delete-branch` makes `gh` shell out to local `git`
+ * (including a `git checkout <base>`). When this arm runs from a per-Story
+ * worktree cwd checked out on the head branch while the base branch is
+ * occupied by the primary worktree, that checkout collides
+ * (`fatal: '<base>' is already used by worktree`). We re-point the spawn
+ * cwd at the primary worktree root (which holds the base branch) via
+ * `resolveAutoMergeArmCwd`, so the local checkout is a no-op while
+ * `--delete-branch` (head-branch-removed-on-merge) is preserved. The
+ * resolver is non-fatal — it degrades to the original cwd.
  */
-export function ghPrMergeAuto({ prUrl, cwd, spawnFn = spawnSync }) {
+export function ghPrMergeAuto({
+  prUrl,
+  cwd,
+  spawnFn = spawnSync,
+  resolveArmCwd = resolveAutoMergeArmCwd,
+}) {
+  const armCwd = resolveArmCwd(cwd);
   const result = spawnFn(
     'gh',
     ['pr', 'merge', prUrl, '--auto', '--squash', '--delete-branch'],
-    { cwd, encoding: 'utf-8', shell: false },
+    { cwd: armCwd, encoding: 'utf-8', shell: false },
   );
   return {
     status: result.status ?? 1,