mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/checks/epic-merge-lock-stale.js

@@ -1,54 +0,0 @@
-/**
- * epic-merge-lock-stale — refuse-and-print warning check.
- *
- * Detects orphan `epic-<id>.merge.lock` files left behind by a crashed
- * or hung `withEpicMergeLock()` holder. The live serialization path is
- * owned by `lib/epic-merge-lock.js` itself; this check intentionally
- * does NOT serialize against it. Instead, at preflight time it probes
- * the lock file for each known epic and surfaces a warning when:
- *
- *   - the lock file exists, AND
- *   - the recorded holder PID is not alive (per `process.kill(pid, 0)`).
- *
- * Severity is `warning` rather than `blocker` because the live lock
- * implementation already steals stale locks on its own (per
- * `tryStealStale()` in epic-merge-lock.js). Surfacing the residue
- * earlier just helps operators diagnose hung CI runs before they
- * snowball into wave-aggregation timeouts. The fix is a literal
- * `rm <lockPath>` — refuse-and-print so the operator runs it
- * deliberately.
- *
- * Reads `state.fs.epicMergeLocks`, a map of `epicId → { exists, pid,
- * holderAlive, path, ... }` populated by state.js.
- */
-export default {
-  id: 'epic-merge-lock-stale',
-  severity: 'warning',
-  scope: ['story-close', 'retro'],
-  autoCorrect: 'refuse-and-print',
-  detect(state) {
-    const locks = state?.fs?.epicMergeLocks ?? {};
-    for (const [epicId, info] of Object.entries(locks)) {
-      if (!info?.exists) continue;
-      if (info.holderAlive) continue;
-      // Lock exists and the holder PID is not alive — orphan.
-      return {
-        id: 'epic-merge-lock-stale',
-        severity: 'warning',
-        scope: state?.scope ?? 'story-close',
-        summary: `Orphan epic merge lock for epic/${epicId} (holder PID ${info.pid ?? 'unknown'} not alive)`,
-        detail: [
-          `lock path: ${info.path}`,
-          `holder pid: ${info.pid ?? 'unknown'}`,
-          info.acquiredAt
-            ? `acquired at: ${new Date(info.acquiredAt).toISOString()}`
-            : 'acquired at: unknown',
-          'The live lock will steal this on next contention, but the residue can be cleared manually.',
-        ].join('\n'),
-        fixCommand: `rm "${info.path}"`,
-        autoCorrectable: false,
-      };
-    }
-    return null;
-  },
-};

package/.agents/scripts/lib/checks/stale-origin-epic.js

@@ -1,49 +0,0 @@
-/**
- * stale-origin-epic — refuse-and-print blocker check.
- *
- * Detects the failure mode where a manual merge into `epic/<id>` landed
- * locally but the operator forgot to `git push` the epic branch before
- * re-running `story-close.js`. The close script's rebase then fights a
- * stale `origin/epic/<id>` and re-introduces a different conflict on
- * every retry.
- *
- * The check surfaces this at story-close preflight (and at retro time
- * read-only) so the operator is told to fetch + push the epic branch
- * before the close re-runs. It is `refuse-and-print` because the fix
- * is `git fetch origin` followed by `git push origin epic/<id>`; both
- * touch remote state and therefore violate the autoCorrect rules.
- *
- * Detection reads `state.git.epicBranchSync` (assembled in state.js).
- * Each entry reports `{ local, remote, ahead }` for an `epic/<id>` ref;
- * we surface the first ref whose local SHA differs from its remote SHA.
- * If the remote ref is missing entirely we return null (this is a
- * pre-push epic, not a stale one — story-close.js handles that path).
- */
-export default {
-  id: 'stale-origin-epic',
-  severity: 'blocker',
-  scope: ['story-close', 'retro'],
-  autoCorrect: 'refuse-and-print',
-  detect(state) {
-    const sync = state?.git?.epicBranchSync ?? {};
-    const entries = Object.entries(sync);
-    for (const [branch, info] of entries) {
-      if (!info?.local || !info.remote) continue;
-      if (!info.ahead) continue;
-      return {
-        id: 'stale-origin-epic',
-        severity: 'blocker',
-        scope: state?.scope ?? 'story-close',
-        summary: `Local ${branch} differs from origin/${branch}; close will rebase against a stale base.`,
-        detail: [
-          `local  ${branch}        = ${info.local}`,
-          `remote origin/${branch} = ${info.remote}`,
-          'Push the epic branch (or fetch origin) before re-running story-close.',
-        ].join('\n'),
-        fixCommand: `git fetch origin && git push origin ${branch}`,
-        autoCorrectable: false,
-      };
-    }
-    return null;
-  },
-};

