mandrel 1.76.0 → 1.77.0

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -1,5 +1,6 @@
 import { LIMITS_DEFAULTS } from '../config/limits.js';
 import {
+  AUTHORING_ALTITUDE_GUIDANCE,
   DEFAULT_TASK_SIZING,
   DELIVERABLE_GRANULARITY_GUIDANCE,
 } from '../orchestration/ticket-validator-sizing.js';
@@ -56,6 +57,15 @@ function render2TierPrompt({ maxTickets, maxTokenBudget }) {
   // cannot drift (Story #3777).
   const { definition: granularityDefinition, singleConsumerRule } =
     DELIVERABLE_GRANULARITY_GUIDANCE;
+  // The binding-vs-advisory authoring altitude + the New-File Contract are
+  // sourced from the single AUTHORING_ALTITUDE_GUIDANCE constant
+  // (ticket-validator-sizing.js) so the prompt and the authoring SKILL cannot
+  // drift (Story #4272).
+  const {
+    altitude: authoringAltitude,
+    advisoryCaveat,
+    newFileContract,
+  } = AUTHORING_ALTITUDE_GUIDANCE;
   return `You are an expert Senior Project Manager and Orchestrator.
 Your job is to take a Product Requirements Document (PRD) and a Technical Specification and decompose them into a flat list of Story tickets for an AI Agent to execute.
 
@@ -114,6 +124,10 @@ The serialized \`body\` string renders these markdown sections (in order):
     - {"path": "<read-only dependency path>", "assumption": "exists"}
     - ...
 
+    ## Non-Goals
+    - <a capability or change this Story explicitly does NOT deliver>
+    - ...
+
 #### STORY BODY RULES:
 
 - **goal** (in body string): One sentence stating WHY this story exists within the Epic.
@@ -122,6 +136,15 @@ The serialized \`body\` string renders these markdown sections (in order):
 - **verify** (top-level array on the ticket object): Each entry MUST name a testing tier in parentheses, drawn from \`unit\` / \`contract\` / \`e2e\` / \`validate\`. Example: \`npm run test -- src/x.test.ts (unit)\`, \`npm run validate (validate)\`. Stories with zero verify entries SHOULD fail validation; if a story is genuinely unverifiable in isolation (e.g., a copy edit auditor will eyeball), the literal entry \`manual:<reason>\` is allowed so the absence is intentional, not lazy. Manual entries without a reason are rejected.
 - **reason to exist** (REQUIRED, encoded as the \`reason_to_exist\` field of the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): One sentence stating the single coherent reason this Story exists, distinct from its broader \`## Goal\` prose. Every Story MUST carry a non-empty \`reason_to_exist\`; it is the machine-checkable form of the cohesion rule (**one Story = one coherent change with one reason to exist**) and the \`epic-plan-consolidate\` critic flags any Story whose body carries no non-empty reason to exist. Encode it as \`<!-- meta: {"reason_to_exist": "..."} -->\`.
 - **estimated_test_files** (optional, encoded in the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): Integer estimate of how many test files this Story creates or modifies. Omit when the number is not estimable. Informational only — it does not gate the decompose.
+- **non_goals** (OPTIONAL, in body string as the \`## Non-Goals\` section): A short list of capabilities or changes this Story explicitly does NOT deliver — an advisory negative-scope bound that fences the executing agent away from adjacent work. It is **advisory and NON-GATING**: the validator does not require, count, or reject on it, and an absent or empty section renders nothing. Use the EXACT single-word hyphenated heading spelling \`## Non-Goals\` (a space-separated heading like \`## Out of Scope\` is NOT recognized by the parser and will be dropped). Reach for it when a Story's negative boundary is non-obvious from its \`acceptance[]\` alone; omit it otherwise.
+
+#### AUTHORING ALTITUDE — BINDING ACCEPTANCE vs ADVISORY CHANGES:
+
+${authoringAltitude}
+
+${newFileContract}
+
+${advisoryCaveat}
 
 #### STORY SIZING — COHESION FIRST (the numeric ceiling is only a backstop):
 

package/.agents/scripts/lib/validation-evidence.js

@@ -103,25 +103,34 @@ function requirePositiveInt(value, label) {
  *   - `scopeId === epicId` → `<tempRoot>/epic-<epicId>/validation-evidence.json`
  *   - `scopeId !== epicId` → treated as a Story id → `<tempRoot>/epic-<epicId>/story-<scopeId>/validation-evidence.json`
  *
- * `epicId` is required. The legacy flat
- * `temp/validation-evidence-<scopeId>.json` layout is no longer supported —
- * callers must thread the Epic id through (Epic #1030 follow-up to Story
- * #1054). The synthetic config bag passed to `epicTempDir` keeps the
- * resolver from doing a disk-bound `.agentrc.json` lookup; bare callers can
- * pass `tempDir` via `opts` to override the default `'temp'`.
+ * **Standalone keyspace (Story #4250).** When `opts.standalone === true`,
+ * the Story has no parent Epic, so the evidence file is anchored on the
+ * Story id alone at
+ * `<tempRoot>/standalone/stories/story-<scopeId>/validation-evidence.json`
+ * (the `storyTempDir(null, sid)` layout from Story #2874). In this mode
+ * `epicId` is ignored — callers MUST NOT feed a `0`/`null` epicId into the
+ * Epic-keyed branch (the historical bug this keyspace replaces). Outside
+ * standalone mode `epicId` remains required.
+ *
+ * The legacy flat `temp/validation-evidence-<scopeId>.json` layout is no
+ * longer supported — Epic-scoped callers must thread the Epic id through
+ * (Epic #1030 follow-up to Story #1054). The synthetic config bag passed to
+ * `epicTempDir` / `storyTempDir` keeps the resolver from doing a disk-bound
+ * `.agentrc.json` lookup; bare callers can pass `tempDir` via `opts` to
+ * override the default `'temp'`.
  *
  * @param {number|string} scopeId
- * @param {{ cwd?: string, tempDir?: string, epicId: number|string }} opts
+ * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean }} opts
  * @returns {string}
  */
 export function evidencePath(scopeId, opts = {}) {
-  if (opts.epicId == null) {
+  const standalone = opts.standalone === true;
+  if (!standalone && opts.epicId == null) {
     throw new Error(
-      '[validation-evidence] evidencePath requires opts.epicId (Epic-scoped path resolution).',
+      '[validation-evidence] evidencePath requires opts.epicId (Epic-scoped path resolution) unless opts.standalone is set.',
     );
   }
   const { cwd, tempDir } = resolveOpts(opts);
-  const epicId = requirePositiveInt(opts.epicId, 'epicId');
   const scope = requirePositiveInt(scopeId, 'scopeId');
   // Bind the temp tree to the explicit `cwd` (Story #3900): pre-absolutise
   // the tempRoot under `cwd` and pass it through the canonical
@@ -134,10 +143,18 @@ export function evidencePath(scopeId, opts = {}) {
     ? tempDir
     : path.join(cwd, tempDir);
   const configBag = { project: { paths: { tempRoot: absTempRoot } } };
-  const dir =
-    scope === epicId
-      ? epicTempDir(epicId, configBag)
-      : storyTempDir(epicId, scope, configBag);
+  let dir;
+  if (standalone) {
+    // Story #4250 — storyId-anchored standalone keyspace. `null` is the
+    // standalone-story sentinel `storyTempDir` accepts (Story #2874).
+    dir = storyTempDir(null, scope, configBag);
+  } else {
+    const epicId = requirePositiveInt(opts.epicId, 'epicId');
+    dir =
+      scope === epicId
+        ? epicTempDir(epicId, configBag)
+        : storyTempDir(epicId, scope, configBag);
+  }
   return path.join(dir, EVIDENCE_FILENAME);
 }
 
@@ -172,15 +189,21 @@ function emptyDoc(scopeId) {
  * cross-scopeId cases — callers don't have to branch on those failure
  * modes; they manifest as `shouldSkip()` returning `skip: false`.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved.
+ * `opts.epicId` is required so the per-Epic-tree path can be resolved,
+ * unless `opts.standalone === true` (Story #4250) routes to the
+ * storyId-anchored standalone keyspace.
  *
  * @param {number|string} scopeId
- * @param {{ cwd?: string, tempDir?: string, epicId: number|string, fs?: object }} opts
+ * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object }} opts
  * @returns {{ storyId: number, schemaVersion: number, records: object[] }}
  */
 export function loadEvidence(scopeId, opts = {}) {
   const resolved = resolveOpts(opts);
-  const file = evidencePath(scopeId, { ...resolved, epicId: opts.epicId });
+  const file = evidencePath(scopeId, {
+    ...resolved,
+    epicId: opts.epicId,
+    standalone: opts.standalone,
+  });
   if (!resolved.fs.existsSync(file)) return emptyDoc(scopeId);
   let parsed;
   try {
@@ -200,7 +223,9 @@ export function loadEvidence(scopeId, opts = {}) {
  * Validates the resulting document against the schema before writing — a
  * malformed write throws so the bug surfaces immediately.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved.
+ * `opts.epicId` is required so the per-Epic-tree path can be resolved,
+ * unless `opts.standalone === true` (Story #4250) routes to the
+ * storyId-anchored standalone keyspace.
  *
  * @param {{
  *   storyId: number|string,
@@ -210,7 +235,7 @@ export function loadEvidence(scopeId, opts = {}) {
  *   exitCode?: number,
  *   durationMs?: number|null,
  * }} input
- * @param {{ cwd?: string, tempDir?: string, epicId: number|string, fs?: object, now?: Function }} opts
+ * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object, now?: Function }} opts
  * @returns {object} The persisted record.
  */
 export function recordPass(
@@ -231,7 +256,11 @@ export function recordPass(
     );
   }
   const resolved = resolveOpts(opts);
-  const evidenceOpts = { ...resolved, epicId: opts.epicId };
+  const evidenceOpts = {
+    ...resolved,
+    epicId: opts.epicId,
+    standalone: opts.standalone,
+  };
   const doc = loadEvidence(storyId, evidenceOpts);
   const record = {
     gateName,
@@ -268,10 +297,13 @@ export function recordPass(
  * with a machine-readable `reason` so callers can log why the skip didn't
  * fire.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved.
+ * `opts.epicId` is required so the per-Epic-tree path can be resolved,
+ * unless `opts.standalone === true` (Story #4250) routes to the
+ * storyId-anchored standalone keyspace. `opts` is forwarded verbatim to
+ * `loadEvidence`, so `standalone` flows through unchanged.
  *
  * @param {{ storyId: number|string, gateName: string, currentSha: string, configHash: string }} input
- * @param {{ cwd?: string, tempDir?: string, epicId: number|string, fs?: object }} opts
+ * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object }} opts
  * @returns {{ skip: boolean, reason: string, record?: object }}
  */
 export function shouldSkip(
@@ -308,15 +340,21 @@ export function shouldSkip(
  * start of each Story so a re-run always starts clean. Idempotent —
  * absent file is not an error.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved.
+ * `opts.epicId` is required so the per-Epic-tree path can be resolved,
+ * unless `opts.standalone === true` (Story #4250) routes to the
+ * storyId-anchored standalone keyspace.
  *
  * @param {number|string} scopeId
- * @param {{ cwd?: string, tempDir?: string, epicId: number|string, fs?: object }} opts
+ * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object }} opts
  * @returns {{ cleared: boolean, path: string }}
  */
 export function forceClear(scopeId, opts = {}) {
   const resolved = resolveOpts(opts);
-  const file = evidencePath(scopeId, { ...resolved, epicId: opts.epicId });
+  const file = evidencePath(scopeId, {
+    ...resolved,
+    epicId: opts.epicId,
+    standalone: opts.standalone,
+  });
   if (!resolved.fs.existsSync(file)) return { cleared: false, path: file };
   resolved.fs.unlinkSync(file);
   return { cleared: true, path: file };

package/.agents/scripts/lib/worktree/node-modules-strategy.js

@@ -7,6 +7,15 @@
  *
  *   - `per-worktree`  — run the project's package-manager install inside the
  *                       worktree (lock-file aware).
+ *   - `clone`         — copy-on-write (reflink/clonefile) clone of the donor's
+ *                       `node_modules` into the worktree (`cp -c` on darwin,
+ *                       `cp --reflink=auto` on linux). Effectively free in time
+ *                       and disk on APFS / reflink-capable filesystems. Falls
+ *                       back to `per-worktree` cleanly on any failure
+ *                       (unsupported filesystem, cross-volume clone, Windows).
+ *                       When the worktree's lockfile byte-matches the donor's
+ *                       and the donor's install markers are present, the
+ *                       per-tree install is skipped.
  *   - `symlink`       — symlink (or junction on Windows) the worktree's
  *                       `node_modules` to a donor worktree's copy. Refuses on
  *                       Windows unless `allowSymlinkOnWindows=true`.
@@ -14,10 +23,11 @@
  *                       shared content-addressable store.
  *
  * The context passed to each helper carries the minimum state the strategy
- * needs: config, platform, logger, and repoRoot (for `symlink`).
+ * needs: config, platform, logger, and repoRoot (for `symlink` / `clone`).
  */
 
 import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { detectPackageManager } from '../detect-package-manager.js';
@@ -28,6 +38,21 @@ function sleepSync(ms) {
   Atomics.wait(signal, 0, 0, ms);
 }
 
+/**
+ * Resolve the copy-on-write clone donor directory. Defaults to the repo root
+ * (the main checkout, which is primed by the host's own install) unless the
+ * operator pinned a `primeFromPath`.
+ *
+ * @param {{ config: object, repoRoot: string }} ctx
+ * @returns {string} Absolute donor path.
+ */
+function resolveCloneDonor(ctx) {
+  const primeFromPath = ctx.config?.primeFromPath;
+  return primeFromPath
+    ? path.resolve(ctx.repoRoot, primeFromPath)
+    : path.resolve(ctx.repoRoot);
+}
+
 /**
  * Apply the configured `nodeModulesStrategy` after a fresh worktree is added.
  * Called only during creation.
@@ -43,6 +68,11 @@ export function applyNodeModulesStrategy(ctx, wtPath) {
     case 'pnpm-store':
       return;
 
+    case 'clone': {
+      cloneNodeModules(ctx, wtPath);
+      return;
+    }
+
     case 'symlink': {
       const primeFromPath = ctx.config.primeFromPath;
       if (!primeFromPath) {
@@ -89,17 +119,106 @@ export function applyNodeModulesStrategy(ctx, wtPath) {
     default:
       throw new Error(
         `WorktreeManager: unknown nodeModulesStrategy '${strategy}'. ` +
-          'Expected per-worktree | symlink | pnpm-store.',
+          'Expected per-worktree | clone | symlink | pnpm-store.',
       );
   }
 }
 
+/**
+ * Copy-on-write clone the donor's `node_modules` into the worktree. On a
+ * reflink-capable filesystem (APFS on darwin, btrfs/XFS/etc. on linux) the
+ * clone is effectively free in both time and disk; the subsequent
+ * lockfile-match probe in `installDependencies` then skips the per-tree
+ * install entirely.
+ *
+ * Non-fatal by design: any failure (unsupported filesystem, cross-volume
+ * clone, Windows, missing donor) falls back to `per-worktree` cleanly — the
+ * worktree is simply left without a cloned `node_modules`, and the regular
+ * per-tree install runs. Failure NEVER throws; the clone is a fast-path
+ * optimization, not a correctness requirement.
+ *
+ * @param {{ config: object, platform: NodeJS.Platform, logger: object, repoRoot: string }} ctx
+ * @param {string} wtPath Absolute worktree path.
+ * @param {{ spawnFn?: typeof spawnSync, fsLike?: typeof fs }} [io] Injectable for tests.
+ * @returns {{ cloned: boolean, reason?: string }}
+ */
+export function cloneNodeModules(ctx, wtPath, io = {}) {
+  const spawnFn = io.spawnFn ?? spawnSync;
+  const fsLike = io.fsLike ?? fs;
+  // Key off the real host OS, not the test-injection `ctx.platform`, for the
+  // capability decision: Windows has no `cp -c`/`--reflink` equivalent here.
+  if (process.platform === 'win32') {
+    ctx.logger.info(
+      'worktree.node_modules strategy=clone fallback=per-worktree reason=windows-unsupported',
+    );
+    return { cloned: false, reason: 'windows-unsupported' };
+  }
+
+  const donor = resolveCloneDonor(ctx);
+  const donorNodeModules = path.join(donor, 'node_modules');
+  if (!fsLike.existsSync(donorNodeModules)) {
+    ctx.logger.info(
+      `worktree.node_modules strategy=clone fallback=per-worktree reason=donor-node-modules-missing donor=${donorNodeModules}`,
+    );
+    return { cloned: false, reason: 'donor-node-modules-missing' };
+  }
+
+  const target = path.join(wtPath, 'node_modules');
+  if (fsLike.existsSync(target)) {
+    // A worktree that already carries node_modules must not be clobbered by a
+    // clone-on-top (cp would nest into the existing dir). Treat as already
+    // populated and let the install-skip probe decide freshness.
+    ctx.logger.info(
+      `worktree.node_modules strategy=clone skip reason=target-exists target=${target}`,
+    );
+    return { cloned: false, reason: 'target-exists' };
+  }
+
+  // darwin: `cp -c` requests a clonefile (APFS). linux: `cp --reflink=auto`
+  // requests a reflink, silently degrading to a full copy on non-reflink
+  // filesystems — which we deliberately reject below so a slow full-tree copy
+  // never masquerades as a free clone.
+  const cloneArgs =
+    process.platform === 'darwin'
+      ? ['-c', '-R', donorNodeModules, target]
+      : ['--reflink=always', '-R', donorNodeModules, target];
+  const result = spawnFn('cp', cloneArgs, {
+    cwd: wtPath,
+    stdio: 'pipe',
+    encoding: 'utf-8',
+    timeout: 120_000,
+  });
+  if (result.status !== 0) {
+    // Clean up a partial copy so the per-worktree fallback install starts from
+    // a known-empty target.
+    try {
+      fsLike.rmSync(target, { recursive: true, force: true });
+    } catch {
+      // best-effort
+    }
+    ctx.logger.warn(
+      `worktree.node_modules strategy=clone fallback=per-worktree reason=clone-command-failed ` +
+        `(${describeAttemptFailure(result, 120_000)}) stderr=${(result.stderr ?? '').slice(0, 300)}`,
+    );
+    return { cloned: false, reason: 'clone-command-failed' };
+  }
+
+  ctx.logger.info(
+    `worktree.node_modules strategy=clone target=${target} source=${donorNodeModules}`,
+  );
+  return { cloned: true };
+}
+
 /**
  * Pure: pick the package-manager command + args for a given strategy and
  * worktree path. Returns `null` when the strategy is `symlink` (handled
  * elsewhere) or the worktree has no `package.json`.
  *
- * @param {string} strategy One of `per-worktree | pnpm-store | symlink`.
+ * `clone` shares `per-worktree`'s PM-detection: when the install is *not*
+ * skipped (lockfile mismatch), the worktree still installs with the project's
+ * detected package manager.
+ *
+ * @param {string} strategy One of `per-worktree | clone | pnpm-store | symlink`.
  * @param {string} wtPath Absolute worktree path.
  * @param {{ existsSync: (p: string) => boolean }} [fsLike] Injectable for tests.
  * @returns {{ cmd: string, args: string[] } | null}
@@ -112,6 +231,7 @@ export function selectInstallCommand(strategy, wtPath, fsLike = fs) {
     return { cmd: 'pnpm', args: ['install', '--frozen-lockfile'] };
   }
   // Shared lockfile probe (Story #4048 B3 — one implementation per concept).
+  // `per-worktree` and `clone` both fall through to PM detection here.
   const pm = detectPackageManager(wtPath, (p) => fsLike.existsSync(p)) ?? 'npm';
   if (pm === 'pnpm') {
     return { cmd: 'pnpm', args: ['install', '--frozen-lockfile'] };
@@ -138,14 +258,78 @@ const INSTALL_MARKERS = [
 
 const LOCKFILES = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'];
 
-function safeMtimeMs(fsLike, p) {
+/**
+ * Pure: locate the first present lockfile in `dir` and return its byte-exact
+ * SHA-256 hash, or `null` when no lockfile exists / cannot be read.
+ *
+ * The hash is the load-bearing freshness key for the install-skip decision —
+ * never an mtime, which clone (clonefile/reflink) does not preserve reliably
+ * and which is trivially perturbed by a no-op `git checkout`.
+ *
+ * @param {string} dir Absolute directory containing the lockfile.
+ * @param {{ existsSync: Function, readFileSync: Function }} [fsLike]
+ * @returns {string | null}
+ */
+export function lockfileHash(dir, fsLike = fs) {
+  const lockfile = LOCKFILES.map((l) => path.join(dir, l)).find((p) =>
+    fsLike.existsSync(p),
+  );
+  if (!lockfile) return null;
   try {
-    return fsLike.statSync(p).mtimeMs;
+    const bytes = fsLike.readFileSync(lockfile);
+    return crypto.createHash('sha256').update(bytes).digest('hex');
   } catch {
     return null;
   }
 }
 
+/**
+ * Pure: the single shared "is the per-tree install skippable?" predicate
+ * (generalized from `probeReusedInstall`). The install is safe to skip iff:
+ *
+ *   1. the worktree carries a completed-install marker
+ *      (`node_modules/<INSTALL_MARKERS>`), AND
+ *   2. the worktree's lockfile byte-exactly matches the donor's lockfile.
+ *
+ * The lockfile match is keyed on a byte-exact SHA-256 hash, NEVER mtime: a
+ * reflink/clonefile clone does not preserve mtime relationships, so an mtime
+ * comparison would either mis-skip a real change or force a redundant install
+ * on every clone. When the donor is omitted (reuse path, no clone donor), the
+ * worktree's own lockfile is hashed against itself — i.e. the lockfile-match
+ * leg is vacuously satisfied and only the marker presence gates the skip.
+ *
+ * @param {object} opts
+ * @param {string} opts.wtPath Absolute worktree path.
+ * @param {string} [opts.donorPath] Absolute donor path (the clone source).
+ * @param {{ existsSync: Function, readFileSync: Function }} [opts.fsLike]
+ * @returns {{ skippable: boolean, reason: string }}
+ */
+export function isInstallSkippable({ wtPath, donorPath, fsLike = fs }) {
+  const nmPath = path.join(wtPath, 'node_modules');
+  if (!fsLike.existsSync(nmPath)) {
+    return { skippable: false, reason: 'node-modules-missing' };
+  }
+  const marker = INSTALL_MARKERS.map((m) => path.join(nmPath, m)).find((p) =>
+    fsLike.existsSync(p),
+  );
+  if (!marker) {
+    return { skippable: false, reason: 'install-incomplete' };
+  }
+  const wtHash = lockfileHash(wtPath, fsLike);
+  if (wtHash === null) {
+    // No lockfile in the worktree — nothing to pin freshness against. The
+    // marker alone is the signal (matches a lockfile-less project).
+    return { skippable: true, reason: 'marker-present-no-lockfile' };
+  }
+  if (donorPath) {
+    const donorHash = lockfileHash(donorPath, fsLike);
+    if (donorHash !== null && donorHash !== wtHash) {
+      return { skippable: false, reason: 'lockfile-mismatch' };
+    }
+  }
+  return { skippable: true, reason: 'lockfile-match' };
+}
+
 /**
  * Pure: probe whether a **reused** worktree already carries a completed,
  * up-to-date install. Worktree reuse must not blindly report
@@ -157,12 +341,17 @@ function safeMtimeMs(fsLike, p) {
  *   - `{ status: 'skipped', reason: 'worktree-reused' }` — a completed
  *     install was detected (or the strategy never installs per-tree);
  *     safe to skip.
- *   - `{ status: 'failed', reason }` — missing/incomplete/stale install
- *     detected; callers should retry the install.
+ *   - `{ status: 'failed', reason }` — missing/incomplete install detected;
+ *     callers should retry the install.
  *
- * @param {string} strategy One of `per-worktree | pnpm-store | symlink`.
+ * Thin wrapper over the shared `isInstallSkippable` predicate (Story #4249 —
+ * one freshness predicate, keyed on a byte-exact lockfile hash, never mtime).
+ * The reuse path has no separate donor, so freshness reduces to marker
+ * presence (the worktree's own lockfile is its own baseline).
+ *
+ * @param {string} strategy One of `per-worktree | clone | pnpm-store | symlink`.
  * @param {string} wtPath Absolute worktree path.
- * @param {{ existsSync: Function, statSync: Function }} [fsLike] Injectable for tests.
+ * @param {{ existsSync: Function, readFileSync: Function }} [fsLike] Injectable for tests.
  * @returns {{ status: 'skipped' | 'failed', reason: string }}
  */
 export function probeReusedInstall(strategy, wtPath, fsLike = fs) {
@@ -173,34 +362,33 @@ export function probeReusedInstall(strategy, wtPath, fsLike = fs) {
   if (!fsLike.existsSync(path.join(wtPath, 'package.json'))) {
     return { status: 'skipped', reason: 'no-package-json' };
   }
-  const nmPath = path.join(wtPath, 'node_modules');
-  if (!fsLike.existsSync(nmPath)) {
-    return { status: 'failed', reason: 'reuse-node-modules-missing' };
-  }
-  const marker = INSTALL_MARKERS.map((m) => path.join(nmPath, m)).find((p) =>
-    fsLike.existsSync(p),
-  );
-  if (!marker) {
-    return { status: 'failed', reason: 'reuse-install-incomplete' };
-  }
-  const markerMtime = safeMtimeMs(fsLike, marker);
-  const lockfile = LOCKFILES.map((l) => path.join(wtPath, l)).find((p) =>
-    fsLike.existsSync(p),
-  );
-  if (lockfile && markerMtime !== null) {
-    const lockMtime = safeMtimeMs(fsLike, lockfile);
-    if (lockMtime !== null && lockMtime > markerMtime) {
-      return { status: 'failed', reason: 'reuse-node-modules-stale' };
-    }
+  const probe = isInstallSkippable({ wtPath, fsLike });
+  if (probe.skippable) {
+    return { status: 'skipped', reason: 'worktree-reused' };
   }
-  return { status: 'skipped', reason: 'worktree-reused' };
+  return {
+    status: 'failed',
+    reason:
+      probe.reason === 'node-modules-missing'
+        ? 'reuse-node-modules-missing'
+        : 'reuse-install-incomplete',
+  };
 }
 
-/** Pure: retry policy keyed off the chosen command. pnpm gets 3× + 5min. */
+/**
+ * Pure: retry policy keyed off the chosen command. pnpm gets 3× + 5min.
+ *
+ * Story #4249: npm/yarn now get a real `maxAttempts` of 2 (was 1). The
+ * formerly hardcoded `npm ci` retry inside `runStoryInitPrepare` was deleted
+ * in the same change; this in-`ensure` retry budget is what compensates so
+ * npm install reliability does not regress — a transient first-attempt
+ * failure now retries here, with the correct (PM-detected) command, instead
+ * of an unconditional `npm ci` re-run after init.
+ */
 export function installRetryPolicy(cmd) {
   const isPnpm = cmd === 'pnpm';
   return {
-    maxAttempts: isPnpm ? 3 : 1,
+    maxAttempts: isPnpm ? 3 : 2,
     timeoutMs: isPnpm ? 300_000 : 120_000,
     backoffMs: [0, 2_000, 5_000],
   };
@@ -387,6 +575,26 @@ export function installDependencies(ctx, wtPath) {
   if (selection === null) {
     return { status: 'skipped', reason: 'no-package-json' };
   }
+  // `clone` reflink-clones the donor's node_modules in `applyNodeModulesStrategy`.
+  // When the cloned tree carries a completed-install marker AND the worktree's
+  // lockfile byte-matches the donor's, the per-tree install is pure waste —
+  // skip it. The freshness predicate is the single shared `isInstallSkippable`
+  // (byte-exact lockfile hash, never mtime). On a lockfile mismatch (donor
+  // drifted, or no clone happened) this returns false and the install below
+  // runs normally.
+  if (strategy === 'clone') {
+    const donor = resolveCloneDonor(ctx);
+    const probe = isInstallSkippable({ wtPath, donorPath: donor });
+    if (probe.skippable) {
+      ctx.logger.info(
+        `worktree.install strategy=clone skip reason=${probe.reason} path=${wtPath}`,
+      );
+      return { status: 'skipped', reason: `clone-${probe.reason}` };
+    }
+    ctx.logger.info(
+      `worktree.install strategy=clone install reason=${probe.reason} path=${wtPath}`,
+    );
+  }
   // Prime the pnpm content-addressable store once per machine before the
   // worktree's own install runs. No-op for non-pnpm-store strategies. Prime
   // failures are surfaced as warnings but do not short-circuit the install —

package/.agents/scripts/resync-status-column.js

@@ -127,6 +127,7 @@ export function buildReassertOptions({
   logger,
   pollAttempts,
   pollDelayMs,
+  config,
 }) {
   const opts = {
     provider,
@@ -135,6 +136,9 @@ export function buildReassertOptions({
   };
   if (pollAttempts !== undefined) opts.pollAttempts = pollAttempts;
   if (pollDelayMs !== undefined) opts.pollDelayMs = pollDelayMs;
+  // Story #4252 — forward the resolved config so ColumnSync's on-disk
+  // board-metadata cache lands under the project's configured tempRoot.
+  if (config !== undefined) opts.config = config;
   return opts;
 }
 
@@ -168,6 +172,7 @@ export async function main(argv = process.argv.slice(2)) {
       logger: Logger,
       pollAttempts,
       pollDelayMs,
+      config: effectiveConfig,
     }),
   );
   process.stdout.write(`${JSON.stringify({ ticketId, ...result })}\n`);