mandrel 2.25.0 → 2.26.0

package/.agents/scripts/lib/feedback-loop/prior-feedback-fetcher.js

@@ -307,5 +307,3 @@ export async function fetchPriorFeedback({
 
   return envelope;
 }
-
-export default fetchPriorFeedback;

package/.agents/scripts/lib/feedback-loop/retro-proposals-graduator.js

@@ -495,5 +495,3 @@ export async function fileRetroProposals({
   );
   return { routedProposals: enriched, summary };
 }
-
-export default graduateRetroProposals;

package/.agents/scripts/lib/git-utils.js

@@ -40,6 +40,23 @@ import { execFileSync, spawnSync } from 'node:child_process';
  * @property {string} stderr - Trimmed stderr.
  */
 
+/**
+ * Explicit stdout ceiling for every git invocation in this module.
+ *
+ * Both child-process runners default `maxBuffer` to 1 MB, at which point the
+ * child is killed and the call fails with `ENOBUFS` for a reason unrelated to
+ * git. The push path is the sharp edge: `git push` relays the whole `pre-push`
+ * hook output, which is unbounded by design — this repo's hook emits a full
+ * `check-baselines` envelope, measured at 2,166,643 bytes, so every Story
+ * close failed at `phase: push` once hooks became reachable inside worktrees.
+ *
+ * 64 MB is the bound Story #4914 already set on `baselines/git-base.js` for
+ * the identical failure, matching `run-test-profile.js`,
+ * `audit-baselines/trend.js` and `audit-baselines/weights.js`. This module was
+ * missed by that sweep.
+ */
+const MAX_BUFFER_BYTES = 64 * 1024 * 1024;
+
 let _execFileSync = execFileSync;
 let _spawnSync = spawnSync;
 
@@ -108,38 +125,44 @@ export function __setGitRunners(exec, spawn) {
 }
 
 /**
- * Run a git command synchronously, returning trimmed stdout.
- * Throws an Error if the command exits with a non-zero code.
+ * The **single** throwing git runner. Both the module-level {@link gitSync} and
+ * the interface returned by {@link createGitInterface} route through this —
+ * they differ only in which `execFileSync` they hand it.
  *
- * @param {string}   cwd  - Working directory for the git process.
- * @param {...string} args - Git sub-command and arguments.
+ * @param {typeof execFileSync} exec
+ * @param {string} cwd
+ * @param {string[]} args
  * @returns {string} Trimmed stdout text.
  */
-export function gitSync(cwd, ...args) {
-  return _execFileSync('git', args, {
+function runGitSync(exec, cwd, args) {
+  return exec('git', args, {
     cwd,
     encoding: 'utf8',
     stdio: ['pipe', 'pipe', 'pipe'],
     shell: false,
     env: cleanGitEnv(),
+    maxBuffer: MAX_BUFFER_BYTES,
   }).trim();
 }
 
 /**
- * Run a git command synchronously, returning a result object.
- * Never throws — callers must inspect `status` to detect failure.
+ * The **single** non-throwing git runner — the `spawnSync` counterpart of
+ * {@link runGitSync}, normalising `status`/stdout/stderr into a
+ * {@link GitResult}.
  *
- * @param {string}   cwd  - Working directory for the git process.
- * @param {...string} args - Git sub-command and arguments.
+ * @param {typeof spawnSync} spawn
+ * @param {string} cwd
+ * @param {string[]} args
  * @returns {GitResult}
  */
-export function gitSpawn(cwd, ...args) {
-  const result = _spawnSync('git', args, {
+function runGitSpawn(spawn, cwd, args) {
+  const result = spawn('git', args, {
     cwd,
     stdio: 'pipe',
     encoding: 'utf-8',
     shell: false,
     env: cleanGitEnv(),
+    maxBuffer: MAX_BUFFER_BYTES,
   });
   return {
     status: result.status ?? 1,
@@ -148,6 +171,30 @@ export function gitSpawn(cwd, ...args) {
   };
 }
 
+/**
+ * Run a git command synchronously, returning trimmed stdout.
+ * Throws an Error if the command exits with a non-zero code.
+ *
+ * @param {string}   cwd  - Working directory for the git process.
+ * @param {...string} args - Git sub-command and arguments.
+ * @returns {string} Trimmed stdout text.
+ */
+export function gitSync(cwd, ...args) {
+  return runGitSync(_execFileSync, cwd, args);
+}
+
+/**
+ * Run a git command synchronously, returning a result object.
+ * Never throws — callers must inspect `status` to detect failure.
+ *
+ * @param {string}   cwd  - Working directory for the git process.
+ * @param {...string} args - Git sub-command and arguments.
+ * @returns {GitResult}
+ */
+export function gitSpawn(cwd, ...args) {
+  return runGitSpawn(_spawnSync, cwd, args);
+}
+
 /**
  * Build a git interface closed over injected child-process runners. Preferred
  * seam for callers that want explicit injection without touching the
@@ -165,57 +212,25 @@ export function gitSpawn(cwd, ...args) {
 export function createGitInterface(deps = {}) {
   const exec = deps.exec ?? execFileSync;
   const spawn = deps.spawn ?? spawnSync;
-  const sleep =
-    deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const sleep = deps.sleep ?? defaultSleep;
   const jitterFactor = deps.jitter ?? 0.5;
 
-  const gitSync = (cwd, ...args) =>
-    exec('git', args, {
-      cwd,
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe'],
-      shell: false,
-      env: cleanGitEnv(),
-    }).trim();
-
-  const gitSpawn = (cwd, ...args) => {
-    const result = spawn('git', args, {
-      cwd,
-      stdio: 'pipe',
-      encoding: 'utf-8',
-      shell: false,
-      env: cleanGitEnv(),
-    });
-    return {
-      status: result.status ?? 1,
-      stdout: (result.stdout ?? '').trim(),
-      stderr: (result.stderr ?? '').trim(),
-    };
-  };
-
-  async function runWithRetry(leadingArgs, cwd, args) {
-    const backoff = [250, 500, 1000];
-    let attempt = 0;
-    let last;
-    for (;;) {
-      attempt++;
-      last = gitSpawn(cwd, ...leadingArgs, ...args);
-      if (last.status === 0) return { ...last, attempts: attempt };
-      if (!isPackedRefsContention(last.stderr))
-        return { ...last, attempts: attempt };
-      if (attempt > backoff.length) return { ...last, attempts: attempt };
-      const base = backoff[attempt - 1];
-      const jitter = Math.floor(Math.random() * base * jitterFactor);
-      await sleep(base + jitter);
-    }
-  }
+  const boundGitSpawn = (cwd, ...args) => runGitSpawn(spawn, cwd, args);
+  const withRetry =
+    (argvPrefix) =>
+    (cwd, ...args) =>
+      gitWithContentionRetry(
+        { spawnGit: boundGitSpawn, sleep, jitterFactor },
+        cwd,
+        argvPrefix,
+        args,
+      );
 
   return {
-    gitSync,
-    gitSpawn,
-    gitFetchWithRetry: (cwd, ...args) => runWithRetry(['fetch'], cwd, args),
-    gitPullWithRetry: (cwd, ...args) =>
-      runWithRetry(['pull', '--rebase'], cwd, args),
+    gitSync: (cwd, ...args) => runGitSync(exec, cwd, args),
+    gitSpawn: boundGitSpawn,
+    gitFetchWithRetry: withRetry(['fetch']),
+    gitPullWithRetry: withRetry(['pull', '--rebase']),
   };
 }
 
@@ -238,12 +253,21 @@ function isPackedRefsContention(stderr) {
 }
 
 /**
- * Sleep helper for retry backoff. Overridable via `__setSleep` so tests
- * can skip real wall-clock delays without relying on node:test timer mocks.
+ * Real wall-clock sleep — the default backoff delay for both the module-level
+ * retry helpers and {@link createGitInterface}.
  * @param {number} ms
  * @returns {Promise<void>}
  */
-let _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Sleep helper for retry backoff. Overridable via `__setSleep` so tests
+ * can skip real wall-clock delays without relying on node:test timer mocks.
+ * @type {(ms: number) => Promise<void>}
+ */
+let _sleep = defaultSleep;
 let _jitterFactor = 0.5;
 
 /**
@@ -258,38 +282,65 @@ export function __setSleep(fn, opts = {}) {
 }
 
 /**
- * Shared bounded retry loop for git commands that can hit packed-refs lock
- * contention. Only contention signatures trigger a retry — non-contention
+ * Backoff schedule for {@link gitWithContentionRetry}: 250ms, 500ms, 1000ms
+ * (3 retries → 4 attempts total).
+ */
+const CONTENTION_BACKOFF_MS = Object.freeze([250, 500, 1000]);
+
+/**
+ * The **single** bounded retry loop for git commands that can hit packed-refs
+ * lock contention. Only contention signatures trigger a retry — non-contention
  * failures surface immediately, and success short-circuits the loop.
  *
- * Backoff schedule: 250ms, 500ms, 1000ms (3 retries → 4 attempts total).
  * Deliberately no global lock — a mutex would erase the parallelism the
- * worktree-isolation model is designed to enable. The schedule and the
- * jitter policy (`_sleep` / `_jitterFactor` seams) live only here so a
- * backoff tuning change has a single point of application.
+ * worktree-isolation model is designed to enable. The schedule and the jitter
+ * policy live only here, so a backoff tuning change has a single point of
+ * application: the module-level `gitFetchWithRetry` / `gitPullWithRetry` pass
+ * the `_sleep` / `_jitterFactor` seams, and {@link createGitInterface} passes
+ * its injected equivalents.
  *
+ * @param {{ spawnGit: (cwd: string, ...args: string[]) => GitResult,
+ *   sleep: (ms: number) => Promise<void>, jitterFactor: number }} runners
  * @param {string} cwd
  * @param {string[]} argvPrefix - Leading git argv (e.g. `['fetch']`).
  * @param {string[]} args - Trailing arguments (e.g. `['origin']`).
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
-async function gitWithContentionRetry(cwd, argvPrefix, args) {
-  const backoff = [250, 500, 1000];
+async function gitWithContentionRetry(
+  { spawnGit, sleep, jitterFactor },
+  cwd,
+  argvPrefix,
+  args,
+) {
   let attempt = 0;
-  let last;
   for (;;) {
     attempt++;
-    last = gitSpawn(cwd, ...argvPrefix, ...args);
-    if (last.status === 0) return { ...last, attempts: attempt };
-    if (!isPackedRefsContention(last.stderr))
+    const last = spawnGit(cwd, ...argvPrefix, ...args);
+    const exhausted = attempt > CONTENTION_BACKOFF_MS.length;
+    if (
+      last.status === 0 ||
+      exhausted ||
+      !isPackedRefsContention(last.stderr)
+    ) {
       return { ...last, attempts: attempt };
-    if (attempt > backoff.length) return { ...last, attempts: attempt };
-    const base = backoff[attempt - 1];
-    const jitter = Math.floor(Math.random() * base * _jitterFactor);
-    await _sleep(base + jitter);
+    }
+    const base = CONTENTION_BACKOFF_MS[attempt - 1];
+    await sleep(base + Math.floor(Math.random() * base * jitterFactor));
   }
 }
 
+/**
+ * The module-level retry runners — the `__setSleep`-overridable seams bound to
+ * the module-global {@link gitSpawn}. Read lazily so `__setSleep` and
+ * `__setGitRunners` still take effect after import.
+ *
+ * @returns {{ spawnGit: typeof gitSpawn, sleep: (ms: number) => Promise<void>,
+ *   jitterFactor: number }}
+ */
+function moduleRetryRunners() {
+  return { spawnGit: gitSpawn, sleep: _sleep, jitterFactor: _jitterFactor };
+}
+
 /**
  * Run `git fetch …` with the bounded packed-refs-contention retry loop
  * (see `gitWithContentionRetry`).
@@ -299,7 +350,7 @@ async function gitWithContentionRetry(cwd, argvPrefix, args) {
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
 export function gitFetchWithRetry(cwd, ...args) {
-  return gitWithContentionRetry(cwd, ['fetch'], args);
+  return gitWithContentionRetry(moduleRetryRunners(), cwd, ['fetch'], args);
 }
 
 /**
@@ -312,7 +363,12 @@ export function gitFetchWithRetry(cwd, ...args) {
  * @returns {Promise<{ status: number, stdout: string, stderr: string, attempts: number }>}
  */
 export function gitPullWithRetry(cwd, ...args) {
-  return gitWithContentionRetry(cwd, ['pull', '--rebase'], args);
+  return gitWithContentionRetry(
+    moduleRetryRunners(),
+    cwd,
+    ['pull', '--rebase'],
+    args,
+  );
 }
 
 /**

package/.agents/scripts/lib/import-graph.js

@@ -0,0 +1,156 @@
+/**
+ * import-graph.js — the shared static-import graph seam (Story #4902).
+ *
+ * Extracted verbatim from `check-arch-cycles.js`, which owned the only
+ * import-graph builder in the repository and kept it private to its own
+ * cycle ratchet. A second consumer now needs the same graph for a very
+ * different question — `audit-baselines.js` ranks hotspot files by import
+ * in-degree — and re-deriving "which module imports which" a second time
+ * would guarantee the two answers drift.
+ *
+ * Note this is a **module** graph, not the task/DAG graph in `lib/Graph.js`;
+ * the two are unrelated despite the shared word.
+ *
+ * The extraction is behaviour-preserving: `check-arch-cycles.js` imports
+ * these helpers and re-exports them, so its public surface (and the ratchet's
+ * output) is unchanged.
+ *
+ * @module lib/import-graph
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Default scan roots making up the project's distributed surface — the
+ * directories published to npm via `package.json` `files[]`. Resolving
+ * them into one graph (relativized against the repo root) means a cycle
+ * crossing two roots is visible to consumers of the graph.
+ *
+ * @type {string[]}
+ */
+export const DEFAULT_ROOTS = [path.join('.agents', 'scripts'), 'bin', 'lib'];
+
+/**
+ * Recursively collect `.js` files under `rootDir`, skipping
+ * `node_modules`. Returns absolute paths, sorted for determinism.
+ *
+ * @param {string} rootDir
+ * @returns {string[]}
+ */
+export function collectJsFiles(rootDir) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules') continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile() && entry.name.endsWith('.js')) {
+        out.push(full);
+      }
+    }
+  };
+  walk(rootDir);
+  return out.sort();
+}
+
+const IMPORT_RE = /from\s+['"](\.\.?\/[^'"]+\.js)['"]/g;
+
+/**
+ * Pure helper: extract relative static-import specifiers from source text.
+ *
+ * @param {string} source
+ * @returns {string[]}
+ */
+export function parseRelativeImports(source) {
+  const specs = [];
+  for (const m of source.matchAll(IMPORT_RE)) {
+    specs.push(m[1]);
+  }
+  return specs;
+}
+
+/**
+ * Build a directed import graph over the given files. Node identity is the
+ * file path relative to `rootDir`, posix-separated, so the graph (and any
+ * cycles found in it) serializes identically across platforms. Edges that
+ * resolve outside the scanned file set are dropped.
+ *
+ * @param {string[]} files absolute paths
+ * @param {string} rootDir
+ * @param {{ readFile?: (p: string) => string }} [opts]
+ * @returns {Map<string, string[]>}
+ */
+export function buildGraph(files, rootDir, { readFile } = {}) {
+  const read = readFile ?? ((p) => fs.readFileSync(p, 'utf-8'));
+  const toId = (abs) => path.relative(rootDir, abs).split(path.sep).join('/');
+  const idSet = new Set(files.map(toId));
+  const graph = new Map();
+  for (const file of files) {
+    const id = toId(file);
+    let source;
+    try {
+      source = read(file);
+    } catch {
+      graph.set(id, []);
+      continue;
+    }
+    const edges = [];
+    for (const spec of parseRelativeImports(source)) {
+      const target = path
+        .relative(rootDir, path.resolve(path.dirname(file), spec))
+        .split(path.sep)
+        .join('/');
+      if (idSet.has(target) && target !== id) edges.push(target);
+    }
+    graph.set(id, [...new Set(edges)].sort());
+  }
+  return graph;
+}
+
+/**
+ * Build the whole-repository import graph by scanning the roots that exist
+ * under `cwd`. Returns `null` when none of the roots is present — the
+ * "no resolvable import graph" degradation every consumer must tolerate
+ * rather than treating an absent graph as a graph with no edges.
+ *
+ * @param {string} cwd repository root the ids are relativized against
+ * @param {{ roots?: string[] }} [opts]
+ * @returns {Map<string, string[]> | null}
+ */
+export function resolveRepoGraph(cwd, { roots = DEFAULT_ROOTS } = {}) {
+  const present = roots
+    .map((dir) => path.resolve(cwd, dir))
+    .filter((dir) => fs.existsSync(dir));
+  if (present.length === 0) return null;
+  const files = present.flatMap((dir) => collectJsFiles(dir));
+  if (files.length === 0) return null;
+  return buildGraph(files, path.resolve(cwd));
+}
+
+/**
+ * Count inbound edges per node. Nodes with no inbound edge are present in
+ * the result with a count of 0, so callers never have to distinguish
+ * "unknown module" from "module nothing imports".
+ *
+ * @param {Map<string, string[]> | null} graph
+ * @returns {Map<string, number>} empty when `graph` is null
+ */
+export function computeInDegree(graph) {
+  const degrees = new Map();
+  if (!graph) return degrees;
+  for (const node of graph.keys()) degrees.set(node, 0);
+  for (const edges of graph.values()) {
+    for (const target of edges) {
+      degrees.set(target, (degrees.get(target) ?? 0) + 1);
+    }
+  }
+  return degrees;
+}

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -534,18 +534,33 @@ function frictionForTerminal(envelope) {
  * Emit the friction record (if any) implied by a terminal envelope.
  * Best-effort; never throws.
  *
+ * `tool` is the CALLER's name, threaded in rather than assumed: TWO CLIs emit
+ * terminal envelopes — `single-story-close.js` (plus its runner) and
+ * `single-story-confirm-merge.js` — and `retro-proposals.js` reads
+ * `emitter.tool` (via {@link normalizeGatheredSignal}) to name the surface a
+ * candidate came from, so hard-coding the close name here attributed every
+ * confirm-merge record to a CLI that never ran and misdirected the follow-up.
+ * Both callers already declare their name once via `runAsCli({ source })`;
+ * pass that same string. The default keeps the close paths — the original
+ * callers, which pass none — emitting exactly what they always did.
+ *
  * @param {object} args
  * @param {object} args.envelope
+ * @param {string} [args.tool] Emitting surface (default `single-story-close`).
  * @param {object} [args.config]
  * @returns {Promise<boolean>} true when a record was appended.
  */
-export async function emitTerminalFriction({ envelope, config } = {}) {
+export async function emitTerminalFriction({
+  envelope,
+  tool = 'single-story-close',
+  config,
+} = {}) {
   const verdict = frictionForTerminal(envelope);
   if (!verdict) return false;
   return emitRuntimeFriction({
     storyId: envelope?.storyId,
     category: verdict.category,
-    tool: 'single-story-close',
+    tool,
     details: verdict.details,
     config,
   });