package/.agents/scripts/lib/config/lifecycle.js

@@ -1,40 +0,0 @@
-/**
- * `delivery.lifecycle` accessor + framework defaults.
- *
- * `TimeoutWatchdog` returns null (no budget) for any timeout key absent from
- * the operator config, meaning phases can hang indefinitely on projects that
- * omit the block. These defaults ensure every Epic run has a watchdog out of
- * the box; projects override individual keys by supplying their own values,
- * which are merged over the defaults.
- */
-
-export const LIFECYCLE_DEFAULTS = Object.freeze({
-  timeouts: Object.freeze({
-    'acceptance.reconcile': 600,
-    'epic.finalize': 600,
-    'epic.watch': 1800,
-  }),
-  heartbeatWarnSeconds: 60,
-});
-
-/**
- * Read the merged `delivery.lifecycle` block, applying framework defaults
- * for any field the operator omitted. Accepts the full resolved config or
- * a bare `{ delivery: { lifecycle: ... } }` / `{ lifecycle: ... }` shape.
- *
- * User-supplied timeout keys win over defaults; unknown keys are preserved
- * so projects can define custom phase budgets.
- *
- * @param {object | null | undefined} config
- * @returns {{ timeouts: Record<string, number>, heartbeatWarnSeconds: number }}
- */
-export function getLifecycle(config) {
-  const lc = config?.delivery?.lifecycle ?? config?.lifecycle ?? config ?? {};
-  return {
-    timeouts: { ...LIFECYCLE_DEFAULTS.timeouts, ...(lc.timeouts ?? {}) },
-    heartbeatWarnSeconds:
-      Number.isInteger(lc.heartbeatWarnSeconds) && lc.heartbeatWarnSeconds >= 1
-        ? lc.heartbeatWarnSeconds
-        : LIFECYCLE_DEFAULTS.heartbeatWarnSeconds,
-  };
-}

package/.agents/scripts/lib/config/preflight.js

@@ -1,58 +0,0 @@
-/**
- * `delivery.preflight` accessor + framework defaults — Story #2899
- * (Epic #2880, F13).
- *
- * Thresholds consumed by `.agents/scripts/epic-deliver-preflight.js`.
- * The defaults are intentionally generous so that a brand-new Epic on a
- * zero-config project does not trip a breach. Operators tighten thresholds
- * per project in `.agentrc.json`. A `null` floor means "no cap" — used by
- * the preflight runner to skip the corresponding breach check.
- */
-
-export const PREFLIGHT_DEFAULTS = Object.freeze({
-  maxStories: null,
-  maxWaves: null,
-  maxInstallCostSeconds: null,
-  maxGithubApiRequests: null,
-  maxClaudeQuotaTokens: null,
-});
-
-/**
- * Read the merged `delivery.preflight` block, applying framework defaults
- * for any field the operator omitted. Accepts the full resolved config,
- * the bare delivery bag, or the bare preflight bag.
- *
- * @param {object | null | undefined} config
- * @returns {{
- *   maxStories: number | null,
- *   maxWaves: number | null,
- *   maxInstallCostSeconds: number | null,
- *   maxGithubApiRequests: number | null,
- *   maxClaudeQuotaTokens: number | null,
- * }}
- */
-export function getPreflight(config) {
-  const pf = config?.delivery?.preflight ?? config?.preflight ?? config ?? {};
-  return {
-    maxStories: normaliseFloor(pf.maxStories, PREFLIGHT_DEFAULTS.maxStories),
-    maxWaves: normaliseFloor(pf.maxWaves, PREFLIGHT_DEFAULTS.maxWaves),
-    maxInstallCostSeconds: normaliseFloor(
-      pf.maxInstallCostSeconds,
-      PREFLIGHT_DEFAULTS.maxInstallCostSeconds,
-    ),
-    maxGithubApiRequests: normaliseFloor(
-      pf.maxGithubApiRequests,
-      PREFLIGHT_DEFAULTS.maxGithubApiRequests,
-    ),
-    maxClaudeQuotaTokens: normaliseFloor(
-      pf.maxClaudeQuotaTokens,
-      PREFLIGHT_DEFAULTS.maxClaudeQuotaTokens,
-    ),
-  };
-}
-
-function normaliseFloor(value, fallback) {
-  if (value === null) return null;
-  if (Number.isInteger(value) && value >= 1) return value;
-  return fallback;
-}

