mandrel 2.19.0 → 2.21.0

package/.agents/scripts/lib/orchestration/planning/authoring-context.js

@@ -14,15 +14,12 @@ import {
   verifyBddRunnerPendingTag,
 } from '../../bdd-runner-detect.js';
 import { scanBddScenarios } from '../../bdd-scenario-scanner.js';
-import { buildCodebaseSnapshot } from '../../codebase-snapshot.js';
 import { getPaths, PROJECT_ROOT } from '../../config-resolver.js';
 import { scanMemoryFreshness } from '../../feedback-loop/memory-freshness.js';
 import { fetchPriorFeedback } from '../../feedback-loop/prior-feedback-fetcher.js';
 import { Logger } from '../../Logger.js';
 import { hasTicketSection } from '../../ticket-body-sections.js';
 import { ensureDocsDigest } from '../docs-digest.js';
-import { collectReferences, hasNewFileCue } from '../spec-freshness.js';
-import { buildAuthoringGrounding } from './spec-authoring-grounding.js';
 
 /**
  * Resolve the per-project memory directory used by the memory-freshness
@@ -179,68 +176,18 @@ export async function buildAuthoringContext(
     repo: githubCfg?.repo,
   });
 
-  // Story #2634 — codebase snapshot. Generates a bounded structural view
-  // of the consumer repo (file tree + package surface + recent activity
-  // + optional export signatures at the `medium` tier) so the Architect
-  // can prefer real module names over doc-only ones. The check is
-  // best-effort: any git/filesystem error degrades to an empty snapshot
-  // so Phase 7 stays non-blocking.
-  let codebaseSnapshot = null;
-  try {
-    codebaseSnapshot = buildCodebaseSnapshot({
-      cwd: PROJECT_ROOT,
-      tier: settings?.planning?.codebaseSnapshot?.tier,
-      include: settings?.planning?.codebaseSnapshot?.include,
-      exclude: settings?.planning?.codebaseSnapshot?.exclude,
-      recentCommitWindow:
-        settings?.planning?.codebaseSnapshot?.recentCommitWindow,
-    });
-    // Story #4139 (F10) — ground the spec author in the files it will cite.
-    // Two signals are attached to the snapshot envelope so the author (which
-    // consumes the JSON, not stderr) cannot miss them:
-    //   1. `grounding.truncation` — the structured, in-envelope form of the
-    //      Story #3959 dropped-file warning. The skinny-tier cap used to drop
-    //      the majority of matched files with only a stderr `Logger.warn` and
-    //      a bare `truncated: true` flag; the author never learned the
-    //      snapshot was partial (a real run dropped "377 of 627 files").
-    //   2. `grounding.citedButAbsent` — path-shaped references in the Epic
-    //      body (the prose the author grounds *from*) that are absent from
-    //      the snapshot's file set and not phrased as net-new, so cited-but-
-    //      absent surfaces are visible *during* authoring rather than only
-    //      after the post-author freshness gate (Story #2635).
-    // The grounding consults only the snapshot's file set and the Epic body —
-    // no new filesystem or git probes — so the context stays bounded for cost.
-    if (codebaseSnapshot) {
-      const grounding = buildAuthoringGrounding({
-        snapshot: codebaseSnapshot,
-        prose: epic.body ?? '',
-        collectReferences,
-        hasNewFileCue,
-      });
-      codebaseSnapshot.grounding = grounding;
-      if (grounding.truncation) {
-        const { dropped, matched, tier } = grounding.truncation;
-        Logger.warn(
-          `[plan-context] codebase snapshot truncated: ${dropped} of ` +
-            `${matched} matched file(s) dropped from the ${tier}-tier view. ` +
-            `The /plan authoring context is partial. To restore full ` +
-            `grounding, ` +
-            `set planning.codebaseSnapshot.tier: "medium" and/or narrow ` +
-            `planning.codebaseSnapshot.include in .agentrc.json.`,
-        );
-      }
-      if (grounding.citedButAbsent.length > 0) {
-        Logger.warn(
-          `[plan-context] ${grounding.citedButAbsent.length} path(s) cited ` +
-            `in the authored Spec are absent from the codebase snapshot: ` +
-            `${grounding.citedButAbsent.join(', ')}. /plan will flag these ` +
-            `as drift unless they are net-new.`,
-        );
-      }
-    }
-  } catch (err) {
-    Logger.warn(`[plan-context] codebase snapshot skipped: ${err.message}`);
-  }
+  // Story #4811 — the codebase snapshot (#2634), its authoring grounding
+  // (#4139 F10) and the spec-freshness helpers behind it are retired. The
+  // pre-computed structural view grounded nothing it promised: the default
+  // include globs missed the standard monorepo layout outright, its remedies
+  // pointed at knobs that re-filtered the same set, and its cited-but-absent
+  // signal inverted into noise whenever the snapshot was the thing that was
+  // wrong. Grounding now rests on the two mechanisms that read the real tree:
+  // the authoring model's own targeted retrieval (the digest-first precedent
+  // of Story #4433) and the Phase 8 `validateStoryFileAssumptions` gate, which
+  // probes every authored `{path, assumption}` against the working tree as a
+  // hard error. Nothing pre-computed replaces it — a stale inventory is the
+  // failure mode, not the fix.
 
   // Story #4542 — planning authors no risk artifact at all. Review depth and
   // the acceptance-critic mode are derived from the diff at close time
@@ -262,7 +209,6 @@ export async function buildAuthoringContext(
       },
     },
     docsContext,
-    codebaseSnapshot,
     bddRunner,
     bddScenarios,
     memoryFreshness,

package/.agents/scripts/lib/orchestration/single-story-close/gate-log.js

@@ -70,7 +70,17 @@ import { Logger, resolveLevel } from '../../Logger.js';
  */
 export const REPLAY_TAIL_LINES = 200;
 
