mandrel 2.0.0 → 2.2.0

package/.agents/scripts/resolve-stories.js

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+
+/**
+ * resolve-stories.js — resolve a list of Story ids into the
+ * `{ stories, dag, done }` envelope `/deliver` sequences from.
+ *
+ * This is the ONE resolution step for multi-Story delivery. `/deliver` takes
+ * only Story ids; the graph is discovered here, from live state, rather than
+ * hand-transcribed by the host or implied by a batch label.
+ *
+ * What it resolves, per Story:
+ *   - the issue itself, fetched with **state=all** so an already-landed
+ *     sibling is present rather than silently dropped;
+ *   - its dependency edges: the union of body-parsed `blocked by #N` /
+ *     `depends on #N` and native GitHub `blocked_by` edges;
+ *   - its declared file footprint, as plain path strings, so the scheduler's
+ *     co-dispatch overlap guard has something to work with.
+ *
+ * And across the set: every dependency id — inside the requested set or
+ * foreign to it — is checked against live issue state, and a blocker that is
+ * closed or `agent::done` lands in `done[]`. That is what makes "deliver
+ * Stories across plan runs and over time" work: a Story whose blocker merged
+ * weeks ago in a different run is simply ready.
+ *
+ * Usage:
+ *   node .agents/scripts/resolve-stories.js --ids 101,102
+ *   node .agents/scripts/resolve-stories.js --ids 101,102 --pretty
+ *   node .agents/scripts/resolve-stories.js --ids 101 --no-native   # skip the dependencies API
+ *
+ * Exit codes: 0 ok, 1 usage/resolution error.
+ */
+
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
+import {
+  buildStoriesEnvelope,
+  isSatisfiedBlocker,
+  parseIds,
+  readNativeBlockedBy,
+  toStoryRecord,
+} from './lib/orchestration/resolve-stories.js';
+import { createProvider } from './lib/provider-factory.js';
+import { concurrentMap } from './lib/util/concurrent-map.js';
+import { parseApiJson } from './providers/github/request-helpers.js';
+
+export { buildStoriesEnvelope, parseIds, readNativeBlockedBy, toStoryRecord };
+
+/**
+ * Bounded concurrency for the per-issue round-trips. Matches the edge-writer's
+ * cap: modest enough for GitHub's secondary rate limits, while collapsing
+ * wall-clock from sum(round-trips) toward sum/concurrency.
+ */
+const FETCH_CONCURRENCY = 5;
+
+const HELP = `\
+Usage:
+  resolve-stories.js --ids <n,n,...> [--pretty] [--no-native]
+
+Resolve Story ids into the { stories, dag, done } envelope /deliver sequences
+from. Dependencies are discovered from live state: body edges union native
+blocked_by edges, with every blocker (in-set or foreign) resolved against its
+real issue state.
+
+Options:
+  --ids <csv>    Comma-separated Story issue numbers. Required.
+  --pretty       Pretty-print the JSON envelope.
+  --no-native    Skip the native blocked_by read (body edges only).
+  --help         Show this help.
+`;
+
+/**
+ * @param {object} [deps]
+ * @returns {{ provider: object, config: object }}
+ */
+export function resolveStoriesProvider({
+  resolveConfigFn = resolveConfig,
+  createProviderFn = createProvider,
+} = {}) {
+  const config = resolveConfigFn();
+  return { provider: createProviderFn(config), config };
+}
+
+/**
+ * Fetch every requested id and map it to a Story record, failing on the first
+ * id that is not a deliverable Story.
+ *
+ * @param {object} provider
+ * @param {number[]} ids
+ * @returns {Promise<object[]>}
+ */
+export async function fetchStories(provider, ids) {
+  return concurrentMap(
+    ids,
+    async (id) => {
+      const issue = await provider.getTicket(id);
+      if (!issue) {
+        throw new Error(`[resolve-stories] Issue #${id} was not found.`);
+      }
+      return toStoryRecord(issue, id);
+    },
+    { concurrency: FETCH_CONCURRENCY },
+  );
+}
+
+/**
+ * Read native blocked_by edges for every Story in the set.
+ *
+ * @returns {Promise<Map<number, number[]>>}
+ */
+export async function readNativeEdges({ provider, stories, owner, repo }) {
+  const entries = await concurrentMap(
+    stories,
+    async (story) => [
+      story.id,
+      await readNativeBlockedBy({
+        gh: provider._gh,
+        owner,
+        repo,
+        issueNumber: story.id,
+        parseJson: parseApiJson,
+      }),
+    ],
+    { concurrency: FETCH_CONCURRENCY },
+  );
+  return new Map(entries);
+}
+
+/**
+ * Resolve dependency ids that are NOT in the requested set against live issue
+ * state. A foreign blocker that already landed must enter `done[]`, or the
+ * scheduler withholds its dependent forever — the exact wedge that made
+ * cross-run delivery impossible.
+ *
+ * A foreign id that cannot be read is left OUT of `done[]`: unknown means
+ * "still gating", which withholds the dependent rather than dispatching it
+ * against a possibly-unlanded blocker.
+ *
+ * @returns {Promise<number[]>}
+ */
+export async function resolveForeignDone({ provider, dag, inSetIds }) {
+  const foreign = [
+    ...new Set(
+      dag.flatMap((node) => node.dependsOn).filter((dep) => !inSetIds.has(dep)),
+    ),
+  ];
+  if (foreign.length === 0) return [];
+  const resolved = await concurrentMap(
+    foreign,
+    async (id) => {
+      try {
+        const issue = await provider.getTicket(id);
+        return isSatisfiedBlocker(issue) ? id : null;
+      } catch (err) {
+        Logger.warn(
+          `[resolve-stories] Could not read foreign blocker #${id} (${err?.message ?? err}) — ` +
+            `treating it as still gating.`,
+        );
+        return null;
+      }
+    },
+    { concurrency: FETCH_CONCURRENCY },
+  );
+  return resolved.filter((id) => id !== null);
+}
+
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      ids: { type: 'string' },
+      pretty: { type: 'boolean', default: false },
+      native: { type: 'boolean', default: true },
+      help: { type: 'boolean', default: false },
+    },
+    // The documented opt-out is `--no-native`; without allowNegative,
+    // parseArgs rejects it as an unknown option and the CLI has no working
+    // way to skip the dependencies API.
+    allowNegative: true,
+    allowPositionals: false,
+  });
+
+  if (values.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  if (!values.ids) {
+    process.stderr.write(HELP);
+    throw new Error('[resolve-stories] --ids <n,n,...> is required');
+  }
+
+  // stdout is a JSON stream — keep human-readable output on stderr so a
+  // headless caller can pipe this straight into stories-wave-tick.js.
+  routeAllOutputToStderr();
+
+  const ids = parseIds(values.ids);
+  const { provider, config } = resolveStoriesProvider();
+  const owner = config.github?.owner;
+  const repo = config.github?.repo;
+
+  const stories = await fetchStories(provider, ids);
+  const nativeEdges = values.native
+    ? await readNativeEdges({ provider, stories, owner, repo })
+    : new Map();
+
+  const inSetIds = new Set(stories.map((s) => s.id));
+  const provisional = buildStoriesEnvelope({
+    stories,
+    nativeEdges,
+    warn: (m) => Logger.warn(m),
+  });
+  const foreignDone = await resolveForeignDone({
+    provider,
+    dag: provisional.dag,
+    inSetIds,
+  });
+  const envelope = buildStoriesEnvelope({
+    stories,
+    nativeEdges,
+    foreignDone,
+    warn: () => {},
+  });
+
+  process.stdout.write(
+    values.pretty
+      ? `${JSON.stringify(envelope, null, 2)}\n`
+      : `${JSON.stringify(envelope)}\n`,
+  );
+  return 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'resolve-stories',
+  propagateExitCode: true,
+});