package/.agents/scripts/lib/config/retro.js

@@ -1,77 +0,0 @@
-/**
- * Retro accessor (Story #3042 / Task #3043 — Epic #3019).
- *
- * Resolves `.agentrc.json → delivery.retro` into the canonical shape the
- * retro-runner consumes. Currently exposes only `perfThresholds`, the
- * operator-tunable gates for the perf-signals classifier in
- * `lib/orchestration/retro-perf-heuristics.js`.
- *
- * Defaults mirror `DEFAULT_RETRO_PERF_THRESHOLDS` in the heuristics module
- * (single source of behavioural truth; this resolver is a thin merge layer).
- */
-
-/**
- * Default perf-threshold trio applied when `.agentrc.json` omits
- * `delivery.retro.perfThresholds` (or any of its sub-keys). Frozen so
- * downstream callers cannot accidentally mutate the resolver's defaults
- * across processes.
- *
- * Keep in lockstep with `DEFAULT_RETRO_PERF_THRESHOLDS` in
- * `lib/orchestration/retro-perf-heuristics.js` and the schema mirror in
- * `agentrc.schema.json → $defs.retro.properties.perfThresholds`.
- */
-export const DEFAULT_RETRO = Object.freeze({
-  perfThresholds: Object.freeze({
-    utilisation: 0.6,
-    bootstrapShare: 0.4,
-    capBindingRunLength: 2,
-  }),
-});
-
-/**
- * Read the merged retro block. Returns the canonical shape:
- *
- *   {
- *     perfThresholds: {
- *       utilisation: number,
- *       bootstrapShare: number,
- *       capBindingRunLength: number,
- *     },
- *   }
- *
- * Each sub-key falls back to its documented default when the resolved
- * `.agentrc.json` omits it. Out-of-range values fall back to defaults too —
- * the AJV schema rejects them before they reach this accessor, but the
- * resolver stays defensive so unit-test fixtures and degraded configs
- * never produce nonsensical thresholds.
- *
- * @param {object | null | undefined} config
- * @returns {{ perfThresholds: { utilisation: number, bootstrapShare: number, capBindingRunLength: number } }}
- */
-export function getRetro(config) {
-  const user = config?.delivery?.retro?.perfThresholds ?? {};
-  const defaults = DEFAULT_RETRO.perfThresholds;
-  return {
-    perfThresholds: {
-      utilisation: resolveUnit(user.utilisation, defaults.utilisation),
-      bootstrapShare: resolveUnit(user.bootstrapShare, defaults.bootstrapShare),
-      capBindingRunLength: resolvePositiveInt(
-        user.capBindingRunLength,
-        defaults.capBindingRunLength,
-      ),
-    },
-  };
-}
-
-function resolveUnit(value, fallback) {
-  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
-  if (value < 0 || value > 1) return fallback;
-  return value;
-}
-
-function resolvePositiveInt(value, fallback) {
-  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
-    return fallback;
-  }
-  return value;
-}

package/.agents/scripts/lib/epic-merge-lock.js

