mandrel 2.24.0 → 2.25.0

package/.agents/scripts/acceptance-eval.js

@@ -48,9 +48,14 @@
  *
  * Stdout: a single JSON envelope
  *   { storyId, epicId, decision, round, cap, capReached, totalCriteria,
- *     metCount, unmetCriteria[], signalEmitted }
+ *     metCount, unmetCriteria[], signalEmitted, replay, verdictFingerprint }
  *   (`epicId` is retained as a always-null field for envelope stability.)
  *
+ * Reading is free (Story #4874): re-invoking the gate over a verdict the
+ * ledger has already scored replays that round (`replay: true`,
+ * `signalEmitted: false`) instead of consuming one, so an unchanged verdict
+ * can never escalate from `redraft` to `block` by being looked at twice.
+ *
  * @see .agents/scripts/lib/orchestration/acceptance-eval-decision.js
  * @see .agents/schemas/acceptance-eval-verdict.schema.json
  */
@@ -69,8 +74,9 @@ import { Logger } from './lib/Logger.js';
 import { appendSignal } from './lib/observability/signals-writer.js';
 import {
   buildAcceptanceEvalSignal,
+  computeVerdictFingerprint,
   decideAcceptanceEval,
-  deriveAcceptanceEvalRound,
+  resolveAcceptanceEvalRound,
 } from './lib/orchestration/acceptance-eval-decision.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -166,7 +172,8 @@ function parseCliArgs(argv) {
  *   self-reported `round` is never load-bearing for the cap.
  * @param {object} [deps]
  * @param {Function} [deps.appendSignalFn]
- * @param {Function} [deps.deriveRoundFn]
+ * @param {Function} [deps.resolveRoundFn]
+ * @param {Function} [deps.fingerprintFn]
  * @returns {Promise<{ envelope: object, exitCode: number }>}
  */
 export async function runAcceptanceEval(
@@ -175,13 +182,23 @@ export async function runAcceptanceEval(
 ) {
   const {
     appendSignalFn = appendSignal,
-    deriveRoundFn = deriveAcceptanceEvalRound,
+    resolveRoundFn = resolveAcceptanceEvalRound,
+    fingerprintFn = computeVerdictFingerprint,
   } = deps;
   const { maxRounds } = getAcceptanceEval(config);
+  const verdictFingerprint = fingerprintFn(verdict);
+  // Story #4874: re-reading an already-scored verdict is a replay — it
+  // reports the round that verdict was scored under and appends nothing, so
+  // observation alone can never advance the counter or escalate a redraft.
+  const resolved = resolveRoundFn({
+    epicId: null,
+    storyId,
+    config,
+    verdictFingerprint,
+  });
+  const replay = resolved.replay === true;
   const resolvedRound =
-    Number.isInteger(round) && round >= 1
-      ? round
-      : deriveRoundFn({ epicId: null, storyId, config });
+    Number.isInteger(round) && round >= 1 ? round : resolved.round;
   const outcome = decideAcceptanceEval({
     verdict,
     maxRounds,
@@ -189,9 +206,14 @@ export async function runAcceptanceEval(
   });
 
   let signalEmitted = false;
-  if (emitSignal) {
+  if (emitSignal && !replay) {
     const signal = {
-      ...buildAcceptanceEvalSignal({ storyId, epicId: null, outcome }),
+      ...buildAcceptanceEvalSignal({
+        storyId,
+        epicId: null,
+        outcome,
+        verdictFingerprint,
+      }),
       ts: new Date().toISOString(),
     };
     try {
@@ -228,6 +250,10 @@ export async function runAcceptanceEval(
       evidence: c.evidence,
     })),
     signalEmitted,
+    // True when this invocation re-read a verdict the ledger had already
+    // scored: the round was replayed, not advanced, and nothing was appended.
+    replay,
+    verdictFingerprint,
   };
 
   // `block` is the only non-zero exit: the loop has exhausted its bounded

package/.agents/scripts/audit-labels-bootstrap.js

@@ -1,21 +1,20 @@
 /**
- * audit-labels-bootstrap.js — Idempotently create the `audit::<lens>`
- * label taxonomy in the configured GitHub repo.
+ * audit-labels-bootstrap.js — Idempotently create the audit label taxonomy in
+ * the configured GitHub repo.
  *
  * Run this once per repo before `/audit-to-stories` opens its first
  * Story. Re-runs are safe — existing labels are skipped, only missing
  * ones are created. Story #2583 acceptance criterion #6.
  *
- * The lens list is the shared SSOT `AUDIT_LENSES`
- * (`lib/audit-to-stories/audit-lenses.js`), one per `/audit-<lens>` workflow
- * under `.agents/workflows/`. Sourcing the list from the same module that
- * `build-story-body.js` derives `audit::<lens>` labels from guarantees the
- * label producer (this bootstrap) and the label deriver (story-body) cannot
- * drift — a finding from `audit-documentation-results.md` derives
- * `audit::documentation`, and this bootstrap creates exactly that label
- * (Story #4195). The per-lens colour/description metadata lives in
- * `LENS_META` below; adding a new `audit-*` workflow means adding its lens to
- * `AUDIT_LENSES` and (optionally) a `LENS_META` entry.
+ * This CLI is a thin creator over
+ * [`lib/audit-to-stories/audit-label-taxonomy.js`](lib/audit-to-stories/audit-label-taxonomy.js),
+ * which is the SSOT for **every** label an audit sweep creates or generates:
+ * the `audit::<lens>` set (derived from the shared `AUDIT_LENSES` list, one per
+ * `/audit-<lens>` workflow) plus the story-axis labels the filer applies. The
+ * creator and the generator (`build-story-body.js`) read that one list, so the
+ * bootstrap cannot fall behind the filer — the drift that left `risk::high`
+ * generated but defined nowhere (Story #4877), and that made `audit::<dimension>`
+ * labels mint from free-form prose before Story #4195.
  *
  * Delegates to `gh label create` so the script works without any
  * provider plumbing — `gh auth status` is the only prerequisite. Per
@@ -26,88 +25,11 @@
 import process from 'node:process';
 import { parseArgs } from 'node:util';
 
-import { AUDIT_LENSES } from './lib/audit-to-stories/audit-lenses.js';
+import { AUDIT_LABEL_TAXONOMY } from './lib/audit-to-stories/audit-label-taxonomy.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { gh as defaultGh, GhExecError } from './lib/gh-exec.js';
 
-/**
- * Per-lens label presentation. Keyed by canonical lens name. A lens absent
- * from this map falls back to {@link DEFAULT_LENS_META} so a newly-added
- * `AUDIT_LENSES` entry still gets a label without a hard requirement to
- * register colour/description here first.
- */
-const LENS_META = Object.freeze({
-  accessibility: {
-    color: 'c5def5',
-    description: 'Audit-sourced finding: WCAG accessibility conformance',
-  },
-  architecture: {
-    color: '6f42c1',
-    description: 'Audit-sourced finding: architectural concerns',
-  },
-  'clean-code': {
-    color: '0e8a16',
-    description: 'Audit-sourced finding: clean-code / maintainability',
-  },
-  dependencies: {
-    color: 'd4c5f9',
-    description: 'Audit-sourced finding: dependencies / supply chain',
-  },
-  devops: {
-    color: 'fbca04',
-    description: 'Audit-sourced finding: DevOps / CI / CD',
-  },
-  documentation: {
-    color: '1d76db',
-    description: 'Audit-sourced finding: documentation staleness / gaps',
-  },
-  navigability: {
-    color: 'bfdadc',
-    description: 'Audit-sourced finding: route / nav reachability',
-  },
-  performance: {
-    color: 'b60205',
-    description: 'Audit-sourced finding: performance / latency',
-  },
-  privacy: {
-    color: 'fef2c0',
-    description: 'Audit-sourced finding: privacy / data handling',
-  },
-  quality: {
-    color: '0052cc',
-    description: 'Audit-sourced finding: test quality / coverage gaps',
-  },
-  security: {
-    color: 'b60205',
-    description: 'Audit-sourced finding: security / OWASP',
-  },
-  seo: {
-    color: 'fbca04',
-    description: 'Audit-sourced finding: SEO / discoverability',
-  },
-  sre: {
-    color: '0052cc',
-    description: 'Audit-sourced finding: SRE / observability / reliability',
-  },
-  'ux-ui': {
-    color: 'd4c5f9',
-    description: 'Audit-sourced finding: UX / UI concerns',
-  },
-});
-
-const DEFAULT_LENS_META = Object.freeze({
-  color: 'ededed',
-  description: 'Audit-sourced finding',
-});
-
-const DIMENSIONS = Object.freeze(
-  AUDIT_LENSES.map((name) => ({
-    name,
-    ...(LENS_META[name] ?? DEFAULT_LENS_META),
-  })),
-);
-
 async function labelExists(gh, owner, repo, name) {
   try {
     const list = await gh.label.list(
@@ -166,9 +88,8 @@ export async function bootstrapAuditLabels({
   const skipped = [];
   const failed = [];
 
-  for (const dim of DIMENSIONS) {
-    const labelName = `audit::${dim.name}`;
-    const candidate = { ...dim, name: labelName };
+  for (const candidate of AUDIT_LABEL_TAXONOMY) {
+    const labelName = candidate.name;
 
     if (dryRun) {
       created.push(labelName);
@@ -190,7 +111,7 @@ export async function bootstrapAuditLabels({
     }
   }
 
-  return { created, skipped, failed, total: DIMENSIONS.length };
+  return { created, skipped, failed, total: AUDIT_LABEL_TAXONOMY.length };
 }
 
 /**
@@ -241,7 +162,7 @@ export function formatBootstrapReport(result) {
   };
 }
 
-export const __testing = { DIMENSIONS };
+export const __testing = { AUDIT_LABEL_TAXONOMY };
 
 async function main() {
   const { values } = parseArgs({

package/.agents/scripts/audit-to-stories.js

@@ -47,17 +47,34 @@ import { parseAuditReports } from './lib/audit-to-stories/parse-audit-md.js';
 import { buildPlanSeedMarkdown } from './lib/audit-to-stories/seed-from-findings.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { searchSemanticCandidates } from './lib/findings/semantic-issue-search.js';
+import { SEVERITIES, SEVERITY_RANK } from './lib/findings/severity.js';
 import { Logger } from './lib/Logger.js';
 import { parse as parseStoryBody } from './lib/story-body/story-body.js';
 
-const SEVERITY_RANK = { critical: 4, high: 3, medium: 2, low: 1 };
 const DEFAULT_GLOB = 'temp/audits/audit-*-results.md';
 const FAN_OUT_REPORT = 'audit-fan-out-results.md';
 
+/**
+ * Does `finding` clear the `threshold` severity floor?
+ *
+ * `SEVERITY_RANK` is imported from the canonical scale rather than declared
+ * here (Story #4877). The local copy this replaces ranked only four levels
+ * (`critical|high|medium|low`), so `info` — the canonical floor — ranked `0`,
+ * below even `--severity low`, and every informational finding was silently
+ * dropped from every filtered run. Sourcing the ranking from the SSOT means a
+ * level cannot exist in the vocabulary and be invisible to the filter.
+ *
+ * An unrecognised or absent severity still ranks below every real floor: it
+ * failed to parse, so it is not evidence that a threshold was met.
+ *
+ * @param {{ severity?: string }} finding
+ * @param {string} [threshold] — a canonical level, `'all'`, or falsy for no floor.
+ * @returns {boolean}
+ */
 function meetsSeverity(finding, threshold) {
   if (!threshold || threshold === 'all') return true;
   const minRank = SEVERITY_RANK[threshold] ?? 0;
-  const fRank = SEVERITY_RANK[finding.severity] ?? 0;
+  const fRank = SEVERITY_RANK[finding.severity] ?? -1;
   return fRank >= minRank;
 }
 
@@ -77,8 +94,21 @@ function readReports(paths) {
   }));
 }
 
+/**
+ * Count findings per severity bucket. The buckets are the canonical levels plus
+ * `unknown` for a finding whose severity did not parse — kept as a visible
+ * bucket so an unparseable severity is reported rather than absorbed into a
+ * real level. Derived from `SEVERITIES` so a new level appears in the tally
+ * automatically instead of falling into `unknown` (Story #4877).
+ *
+ * @param {Array<{ severity?: string }>} findings
+ * @returns {Record<string, number>}
+ */
 function tallyBySeverity(findings) {
-  const t = { critical: 0, high: 0, medium: 0, low: 0, unknown: 0 };
+  const t = {
+    ...Object.fromEntries(SEVERITIES.map((s) => [s, 0])),
+    unknown: 0,
+  };
   for (const f of findings) {
     if (Object.hasOwn(t, f.severity)) t[f.severity] += 1;
     else t.unknown += 1;

package/.agents/scripts/check-context-budget.js

@@ -47,9 +47,18 @@
  * Ratchet semantics (mirroring the sibling ratchets):
  *   - A gated tier grows beyond `baseline.tiers.<tier>.totalBytes +
  *     baseline.toleranceBytes` → exit 1, naming the tier and its delta.
- *   - A gated tier shrinks below its baseline total → printed as a `-`
- *     (removal) note, warning the baseline can be refreshed downward.
- *     Shrink-only exits 0.
+ *   - A gated tier shrinks below its baseline total → exit 1 (Story #4872).
+ *     A ratchet that only tightens in one direction lets every measured
+ *     improvement evaporate: the recorded total keeps promising headroom the
+ *     tree no longer spends, so the next growth is absorbed by stale slack
+ *     instead of being reported. Shrinkage is therefore **actionable** —
+ *     refresh the baseline down and the gain is locked in. Unlike growth this
+ *     is deliberately **zero-tolerance**: `toleranceBytes` exists to keep a
+ *     trivial addition from churning the file, and applying it downward would
+ *     silently discard every sub-tolerance gain.
+ *   - A recorded row naming a path the measured tier no longer contains →
+ *     exit 1. The row describes a file that has been deleted or de-listed, so
+ *     the bytes it contributes to the recorded total are fiction.
  *   - Within tolerance / clean → exit 0.
  *   - Baseline file absent → warn + exit 0 (no-op; nothing to ratchet against).
  *
@@ -303,16 +312,45 @@ export function buildBaseline(tierMap, toleranceBytes) {
   };
 }
 
+/**
+ * Collect the recorded rows of one gated tier that name a path the measured
+ * tier no longer contains (Story #4872). A deleted file drops out of the
+ * resolved tier, and so does one that has been de-listed from the read set —
+ * either way the row's bytes are counted into a recorded total that no live
+ * file backs, so the row is drift and not a detail.
+ *
+ * @param {string} tier
+ * @param {Array<{ path: string, bytes: number }>} files live tier measurement
+ * @param {{ files?: Array<{ path: string, bytes?: number }> }} baseTier recorded tier
+ * @returns {Array<{ tier: string, path: string, bytes: number|null }>}
+ */
+function absentRows(tier, files, baseTier) {
+  const live = new Set(files.map((f) => f.path));
+  const out = [];
+  for (const row of baseTier?.files ?? []) {
+    if (typeof row?.path !== 'string' || live.has(row.path)) continue;
+    out.push({
+      tier,
+      path: row.path,
+      bytes: Number.isFinite(row.bytes) ? row.bytes : null,
+    });
+  }
+  return out;
+}
+
 /**
  * Pure diff: compare the current tier map against the committed baseline. A
  * gated tier with no current files is skipped; a tier absent from the baseline
- * is skipped. `grown` entries fail the gate; `shrunk` entries are informational.
+ * is skipped. `grown`, `shrunk` and `absent` entries all fail the gate — see
+ * the ratchet semantics in the module header for why shrinkage is actionable
+ * rather than informational (Story #4872).
  *
  * @param {{ tiers: Record<string, Array<{ path: string, bytes: number }>> }} tierMap
  * @param {{ toleranceBytes?: number, tiers?: Record<string, { totalBytes: number }> }} baseline
  * @returns {{
  *   grown: Array<{ tier: string, current: number, baseline: number, tolerance: number, delta: number }>,
- *   shrunk: Array<{ tier: string, current: number, baseline: number }>,
+ *   shrunk: Array<{ tier: string, current: number, baseline: number, delta: number }>,
+ *   absent: Array<{ tier: string, path: string, bytes: number|null }>,
  *   skipped: string[],
  * }}
  */
@@ -322,6 +360,7 @@ export function diffBudget(tierMap, baseline) {
     : 0;
   const grown = [];
   const shrunk = [];
+  const absent = [];
   const skipped = [];
   for (const tier of GATED_TIERS) {
     const files = tierMap.tiers[tier] ?? [];
@@ -345,16 +384,42 @@ export function diffBudget(tierMap, baseline) {
         delta: current - baselineBytes,
       });
     } else if (current < baselineBytes) {
-      shrunk.push({ tier, current, baseline: baselineBytes });
+      // Deliberately zero-tolerance: `tolerance` guards against churn from a
+      // trivial *addition*; mirroring it downward would discard every gain
+      // smaller than the tolerance, which is the leak this branch closes.
+      shrunk.push({
+        tier,
+        current,
+        baseline: baselineBytes,
+        delta: baselineBytes - current,
+      });
     }
+    absent.push(...absentRows(tier, files, baseTier));
   }
-  return { grown, shrunk, skipped };
+  return { grown, shrunk, absent, skipped };
+}
+
+/**
+ * Count the drift entries that fail the gate. Every direction is actionable
+ * (Story #4872), so this is the one place the failure set is defined and both
+ * the summary tag and the exit code read it.
+ *
+ * @param {ReturnType<typeof diffBudget>} diff
+ * @returns {number}
+ */
+export function budgetFailureCount(diff) {
+  return (
+    (diff?.grown?.length ?? 0) +
+    (diff?.shrunk?.length ?? 0) +
+    (diff?.absent?.length ?? 0)
+  );
 }
 
 /**
  * Render the human-readable diff. `+` lines are tiers that grew beyond
- * tolerance (gate fail); `-` lines are tiers that shrank (refreshable
- * baseline). A one-line summary always follows.
+ * tolerance; `-` lines are tiers that shrank below their recorded total or
+ * rows naming a path the tree no longer carries. All three fail the gate. A
+ * one-line summary always follows.
  *
  * @param {ReturnType<typeof diffBudget>} diff
  * @returns {string}
@@ -368,12 +433,17 @@ export function renderDiff(diff) {
   }
   for (const s of diff.shrunk) {
     lines.push(
-      `- ${s.tier}: ${s.current} bytes below baseline ${s.baseline} — refresh baselines/context-budget.json`,
+      `- ${s.tier}: ${s.current} bytes is under the recorded ${s.baseline} (delta -${s.delta}) — the ratchet is holding slack the tree no longer spends; refresh baselines/context-budget.json`,
+    );
+  }
+  for (const a of diff.absent ?? []) {
+    lines.push(
+      `- ${a.tier}: recorded row ${a.path} names a path the measured tier no longer contains — refresh baselines/context-budget.json`,
     );
   }
-  const tag = diff.grown.length > 0 ? '(gate fail)' : '(ok)';
+  const tag = budgetFailureCount(diff) > 0 ? '(gate fail)' : '(ok)';
   lines.push(
-    `[context-budget] grown=${diff.grown.length} shrunk=${diff.shrunk.length} skipped=${diff.skipped.length} ${tag}`,
+    `[context-budget] grown=${diff.grown.length} shrunk=${diff.shrunk.length} absent=${diff.absent?.length ?? 0} skipped=${diff.skipped.length} ${tag}`,
   );
   return lines.join('\n');
 }
@@ -454,7 +524,7 @@ export async function runCli({
   if (!baseline) {
     if (json) {
       stdout.write(
-        `${JSON.stringify({ kind: 'context-budget-report', baselinePath: resolvedBaselinePath, tiers: tierMap.tiers, grown: [], shrunk: [], skipped: GATED_TIERS, exitCode: 0, noBaseline: true }, null, 2)}\n`,
+        `${JSON.stringify({ kind: 'context-budget-report', baselinePath: resolvedBaselinePath, tiers: tierMap.tiers, grown: [], shrunk: [], absent: [], skipped: GATED_TIERS, exitCode: 0, noBaseline: true }, null, 2)}\n`,
       );
     } else {
       stderr.write(
@@ -472,7 +542,7 @@ export async function runCli({
   const bootDrift = agentBootDrift(tierMap, baseline, ceiling);
   const permissiveDrift = bootDrift.filter((d) => d.direction === 'permissive');
   const exitCode =
-    diff.grown.length > 0 ||
+    budgetFailureCount(diff) > 0 ||
     bootOverflow.length > 0 ||
     permissiveDrift.length > 0
       ? 1
@@ -490,6 +560,7 @@ export async function runCli({
       ),
       grown: diff.grown,
       shrunk: diff.shrunk,
+      absent: diff.absent,
       skipped: diff.skipped,
       agentBootCeilingBytes: ceiling,
       agentBootOverflow: bootOverflow,
@@ -527,6 +598,16 @@ export async function runCli({
           `[context-budget] ❌ a documentation tier grew beyond tolerance — refresh the budget consciously with \`node .agents/scripts/check-context-budget.js --update\` once the growth is intentional\n`,
         );
       }
+      if (diff.shrunk.length > 0) {
+        stderr.write(
+          `[context-budget] ❌ a documentation tier came in under its recorded total — the ratchet is holding slack the tree no longer spends, so the next growth would be absorbed silently. Lock the gain in with \`node .agents/scripts/check-context-budget.js --update\`\n`,
+        );
+      }
+      if (diff.absent.length > 0) {
+        stderr.write(
+          `[context-budget] ❌ a recorded row names a path the measured tier no longer contains — its bytes inflate the recorded total against nothing. Refresh with \`node .agents/scripts/check-context-budget.js --update\`\n`,
+        );
+      }
     }
   }
 

package/.agents/scripts/check-test-temp-hygiene.js

@@ -78,6 +78,11 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runAsCli } from './lib/cli-utils.js';
+import { mainCheckoutRoot } from './lib/config/temp-paths.js';
+import {
+  isReservedTestId,
+  RESERVED_TEST_ID_BAND,
+} from './lib/reserved-test-ids.js';
 import {
   findRawTmpdirMkdtemp,
   listSuiteTempRoots,
@@ -369,6 +374,84 @@ export function cleanFixtureDirs({
   return { candidates, removed };
 }
 
+/**
+ * Every Epic / Story id a stream file's own path attributes it to.
+ *
+ * Both canonical layouts are read, and a nested Epic-attached stream yields
+ * both ids (`run-<eid>/stories/story-<sid>/…`): either half being a fixture id
+ * makes the stream fixture-owned, and taking only the outer one is how a
+ * fixture Story under a real run would slip past.
+ *
+ * @param {string} rel POSIX-normalised path relative to `temp/`.
+ * @returns {number[]}
+ */
+function streamOwnerIds(rel) {
+  const ids = [];
+  const run = /^run-(\d+)$/.exec(rel.split('/')[0]);
+  if (run) ids.push(Number(run[1]));
+  const story = /(?:^|\/)story-(\d+)\//.exec(rel);
+  if (story) ids.push(Number(story[1]));
+  return ids;
+}
+
+/**
+ * Stream files under `tempDir` owned by a **reserved test-fixture id**
+ * (Story #4892).
+ *
+ * This is the residual-pollution dimension the snapshot/assert bracket cannot
+ * cover: the bracket only runs in CI, where `temp/` starts empty, so a local
+ * run that appends fixture telemetry to the operator's live ledger was only
+ * ever discovered from the ticket the retro graduator filed off it (issue
+ * #4870 cited `#999999`, a `--story 999999` CLI spawn from the suite).
+ *
+ * Unlike the snapshot diff this needs no baseline and is immune to a
+ * concurrent delivery in another checkout: a reserved id is reserved *from*
+ * real work, so nothing but a test can own one of these files.
+ *
+ * @param {string} tempDir
+ * @returns {string[]} POSIX-normalised paths relative to `tempDir`, sorted.
+ */
+export function findReservedIdStreamFiles(tempDir) {
+  return listStreamFiles(tempDir).filter((rel) =>
+    streamOwnerIds(rel).some(isReservedTestId),
+  );
+}
+
+/**
+ * Post-run guard: fail when a test run left a fixture-id telemetry stream in
+ * the **repository-root** temp tree (Story #4892).
+ *
+ * Resolution matters more than it looks: every writer anchors a relative
+ * `tempRoot` to the *main checkout* (so a Story worktree and its `/deliver`
+ * host converge on one ledger), so a guard that scanned `cwd` would scan an
+ * empty worktree tree and pass vacuously on the very tree it is meant to
+ * protect. `resolveRoot` is the injection seam for tests.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd=process.cwd()]
+ * @param {(line: string) => void} [opts.log]
+ * @param {(cwd: string) => string|null} [opts.resolveRoot]
+ * @returns {number} exit code (0 clean, 1 polluted).
+ */
+export function assertNoReservedIdStreams({
+  cwd = process.cwd(),
+  log = (l) => process.stderr.write(`${l}\n`),
+  resolveRoot = mainCheckoutRoot,
+} = {}) {
+  const root = resolveRoot(cwd) ?? cwd;
+  const tempDir = tempDirFor(root);
+  const found = findReservedIdStreamFiles(tempDir);
+  if (found.length === 0) return 0;
+  log(
+    `[test-temp-hygiene] FAIL — ${found.length} fixture-id telemetry stream(s) in the real temp tree (${tempDir}):`,
+  );
+  for (const rel of found) log(`  + fixture ${rel}`);
+  log(
+    `[test-temp-hygiene] ids ${RESERVED_TEST_ID_BAND} are reserved for fixtures, so a test wrote to the live ledger — the retro graduator reads these streams and files tickets off them. Inject an absolute per-test tempRoot on the offending spawn, then remove the stream(s) with --clean --ids <id> --yes.`,
+  );
+  return 1;
+}
+
 /**
  * Parse the CLI argv into a normalised options object.
  * @param {string[]} argv

package/.agents/scripts/cleanup-repo-test-temp.js

@@ -3,9 +3,9 @@
 
 /**
  * Removes **test-reserved** per-Epic trees under `<repo>/temp/epic-<id>/` after
- * test runs. Only Epic IDs in the band defined by
- * `lib/test-reserved-epic-temp-ids.js` are deleted (999000–999999). Real Epic
- * scratch (e.g. `temp/epic-1143/`) is never touched.
+ * test runs. Only Epic IDs in the band declared by `lib/reserved-test-ids.js`
+ * are deleted (999000–999999). Real Epic scratch (e.g. `temp/epic-1143/`) is
+ * never touched.
  *
  * Keeps sibling dirs like `temp/epic-runner-logs/`, loose files, and
  * `temp/epic-<id>/` when `<id>` is outside that reserved band.
@@ -20,11 +20,13 @@
 import { existsSync, readdirSync, rmSync } from 'node:fs';
 import path from 'node:path';
 import { runAsCli } from './lib/cli-utils.js';
+import { isReservedTestId } from './lib/reserved-test-ids.js';
 
-const RESERVED_TEST_EPIC_TEMP_DIR = /^epic-999\d{3}$/;
+const EPIC_TEMP_DIR = /^epic-(\d+)$/;
 
 function isReservedTestEpicTempDirName(name) {
-  return RESERVED_TEST_EPIC_TEMP_DIR.test(name);
+  const match = EPIC_TEMP_DIR.exec(name);
+  return match !== null && isReservedTestId(Number(match[1]));
 }
 
 /**

package/.agents/scripts/deliver-light.js

@@ -337,10 +337,9 @@ async function runBackstopMode(values, deps = {}) {
     process.stderr.write(HELP);
     throw new Error('[deliver-light] --backstop requires --story <id>');
   }
-  const { result, nextCommand, exitCode, message } = await resolveFn({
-    storyId,
-  });
-  const extra = nextCommand === null ? {} : { nextCommand };
+  const { result, nextCommand, preservation, exitCode, message } =
+    await resolveFn({ storyId });
+  const extra = nextCommand === null ? {} : { nextCommand, preservation };
   emit({ mode: 'backstop', storyId, ...result, ...extra }, values.pretty);
   if (result.blocked) Logger.warn(message);
   else Logger.info(message);

package/.agents/scripts/deliver-recover.js

@@ -16,6 +16,14 @@
  * `single-story-init.js` hard-errors on an already-closed Story. Before this
  * surface, that Story had no automated way back.
  *
+ * Every command it prints **resumes** — it re-enters the in-flight worker or
+ * close, or closes the branch that is already pushed. None of them re-dispatch
+ * the Story, and that is deliberate: since Story #4876 the close-and-land tail
+ * belongs to the dispatching orchestrator, so a worker returning without a
+ * terminal envelope is the expected shape rather than evidence the Story never
+ * ran. Answering it with a fresh dispatch re-runs `single-story-init.js`
+ * underneath live work and puts a second close on one PR.
+ *
  * Usage:
  *   node .agents/scripts/deliver-recover.js --story <STORY_ID> [--cwd <main-repo>]
  *                                           [--json]
@@ -46,6 +54,11 @@ Probes a Story's live delivery state — labels, lease, branch, worktree, PR
 state and checks — and prints the single next command that resumes it, with
 the evidence it was derived from. Read-only: mutates nothing.
 
+The command always resumes the existing worker or close (or closes an already
+pushed branch); it never re-dispatches the Story, which would re-run init
+underneath live work. A worker that returned no terminal envelope is expected —
+the orchestrator owns the close-and-land tail.
+
 Mid-flight shapes (executing-*/closing-*) get a stability re-probe after a
 short settle window: matching shapes return the fresher verdict; diverging
 shapes report \`in-transition\` (a live delivery process is mutating the