package/.agents/scripts/run-coverage.js

@@ -45,6 +45,7 @@ import { fileURLToPath } from 'node:url';
 
 import { cleanupRepoTestTempArtifacts } from './cleanup-repo-test-temp.js';
 import { C8_CLI } from './lib/c8-cli-path.js';
+import { buildWebhookSafeTestEnv } from './lib/test-env.js';
 import { TEST_RUNNER_FLAGS } from './run-tests.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -89,7 +90,9 @@ function runCoveragePipeline() {
   const testRun = spawnSync(process.execPath, buildCoverageTestArgs(), {
     cwd: ROOT,
     stdio: 'inherit',
-    env: { ...process.env, NODE_V8_COVERAGE: V8_TMP },
+    // GIT_*-scrubbed: under a husky pre-push from a linked worktree the
+    // inherited GIT_DIR poisons fixture `git init` runs (#4580).
+    env: { ...buildWebhookSafeTestEnv(process.env), NODE_V8_COVERAGE: V8_TMP },
   });
 
   cleanupRepoTestTempArtifacts({ repoRoot: ROOT });

package/.agents/scripts/run-lint.js

@@ -73,8 +73,8 @@ const tasks = [
     // spans for axis-shaped tokens (`type/epic`, etc.) and asserts
     // only the canonical `<axis>::<value>` separator from
     // `lib/label-constants.js` appears. Closes the drift gap that
-    // let the original `type/epic` typo land at
-    // `.agents/workflows/helpers/plan-epic.md:49`.
+    // let the original `type/epic` typo land in a since-retired
+    // planning workflow helper.
     name: 'label-vocabulary',
     cmd: 'node',
     args: ['.agents/scripts/lint-label-vocabulary.js'],

package/.agents/scripts/run-verify.js

@@ -5,14 +5,28 @@
  * Local full verification — a true CI mirror for the gates that CAN be proven
  * locally, without epic-scoped MI projection or push semantics.
  *
- * Order: audit (SCA) → lint (includes docs:check) → full test suite →
- * unified baselines.
+ * Order: audit (SCA) → lint (includes docs:check + the arch-cycles ratchet) →
+ * full test suite → unified baselines → the dead-exports and context-budget
+ * ratchets.
  *
  * The `audit` step runs `npm audit --audit-level=high`, matching CI's
  * "Dependency Vulnerability Audit (SCA)" gate so a local green no longer hides
  * a high-severity advisory that CI would fail on. It is independent of the
  * pre-push `PREPUSH_AUDIT` opt-in, which stays unchanged.
  *
+ * The trailing ratchets complete the mirror of CI's "Architecture Cycle Check"
+ * step in the `baselines` job (Story #4549). That step runs three checks;
+ * `check-arch-cycles.js` is deliberately absent from STEPS because the `lint`
+ * step above already runs it (see run-lint.js) — re-running it here would
+ * double-pay a gate verify already covers. `check-dead-exports.js` and
+ * `check-context-budget.js` had no such cover: they were reachable locally only
+ * via the diff-scoped `npm run quality:preview` or a direct invocation, so a
+ * clean `verify` could still hide a CI-red — the failure Story #4531 / PR #4548
+ * paid for with a full push → CI → fix → push round-trip. Both are pure-Node
+ * and baseline-aware, adding ~15s on a cold cache (dominated by knip's
+ * full-tree scan in check-dead-exports.js) to a command that already carries
+ * the full test suite.
+ *
  * A handful of CI gates cannot be reproduced by this command (action pinning,
  * TruffleHog secret scan, the BASELINE_SCOPE=full push-scoped maintainability
  * run) — those are catalogued in docs/ci-contract.md.
@@ -34,6 +48,21 @@ const STEPS = [
     cmd: 'node',
     args: ['.agents/scripts/check-baselines.js'],
   },
+  {
+    label: 'dead-exports',
+    cmd: 'node',
+    args: ['.agents/scripts/check-dead-exports.js'],
+  },
+  {
+    label: 'dead-exports-production',
+    cmd: 'node',
+    args: ['.agents/scripts/check-dead-exports.js', '--production'],
+  },
+  {
+    label: 'context-budget',
+    cmd: 'node',
+    args: ['.agents/scripts/check-context-budget.js'],
+  },
 ];
 
 export function runVerifySteps({

package/.agents/scripts/signals-view.js

@@ -174,13 +174,13 @@ function describeEvent(evt) {
  * `process.stdout.write`). Logger is intentionally not used: the
  * viewer's contract is "dumb terminal compatible, parseable output".
  *
- * @param {{ epic: number | null, stories: Array<object> }} tree
+ * @param {{ run: number | null, stories: Array<object> }} tree
  * @param {{ storyFilter?: number | null }} [opts]
  * @returns {void}
  */
 export function renderTree(tree, opts = {}) {
   const filter = opts.storyFilter ?? null;
-  println(`Run #${tree.epic ?? '?'}`);
+  println(`Run #${tree.run ?? '?'}`);
   const stories =
     filter == null ? tree.stories : tree.stories.filter((s) => s.id === filter);
 
@@ -231,10 +231,10 @@ export async function main(argv, deps = {}) {
   const buildSpanTree = deps.buildSpanTree ?? signals.buildSpanTree;
   const config = buildConfig(tempRoot);
 
-  // The reader API still accepts the historical `epic` key while resolving
-  // the run directory through temp-paths (`temp/run-<id>/`).
+  // The reader resolves the run directory through temp-paths
+  // (`temp/run-<id>/`) keyed by the `run` id.
   const iter = read(
-    story != null ? { epic: runId, story, config } : { epic: runId, config },
+    story != null ? { run: runId, story, config } : { run: runId, config },
   );
 
   // Eagerly collect to detect the missing-file case before we start
@@ -267,11 +267,10 @@ export async function main(argv, deps = {}) {
   }
 
   // Pin the run id on the tree to the requested one — `buildSpanTree`
-  // stores it in the legacy `epic` field from the first observed event,
-  // which is normally the same, but if every event lacks that field the
-  // tree's `epic` would be
-  // `null` while we still know what was requested.
-  if (tree.epic == null) tree = { ...tree, epic: runId };
+  // stores it in the `run` field from the first observed event, which is
+  // normally the same, but if every event lacks that field the tree's
+  // `run` would be `null` while we still know what was requested.
+  if (tree.run == null) tree = { ...tree, run: runId };
 
   renderTree(tree, { storyFilter: story });
   return 0;

package/.agents/scripts/single-story-close.js

@@ -21,14 +21,17 @@
  *                          the post-merge confirmation step,
  *                          `single-story-confirm-merge.js`)
  *   8. worktree-reap     — drop the per-Story worktree
- *   9. confirm-merge      — Story #4428, headless-only (`--wait-merge`):
+ *   9. confirm-merge      — close-and-land (Story #4428; the DEFAULT for
+ *                          every run since `delivery.routing.closeAndLand`):
  *                          poll the just-armed PR to merge confirmation
- *                          (reusing `confirmStoryMerged`) or terminate
- *                          `agent::blocked` with a classified
- *                          `merge.unlanded` lifecycle event. Attended runs
- *                          (the default, no `--wait-merge`) skip this
- *                          phase entirely and keep resting at
- *                          `agent::closing`, exactly as before.
+ *                          (reusing `confirmStoryMerged`), capture the
+ *                          Story follow-ups, or terminate `agent::blocked`
+ *                          with a classified `merge.unlanded` event — or
+ *                          `merge.flip-failed` when the merge landed and
+ *                          only the label write failed. Skipped when the
+ *                          operator owns the merge (`--no-wait-merge`,
+ *                          `--no-auto-merge`, or `autoMerge: "strict"`),
+ *                          which rests at `agent::closing` for the human.
  *
  * Existing tests import the re-exported helpers
  * (`runSingleStoryClose`, `ensurePullRequest`, `parsePrNumber`,
@@ -38,24 +41,55 @@
  * Usage:
  *   node single-story-close.js --story <STORY_ID> [--cwd <main-repo>]
  *                              [--skip-validation] [--skip-sync]
- *                              [--no-auto-merge] [--no-full-scope-crap]
+ *                              [--no-auto-merge]
  *                              [--wait-merge | --no-wait-merge]
  *
- * `--wait-merge` is the headless must-land signal (Story #4428, Epic
- * #4425): the invoking surface (a headless `/deliver` run or a CI-driven
- * wrapper) opts in explicitly — attended runs never pass it, so the default
- * exit shape (rest at `agent::closing`, issue OPEN) is unchanged.
- * `--no-wait-merge` is the explicit opt-out that always wins over
- * `--wait-merge`, for a caller that wants to manage merge confirmation
- * externally even in an otherwise headless context.
+ * Close-and-land is the DEFAULT for every run (Story #4428 introduced it as
+ * `--wait-merge`; `delivery.routing.closeAndLand` — default `true` — made it
+ * the default, and Story #4539 made that knob actually readable). Resolution
+ * order, highest first: `--no-wait-merge` (explicit opt-out, always wins);
+ * operator-owns-the-merge (`--no-auto-merge` or `delivery.ci.autoMerge:
+ * "strict"` — the PR was deliberately left un-armed, so there is nothing to
+ * land and the Story rests at `agent::closing`); explicit `--wait-merge`;
+ * then the config. A genuine arm FAILURE is not an opt-out — it still waits
+ * and therefore still blocks, which is what keeps the must-land contract
+ * intact.
  *
- * Exit codes: 0 ok, 1 error (including a headless `--wait-merge` run that
- * gave up without a confirmed merge — see phase 9 above).
+ * Every invocation emits ONE schema-validated terminal envelope
+ * (`.agents/schemas/story-deliver-terminal.schema.json`, Story #4543) on
+ * stdout between `--- STORY DELIVER TERMINAL ---` markers. Its `status` is
+ * the contract; the exit code mirrors it:
+ *
+ *   0 — `landed`:  the PR merged, the Story is `agent::done`, and the
+ *                  post-land tail ran (follow-ups, status resync, local ref
+ *                  cleanup, base fast-forward).
+ *   3 — `pending`: RESUMABLE, not a failure. Either the per-invocation merge
+ *                  wait (`delivery.mergeWatch.maxWaitSeconds`, default 300s
+ *                  to fit a single host tool invocation) expired with the PR
+ *                  still healthy and in flight, or the operator owns the
+ *                  merge (`--no-wait-merge` / `--no-auto-merge` /
+ *                  `autoMerge: "strict"`). NO label was mutated and no
+ *                  `merge.unlanded` event was emitted. The envelope's
+ *                  `nextCommand` names the single command that resumes it,
+ *                  and the cumulative budget is anchored at the PR's
+ *                  createdAt so the resume does not restart the clock.
+ *   1 — `blocked` or `failed`: a classified hard block (the Story carries
+ *                  `agent::blocked` and a friction comment) or a phase crash.
+ *
+ * The distinct `pending` code is the point: before it, a close-and-land whose
+ * CI outlived the host's tool-invocation ceiling was killed mid-poll with no
+ * terminal path taken at all, and merely shrinking the budget instead would
+ * have misfiled every slow-CI run as a hard block.
  *
  * @see .agents/workflows/helpers/deliver-story.md
+ * @see .agents/schemas/story-deliver-terminal.schema.json
  */
 
+import { parseSprintArgs } from './lib/cli-args.js';
 import { runAsCli } from './lib/cli-utils.js';
+import { formatCliError } from './lib/error-redactor.js';
+import { Logger } from './lib/Logger.js';
+import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
 import { enableAutoMergeWith } from './lib/orchestration/single-story-close/phases/auto-merge.js';
 import {
   buildSyncFailureCommentBody,
@@ -67,6 +101,12 @@ import {
   runStoryScopeReview,
 } from './lib/orchestration/single-story-close/phases/code-review.js';
 import { ensurePullRequestWith } from './lib/orchestration/single-story-close/phases/pull-request.js';
+import {
+  buildTerminalEnvelope,
+  emitTerminalEnvelope,
+  exitCodeForTerminal,
+  NEXT_COMMANDS,
+} from './lib/orchestration/story-deliver-terminal.js';
 
 // Story #2990 moved the `gh`-spawn boundary into the `lib/gh-exec.js`
 // facade (the same shim the `providers/github/` gateways use). The
@@ -94,6 +134,121 @@ export async function runSingleStoryClose(opts) {
   return mod.runSingleStoryClose(opts);
 }
 
-runAsCli(import.meta.url, runSingleStoryClose, {
+/**
+ * The close pipeline's phase order, as `setPhase` walks it. Only used to
+ * decide whether a gate had already run when a later phase died.
+ */
+const PHASE_ORDER = Object.freeze([
+  'init',
+  'wrong-tree-guard',
+  'close-validation',
+  'base-sync',
+  'push',
+  'pull-request',
+  'code-review',
+  'auto-merge',
+  'confirm-merge',
+  'post-land',
+  'done',
+]);
+
+/** Each reported gate and the pipeline phase that decides it. */
+const GATE_PHASES = Object.freeze([
+  ['validation', 'close-validation'],
+  ['baseSync', 'base-sync'],
+  ['codeReview', 'code-review'],
+]);
+
+/**
+ * Report every gate's outcome for a run that died at `phase`.
+ *
+ * The schema's contract: "A gate the run skipped … reports `skipped` rather
+ * than being omitted, so a missing gate is never mistaken for a passing one."
+ * The previous shape named only the gate that died and omitted the rest
+ * entirely — exactly the ambiguity the contract forbids.
+ *
+ * Reconstructed from the phase order, which is sound because the pipeline is
+ * strictly sequential: reaching phase N means every gate before it completed.
+ * A gate whose phase the run never reached is `skipped`; one the operator
+ * turned off via `--skip-validation` / `--skip-sync` is `skipped` too (it did
+ * not pass — it never ran).
+ *
+ * @param {string} phase The phase the run died in.
+ * @param {{ skipValidation?: boolean, skipSync?: boolean }} args Parsed CLI args.
+ * @returns {Record<string, 'passed'|'failed'|'skipped'>}
+ */
+export function gatesForFailedPhase(phase, args = {}) {
+  const skipped = { validation: args.skipValidation, baseSync: args.skipSync };
+  const failedAt = PHASE_ORDER.indexOf(phase);
+  const gates = {};
+  for (const [gate, gatePhase] of GATE_PHASES) {
+    const at = PHASE_ORDER.indexOf(gatePhase);
+    if (gatePhase === phase) gates[gate] = 'failed';
+    else if (failedAt < 0 || at > failedAt) gates[gate] = 'skipped';
+    else gates[gate] = skipped[gate] ? 'skipped' : 'passed';
+  }
+  return gates;
+}
+
+/**
+ * Build the `failed` terminal for a phase that crashed.
+ *
+ * The runner deliberately throws rather than returning a failure (a red gate
+ * must not look like a return value), so without this the most common
+ * non-happy ending — a failing close-validation gate — would emit **no
+ * envelope at all**, exiting 1 with only a stderr line while the workflow
+ * docs promise the agent a `failed` envelope naming the phase. Every close
+ * invocation emits exactly one envelope; this is the path that keeps that
+ * true when a phase dies.
+ *
+ * `err.closePhase` is tagged by the runner's phase tracker.
+ *
+ * @param {unknown} err
+ * @returns {object|null} A validated envelope, or null when even the story id
+ *   is unknown (a usage error — there is nothing to report an envelope about).
+ */
+function failedTerminalFor(err) {
+  const phase = err?.closePhase ?? 'init';
+  const args = parseSprintArgs();
+  const storyId = Number(args.storyId);
+  if (!Number.isInteger(storyId) || storyId <= 0) return null;
+  return buildTerminalEnvelope({
+    storyId,
+    status: 'failed',
+    phase,
+    gates: gatesForFailedPhase(phase, args),
+    failure: { reason: String(err?.message ?? err) },
+    nextCommand: NEXT_COMMANDS.recover(storyId),
+    elapsedSeconds: 0,
+  });
+}
+
+/**
+ * CLI entry — resolves the process exit code from the terminal envelope's
+ * status rather than from a thrown/not-thrown distinction, so `pending`
+ * (resumable) is distinguishable from `blocked` (come look) without parsing
+ * stdout.
+ */
+async function main() {
+  try {
+    const outcome = await runSingleStoryClose();
+    return exitCodeForTerminal(outcome?.terminal ?? { status: 'failed' });
+  } catch (err) {
+    const terminal = failedTerminalFor(err);
+    if (!terminal) throw err;
+    // Mirror runAsCli's default error line (which this catch pre-empts) so the
+    // human-facing failure text is unchanged, then emit the envelope.
+    Logger.error(`[single-story-close] Fatal error: ${formatCliError(err)}`);
+    emitTerminalEnvelope(terminal);
+    // Story #4578 — a close that died before the runner could report its own
+    // terminal is exactly the friction the retro must see, so the crash path
+    // gets the same emit the happy path does. Best-effort; cannot throw.
+    await emitTerminalFriction({ envelope: terminal });
+    return exitCodeForTerminal(terminal);
+  }
+}
+
+runAsCli(import.meta.url, main, {
   source: 'single-story-close',
+  propagateExitCode: true,
 });