@@ -1,322 +0,0 @@
-/**
- * lib/epic-merge-lock.js — Filesystem mutex for Epic-branch merges.
- *
- * Parallel-wave story closures can race on the Epic branch: two
- * `story-close.js` invocations both `git checkout <epic>`, both
- * `git pull --rebase`, and both attempt to merge — the second push
- * often ends up rejected or, worse, races past the first and produces
- * an incorrect history.
- *
- * This module provides a best-effort cooperative lock keyed per Epic.
- * The lock file lives at `<repoRoot>/.git/epic-<epicId>.merge.lock`
- * (inside `.git/` so it never lands in a commit). Acquisition uses
- * `fs.openSync(..., 'wx')` for atomicity; on contention we poll every
- * 250ms until `timeoutMs` elapses.
- *
- * Stale-lock stealing:
- *   - If the PID recorded in the lock is not running (per
- *     `process.kill(pid, 0)`), or
- *   - if the lock file is older than `timeoutMs * 2`,
- *   the lock is stolen (unlinked) and re-acquired.
- *
- * Test seams (mirroring `single-story-sweep/sweep-lock.js`):
- *   - `nowFn`   — `() => number` (ms epoch); replaces `Date.now`.
- *   - `fsImpl`  — Node `fs` shim; replaces the imported `fs`.
- *   - `killFn`  — `(pid, signal) => void`; replaces `process.kill`,
- *                 so a test can make `pidDead` deterministic without
- *                 fabricating a real dead PID.
- *   - `sleepFn` — `(ms) => Promise<void>`; replaces the real
- *                 `setTimeout`-backed sleep, so the poll loop can spin
- *                 with no wall-clock waits.
- * All four default to the real implementations, so production callers
- * (`acquire(epicId, { repoRoot, timeoutMs })`) see no behavior change.
- */
-
-import { execFileSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-
-const POLL_INTERVAL_MS = 250;
-
-/**
- * Resolve the *common* gitdir for a given working directory.
- *
- * In a linked worktree (`git worktree add ...`), `<repoRoot>/.git` is a
- * one-line gitlink **file**, not a directory. `path.join(repoRoot, '.git')`
- * therefore points at the gitlink file and any `mkdir`/`openSync` against
- * it fails with `EEXIST: file already exists`.
- *
- * Resolution order:
- *   1. If `<repoRoot>/.git` is already a directory, return it. Covers the
- *      main-checkout case and the test fixtures, which create a bare
- *      `.git/` under a temp root — no need to spawn git for those.
- *   2. Otherwise (gitlink file, or `.git` absent), shell out to
- *      `git rev-parse --git-common-dir`. In a worktree this returns the
- *      parent repo's `.git/`, so lock files placed there are shared
- *      across every worktree racing on the same Epic — which is the
- *      correct semantics for an epic-merge mutex.
- *   3. If neither succeeds, fall back to `<repoRoot>/.git`. Lock
- *      acquisition will then surface the underlying error to the
- *      operator with the literal path that failed.
- */
-export function resolveGitCommonDir(repoRoot, fsImpl = fs) {
-  const local = path.join(repoRoot, '.git');
-  try {
-    if (fsImpl.statSync(local).isDirectory()) return local;
-  } catch {
-    // .git does not exist — fall through to git rev-parse.
-  }
-  try {
-    const out = execFileSync('git', ['rev-parse', '--git-common-dir'], {
-      cwd: repoRoot,
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'ignore'],
-    }).trim();
-    if (out) return path.isAbsolute(out) ? out : path.resolve(repoRoot, out);
-  } catch {
-    // not a git repo, or git is unavailable — fall through.
-  }
-  return local;
-}
-
-function lockPathFor(epicId, repoRoot, fsImpl = fs) {
-  return path.join(
-    resolveGitCommonDir(repoRoot, fsImpl),
-    `epic-${epicId}.merge.lock`,
-  );
-}
-
-function isProcessRunning(pid, killFn = process.kill) {
-  if (!Number.isFinite(pid) || pid <= 0) return false;
-  try {
-    // Signal 0 does not deliver a signal; it just checks existence.
-    killFn(pid, 0);
-    return true;
-  } catch (err) {
-    // ESRCH = no such process. EPERM = exists but we can't signal — still alive.
-    return err.code === 'EPERM';
-  }
-}
-
-function readLockMeta(filePath, fsImpl = fs) {
-  try {
-    const raw = fsImpl.readFileSync(filePath, 'utf8');
-    const parsed = JSON.parse(raw);
-    return {
-      pid: Number(parsed.pid),
-      acquiredAt: Number(parsed.acquiredAt),
-    };
-  } catch {
-    return null;
-  }
-}
-
-function tryStealStale(filePath, timeoutMs, seams) {
-  const { fsImpl, nowFn, killFn } = seams;
-  let stats;
-  try {
-    stats = fsImpl.statSync(filePath);
-  } catch {
-    return false;
-  }
-
-  const meta = readLockMeta(filePath, fsImpl);
-  // Corrupted lock file (null meta): we can't verify the writer's PID and
-  // the age comparison is unsafe on Windows where NTFS mtime vs Date.now()
-  // can disagree by hundreds of milliseconds, falsely flipping `ancient`
-  // true at short timeouts. Treat the file as held; the caller times out.
-  // A truly stuck corrupted lock has to be cleared manually — that's the
-  // safer failure mode than wrongly stealing a lock another process owns.
-  if (!meta) return false;
-
-  const ageMs = nowFn() - stats.mtimeMs;
-  const pidDead = !isProcessRunning(meta.pid, killFn);
-  const ancient = ageMs > timeoutMs * 2;
-
-  if (pidDead || ancient) {
-    try {
-      fsImpl.unlinkSync(filePath);
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  return false;
-}
-
-function defaultSleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-// Inner polling loop. Acquires the lock file with `wx` (atomic
-// create-or-error); on EEXIST it tries to steal a stale lock, then
-// either times out or sleeps and retries. Kept separate from
-// `acquireEpicMergeLock` so the public function's cyclomatic complexity
-// stays flat under CRAP.
-async function pollForLock(epicId, filePath, timeoutMs, seams) {
-  const { fsImpl, nowFn, sleepFn } = seams;
-  const started = nowFn();
-  while (true) {
-    try {
-      const fd = fsImpl.openSync(filePath, 'wx');
-      const acquiredAt = nowFn();
-      fsImpl.writeSync(
-        fd,
-        JSON.stringify({ pid: process.pid, acquiredAt }, null, 2),
-      );
-      fsImpl.closeSync(fd);
-      return { epicId, filePath, acquiredAt };
-    } catch (err) {
-      if (err.code !== 'EEXIST') throw err;
-      if (tryStealStale(filePath, timeoutMs, seams)) continue;
-      if (nowFn() - started >= timeoutMs) {
-        const meta = readLockMeta(filePath, fsImpl);
-        const detail = meta
-          ? ` (held by pid ${meta.pid} since ${new Date(meta.acquiredAt).toISOString()})`
-          : '';
-        throw new Error(
-          `acquireEpicMergeLock timed out after ${timeoutMs}ms for epic ${epicId}${detail}`,
-        );
-      }
-      await sleepFn(POLL_INTERVAL_MS);
-    }
-  }
-}
-
-/**
- * Acquire an exclusive Epic merge lock.
- *
- * @param {number|string} epicId
- * @param {object} opts
- * @param {string} opts.repoRoot            Repo working dir; the lock lands
- *                                          in its common `.git/`.
- * @param {number} [opts.timeoutMs=60000]   Poll-until deadline.
- * @param {() => number} [opts.nowFn]       Clock seam (ms epoch).
- * @param {object} [opts.fsImpl]            Node `fs` shim.
- * @param {(pid:number, signal:number)=>void} [opts.killFn]
- *                                          `process.kill` shim for the
- *                                          pid-liveness probe.
- * @param {(ms:number)=>Promise<void>} [opts.sleepFn]
- *                                          Poll-interval sleep shim.
- * @returns {Promise<{ epicId: number|string, filePath: string, acquiredAt: number }>}
- * @throws {Error} on timeout.
- */
-export async function acquireEpicMergeLock(
-  epicId,
-  {
-    repoRoot,
-    timeoutMs = 60_000,
-    nowFn = Date.now,
-    fsImpl = fs,
-    killFn = process.kill.bind(process),
-    sleepFn = defaultSleep,
-  } = {},
-) {
-  if (!repoRoot) throw new Error('acquireEpicMergeLock: repoRoot is required');
-
-  const filePath = lockPathFor(epicId, repoRoot, fsImpl);
-  // Ensure the .git directory exists (it will, in a real repo, but the
-  // tests use a temp dir and need us to be forgiving).
-  fsImpl.mkdirSync(path.dirname(filePath), { recursive: true });
-
-  const seams = { fsImpl, nowFn, killFn, sleepFn };
-  return pollForLock(epicId, filePath, timeoutMs, seams);
-}
-
-/**
- * Release a previously-acquired Epic merge lock.
- *
- * @param {{ filePath: string }} handle
- * @param {object} [fsImpl] Node `fs` shim for tests.
- */
-export function releaseEpicMergeLock(handle, fsImpl = fs) {
-  if (!handle?.filePath) return;
-  try {
-    fsImpl.unlinkSync(handle.filePath);
-  } catch (err) {
-    if (err.code !== 'ENOENT') throw err;
-  }
-}
-
-const LOCK_FILE_PREFIX = 'epic-';
-const LOCK_FILE_SUFFIX = '.merge.lock';
-
-// Extract the epic id from a lock filename, or `null` when `entry` isn't a
-// `epic-*.merge.lock` file. Split out of `findForeignActiveEpicLock` so
-// that function stays a flat filter+map instead of a nested-conditional
-// loop body (Story #4460).
-function parseLockFileEpicId(entry) {
-  if (
-    !entry.startsWith(LOCK_FILE_PREFIX) ||
-    !entry.endsWith(LOCK_FILE_SUFFIX)
-  ) {
-    return null;
-  }
-  return entry.slice(
-    LOCK_FILE_PREFIX.length,
-    entry.length - LOCK_FILE_SUFFIX.length,
-  );
-}
-
-// Read `<dir>/<entry>`'s lock meta and report it only when the recorded
-// pid is still alive — a foreign lock whose pid is dead (or whose meta is
-// unreadable/corrupt) is stale debris, not an active holder, mirroring the
-// pid-liveness half of `tryStealStale`'s heuristic.
-function readLiveLock(dir, entry, otherEpicId, fsImpl, killFn) {
-  const filePath = path.join(dir, entry);
-  const meta = readLockMeta(filePath, fsImpl);
-  if (!meta || !isProcessRunning(meta.pid, killFn)) return null;
-  return {
-    epicId: otherEpicId,
-    filePath,
-    pid: meta.pid,
-    acquiredAt: meta.acquiredAt,
-  };
-}
-
-/**
- * Scan the shared common `.git/` dir for a *different* epic's live
- * merge lock (Story #4460 — cross-epic shared-checkout guard).
- *
- * `acquireEpicMergeLock` only ever contends against locks for the *same*
- * `epicId` (its own lock filename). This helper is the cross-epic
- * counterpart: it lists every `epic-*.merge.lock` file in the common
- * gitdir, skips the caller's own `epicId` namespace, and returns the
- * first foreign lock whose recorded `pid` is still alive.
- *
- * @param {number|string} epicId Caller's own epic id (excluded from the scan).
- * @param {{
- *   repoRoot: string,
- *   fsImpl?: object,
- *   killFn?: (pid:number, signal:number)=>void,
- * }} opts
- * @returns {{ epicId: string, filePath: string, pid: number, acquiredAt: number }|null}
- */
-export function findForeignActiveEpicLock(
-  epicId,
-  { repoRoot, fsImpl = fs, killFn = process.kill.bind(process) } = {},
-) {
-  if (!repoRoot) {
-    throw new Error('findForeignActiveEpicLock: repoRoot is required');
-  }
-  const dir = resolveGitCommonDir(repoRoot, fsImpl);
-  let entries;
-  try {
-    entries = fsImpl.readdirSync(dir);
-  } catch {
-    return null;
-  }
-
-  const foreignEntries = entries
-    .map((entry) => ({ entry, otherEpicId: parseLockFileEpicId(entry) }))
-    .filter(
-      ({ otherEpicId }) =>
-        otherEpicId !== null && String(otherEpicId) !== String(epicId),
-    );
-
-  for (const { entry, otherEpicId } of foreignEntries) {
-    const live = readLiveLock(dir, entry, otherEpicId, fsImpl, killFn);
-    if (live) return live;
-  }
-  return null;
-}