-/** Basename of the per-Story gate log inside the temp directory. */
+/**
+ * Basename of the per-Story gate log inside the temp directory.
+ *
+ * `closeGateLogPath` in `lib/config/temp-paths.js` spells the same name for the
+ * READER — `deliver-recover.js` uses this file's freshness to tell a live close
+ * from a dead one. Deliberately not shared through an import: this sink needs
+ * the basename alone (it honours a `logDir` override the path helper knows
+ * nothing about), and calling that helper for it would drag tempRoot
+ * resolution — a git spawn and scratch-dir creation — into a filename lookup.
+ * The two spellings are pinned equal by test instead.
+ */
 function logNameFor(storyId) {
   return `close-gates-${storyId ?? 'unknown'}.log`;
 }

package/.agents/scripts/lib/orchestration/single-story-close/runner.js

@@ -71,7 +71,7 @@ async function emitTerminal({ terminal, result, config }) {
       },
     });
   }
-  emitTerminalEnvelope(terminal);
+  emitTerminalEnvelope(terminal, { config });
   await emitTerminalFriction({ envelope: terminal, config });
 }
 

package/.agents/scripts/lib/orchestration/story-deliver-terminal.js

@@ -28,6 +28,10 @@
  * pre-#4543 pipeline collapsed by treating budget exhaustion as a block.
  */
 
+import nodeFs from 'node:fs';
+import path from 'node:path';
+import { storyTerminalEnvelopePath } from '../config/temp-paths.js';
+import { resolveConfig } from '../config-resolver.js';
 import { validateTerminalEnvelope } from './story-deliver-terminal-schema.js';
 
 // Re-exported so the schema split stays an implementation detail: every
@@ -327,7 +331,95 @@ export const TERMINAL_BEGIN_MARKER = '--- STORY DELIVER TERMINAL ---';
 export const TERMINAL_END_MARKER = '--- END TERMINAL ---';
 
 /**
- * Write a terminal envelope to stdout, between its markers.
+ * Resolve the repo config, or `undefined` when it cannot be read.
+ *
+ * An unreadable `.agentrc.json` must not cost the run its envelope copy: the
+ * path helpers fall back to the framework-default temp root, which is still a
+ * far better outcome than no artifact at all.
+ *
+ * @param {typeof resolveConfig} resolveConfigImpl
+ * @returns {object|undefined}
+ */
+function tolerantConfig(resolveConfigImpl) {
+  try {
+    return resolveConfigImpl();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Persist a terminal envelope beside its Story's gate log (Story #4816).
+ *
+ * Stdout is a channel with exactly one reader — the turn that launched the
+ * close — and that reader is not always still listening. A `story-worker`
+ * that reports progress and ends its turn while the close it started is
+ * mid-gate-chain is behaving reasonably, but the envelope it never relayed is
+ * gone: the router then has to reconstruct the Story's state from labels, and
+ * `deliver-recover.js` used to answer that reconstruction with
+ * "Implementation never finished" — false, and its re-init suggestion can put
+ * a second close on one PR. Observed four times across three workers in one
+ * consumer run. The file is the second channel, and it outlives the turn.
+ *
+ * **Best-effort by construction.** Every failure path returns `null`: a
+ * delivery must never turn a landed PR into a crash because a temp directory
+ * was unwritable. The stdout envelope above is the contract; this is a copy.
+ *
+ * **Atomic by construction.** The payload is written to a pid-scoped
+ * temporary name and renamed into place, because the reader that matters most
+ * is a router polling during a live close — a half-written file would hand it
+ * a parse error at exactly the moment it is trying to avoid guessing.
+ *
+ * A null `storyId` (the `escalated` terminal, which by construction never
+ * authored a Story) has nowhere to be filed and writes nothing.
+ *
+ * `config` is optional and resolved lazily when absent. Two of the emit sites
+ * are `catch` blocks that crashed before any config was resolved, and those
+ * are precisely the runs whose envelope is most worth keeping — so the temp
+ * root is looked up here rather than left at the framework default, which
+ * would file the artifact where a consumer's router never looks (and where
+ * the retention purge would never reap it).
+ *
+ * @param {object} envelope A validated terminal envelope.
+ * @param {{
+ *   config?: object,
+ *   fsImpl?: typeof nodeFs,
+ *   resolveConfigImpl?: typeof resolveConfig,
+ * }} [deps]
+ * @returns {string|null} The path written, or `null` when nothing was.
+ */
+export function persistTerminalEnvelope(
+  envelope,
+  { config, fsImpl = nodeFs, resolveConfigImpl = resolveConfig } = {},
+) {
+  const storyId = envelope?.storyId;
+  if (!Number.isInteger(storyId) || storyId <= 0) return null;
+  let tmpPath = null;
+  try {
+    const resolved = config ?? tolerantConfig(resolveConfigImpl);
+    const target = storyTerminalEnvelopePath(storyId, resolved);
+    fsImpl.mkdirSync(path.dirname(target), { recursive: true });
+    tmpPath = `${target}.${process.pid}.tmp`;
+    fsImpl.writeFileSync(tmpPath, `${JSON.stringify(envelope)}\n`, 'utf8');
+    fsImpl.renameSync(tmpPath, target);
+    return target;
+  } catch {
+    // A rename that never ran leaves the scratch file behind; drop it rather
+    // than accumulating one per failed close.
+    if (tmpPath) {
+      try {
+        fsImpl.rmSync(tmpPath, { force: true });
+      } catch {
+        // Nothing left to try — this whole path is already best-effort.
+      }
+    }
+    return null;
+  }
+}
+
+/**
+ * Write a terminal envelope to stdout, between its markers, and persist a
+ * copy to disk.
  *
  * **Deliberately not `Logger.info`.** The envelope is this CLI's
  * machine-readable contract — every invocation emits exactly ONE, and a
@@ -340,16 +432,37 @@ export const TERMINAL_END_MARKER = '--- END TERMINAL ---';
  *
  * Single home for the marker format so the four emit sites (the runner's
  * terminal, the close CLI's failed-terminal catch, and both confirm-CLI
- * paths) cannot drift apart.
+ * paths) cannot drift apart — and, since Story #4816, the single home for the
+ * on-disk copy too, so no emit path can persist and another forget.
+ * {@link persistTerminalEnvelope} runs **first**: a caller that has read the
+ * markers off stdout can then rely on the file already being there.
  *
  * @param {object} envelope
- * @param {{ write?: (s: string) => void }} [opts] `write` is a test seam.
+ * @param {{
+ *   write?: (s: string) => void,
+ *   config?: object,
+ *   persist?: typeof persistTerminalEnvelope,
+ * }} [opts] `write` and `persist` are test seams; `config` resolves the
+ *   artifact's temp root and is threaded from whichever emit site holds one.
  * @returns {void}
  */
 export function emitTerminalEnvelope(
   envelope,
-  { write = (s) => process.stdout.write(s) } = {},
+  {
+    write = (s) => process.stdout.write(s),
+    config,
+    persist = persistTerminalEnvelope,
+  } = {},
 ) {
+  // Belt and braces around a copy: `persistTerminalEnvelope` already swallows
+  // its own failures, but the stdout envelope is the CONTRACT and the disk
+  // copy is a convenience. Nothing in the secondary path — including a future
+  // injected `persist` — may cost the caller the primary one.
+  try {
+    persist(envelope, { config });
+  } catch {
+    // Intentionally silent: see above.
+  }
   // Story #4685 — compact (not 2-space pretty) JSON. The envelope is a
   // machine contract callers recover with `JSON.parse`, so pretty-printing
   // only adds turn-resident bytes without helping any consumer.

package/.agents/scripts/lib/temp-retention.js

@@ -210,28 +210,43 @@ async function makeEntry(fsp, target, className, storyId, keep = false) {
 }
 
 /**
- * Recover the Story id a run-log basename carries. Both writers that land in
- * `orchestration/` end their name with the scope: `close-gates-4794.log` from
- * the gate sink, `sync-result-story-4794.log` from the terse-result dump.
+ * Extensions this class owns inside `orchestration/`. Story #4816 added
+ * `.json`: the persisted terminal envelope lands beside the gate log, and a
+ * `.log`-only scan would have left one immortal file per delivered Story in a
+ * directory the purge otherwise keeps clean.
+ */
+const ORCHESTRATION_EXTENSIONS = Object.freeze(['.log', '.json']);
+
+/**
+ * Recover the Story id a run-artifact basename carries. Every writer that
+ * lands in `orchestration/` ends its name with the scope: `close-gates-4794.log`
+ * from the gate sink, `sync-result-story-4794.log` from the terse-result dump,
+ * `story-deliver-terminal-4794.json` from the terminal-envelope persist.
  *
  * @param {string} name
  * @returns {number|null}
  */
 function storyIdFromLogName(name) {
-  const match = TRAILING_ID_PATTERN.exec(name.replace(/\.log$/, ''));
+  const match = TRAILING_ID_PATTERN.exec(name.replace(/\.(log|json)$/, ''));
   return match ? Number(match[1]) : null;
 }
 
 /**
- * `<tempRoot>/orchestration/*.log` — close gate transcripts and terse-result
- * detail dumps. A log whose name carries no id (there are none today, but the
- * class owns the directory) is age-floored rather than dropped from the class.
+ * `<tempRoot>/orchestration/*.{log,json}` — close gate transcripts,
+ * terse-result detail dumps, and persisted terminal envelopes. An artifact
+ * whose name carries no id (there are none today, but the class owns the
+ * directory) is age-floored rather than dropped from the class.
  */
 async function scanOrchestrationLogs(tempRoot, fsp) {
   const dir = path.join(tempRoot, ORCHESTRATION_DIRNAME);
   const entries = [];
   for (const dirent of await safeReaddir(fsp, dir)) {
-    if (!dirent.isFile() || !dirent.name.endsWith('.log')) continue;
+    if (
+      !dirent.isFile() ||
+      !ORCHESTRATION_EXTENSIONS.some((ext) => dirent.name.endsWith(ext))
+    ) {
+      continue;
+    }
     const entry = await makeEntry(
       fsp,
       path.join(dir, dirent.name),

package/.agents/scripts/lib/test-env.js

@@ -3,6 +3,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 import { TEST_TEMP_ROOT_ENV } from './config/temp-paths.js';
+import { reapOnExit } from './test-temp.js';
 
 /**
  * Per-process memo for the created scratch dir, so repeated calls in one
@@ -32,16 +33,26 @@ export function _clearTestScratchTempRootCache() {
  * `temp/` telemetry tree — the regression that let 99% of friction records
  * be test-fixture pollution.
  *
+ * Reaping (Story #4808): the minting process registers removal of the
+ * scratch dir at exit. This branch is creator-only by construction — a
+ * process that inherited an absolute root returns above without ever
+ * touching the memo, so a child can never delete its parent's scratch
+ * while the parent is still writing to it. Left unreaped, this seam was
+ * the single largest contributor to the OS-temp-root leak (870 surviving
+ * `mandrel-test-temp-` roots on one host), because it mints one per
+ * `run-tests.js` invocation.
+ *
  * Directly unit-tested via the injectable `mkdtemp` seam in
  * `tests/lib/test-env.test.js` (Story #4711).
  *
  * @param {NodeJS.ProcessEnv} [baseEnv=process.env]
- * @param {{ mkdtemp?: typeof mkdtempSync }} [deps] Injectable for tests.
+ * @param {{ mkdtemp?: typeof mkdtempSync, onExit?: (fn: () => void) => void }} [deps]
+ *   Injectable for tests.
  * @returns {string} absolute scratch tempRoot
  */
 export function ensureTestScratchTempRoot(
   baseEnv = process.env,
-  { mkdtemp = mkdtempSync } = {},
+  { mkdtemp = mkdtempSync, onExit } = {},
 ) {
   const existing = baseEnv?.[TEST_TEMP_ROOT_ENV];
   if (
@@ -52,7 +63,8 @@ export function ensureTestScratchTempRoot(
     return existing;
   }
   if (_createdScratchDir === null) {
-    _createdScratchDir = mkdtemp(path.join(os.tmpdir(), 'mandrel-test-temp-'));
+    _createdScratchDir = mkdtemp(path.join(os.tmpdir(), 'mandrel-test-temp-')); // test-temp-allow: children inherit this path, so it lives outside the suite root.
+    reapOnExit(_createdScratchDir, onExit ? { onExit } : {});
   }
   return _createdScratchDir;
 }