mandrel 1.94.0 → 2.1.0

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

@@ -5,7 +5,7 @@
  * Task #1463).
  *
  * Reads signals via `lib/signals/read`, materialises a span-tree via
- * `lib/signals/buildSpanTree`, and prints a readable Epic → Story → Task →
+ * `lib/signals/buildSpanTree`, and prints a readable run → Story →
  * events tree to stdout. The output is **plain text via
  * `process.stdout.write`** — no Ink, no blessed, no terminal-control
  * escape sequences — so it works on Windows + bash hosts (see
@@ -16,10 +16,10 @@
  * stdout uses `process.stdout.write`, not the console).
  *
  * Usage:
- *   node .agents/scripts/signals-view.js <epic-id> [--story <id>]
+ *   node .agents/scripts/signals-view.js <run-id> [--story <id>]
  *
  * Args:
- *   <epic-id>            Positive integer Epic ID. Required.
+ *   <run-id>             Positive integer run ID. Required.
  *   --story <id>         Optional positive integer Story ID. When set,
  *                        narrows the printed tree to a single Story
  *                        subtree.
@@ -27,7 +27,7 @@
  * Exit codes:
  *   0  — happy path, OR missing signals file (friendly message printed,
  *        no stack trace).
- *   1  — bad arguments (non-integer epic, missing positional, etc.).
+ *   1  — bad arguments (non-integer run, missing positional, etc.).
  *
  * Tempfile contract:
  *   The viewer resolves the on-disk signals path via the configured
@@ -57,7 +57,7 @@ function println(line) {
 }
 
 const USAGE =
-  'Usage: node .agents/scripts/signals-view.js <epic-id> [--story <id>] [--temp-root <path>]';
+  'Usage: node .agents/scripts/signals-view.js <run-id> [--story <id>] [--temp-root <path>]';
 
 /**
  * Parse a token as a strict positive integer (no leading +, no float, no
@@ -86,7 +86,7 @@ const HELP_FLAGS = new Set(['--help', '-h']);
  * print a friendly message and exit 1 without a stack trace.
  *
  * Delegates the flag walking to `parseStandardCliArgs` and post-validates
- * the diagnose-specific invariants (single positional epic-id, strictly
+ * the signals-view-specific invariants (single positional run-id, strictly
  * positive integers for both ids).
  *
  * @param {string[]} argv
@@ -94,7 +94,7 @@ const HELP_FLAGS = new Set(['--help', '-h']);
  */
 export function parseArgs(argv) {
   if (!Array.isArray(argv) || argv.length === 0) {
-    return err(`missing <epic-id>. ${USAGE}`);
+    return err(`missing <run-id>. ${USAGE}`);
   }
   if (argv.some((t) => HELP_FLAGS.has(t))) return err(USAGE);
 
@@ -118,7 +118,7 @@ export function parseArgs(argv) {
   // Exactly one positional, which must be a strictly positive integer
   // (no leading `+`, no float, no trailing junk).
   if (positionals.length === 0) {
-    return err(`missing <epic-id>. ${USAGE}`);
+    return err(`missing <run-id>. ${USAGE}`);
   }
   if (positionals.length > 1) {
     return err(`unexpected token ${JSON.stringify(positionals[1])}. ${USAGE}`);
@@ -126,7 +126,7 @@ export function parseArgs(argv) {
   const epic = parseStrictPositiveInt(positionals[0]);
   if (epic == null) {
     return err(
-      `<epic-id> must be a positive integer; got ${JSON.stringify(positionals[0])}. ${USAGE}`,
+      `<run-id> must be a positive integer; got ${JSON.stringify(positionals[0])}. ${USAGE}`,
     );
   }
 
@@ -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(`Epic #${tree.epic ?? '?'}`);
+  println(`Run #${tree.run ?? '?'}`);
   const stories =
     filter == null ? tree.stories : tree.stories.filter((s) => s.id === filter);
 
@@ -226,12 +226,16 @@ export async function main(argv, deps = {}) {
     println(parsed.error);
     return 1;
   }
-  const { epic, story, tempRoot } = parsed;
+  const { epic: runId, story, tempRoot } = parsed;
   const read = deps.read ?? signals.read;
   const buildSpanTree = deps.buildSpanTree ?? signals.buildSpanTree;
   const config = buildConfig(tempRoot);
 
-  const iter = read(story != null ? { epic, story, config } : { epic, config });
+  // The reader resolves the run directory through temp-paths
+  // (`temp/run-<id>/`) keyed by the `run` id.
+  const iter = read(
+    story != null ? { run: runId, story, config } : { run: runId, config },
+  );
 
   // Eagerly collect to detect the missing-file case before we start
   // printing — when the iterator yields nothing we want a friendly
@@ -241,7 +245,7 @@ export async function main(argv, deps = {}) {
     tree = await buildSpanTree(iter);
   } catch (err) {
     println(
-      `signals: failed to read signals for Epic #${epic}: ${
+      `signals: failed to read signals for run #${runId}: ${
         err instanceof Error ? err.message : String(err)
       }`,
     );
@@ -250,7 +254,7 @@ export async function main(argv, deps = {}) {
 
   if (tree.stories.length === 0) {
     const scope = story != null ? ` (Story #${story})` : '';
-    println(`No signals found for Epic #${epic}${scope}.`);
+    println(`No signals found for run #${runId}${scope}.`);
     return 0;
   }
 
@@ -258,15 +262,15 @@ export async function main(argv, deps = {}) {
   // `story` is omitted. If the requested Story filter doesn't match any
   // observed Story id, treat that as the missing-file case too.
   if (story != null && !tree.stories.some((s) => s.id === story)) {
-    println(`No signals found for Epic #${epic} (Story #${story}).`);
+    println(`No signals found for run #${runId} (Story #${story}).`);
     return 0;
   }
 
-  // Pin the Epic id on the tree to the requested one — `buildSpanTree`
-  // pins it from the first observed event, which is normally the same,
-  // but if every event lacks an `epic` field the tree's `epic` would be
-  // `null` while we still know what was requested.
-  if (tree.epic == null) tree = { ...tree, epic };
+  // Pin the run id on the tree to the requested one — `buildSpanTree`
+  // 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

@@ -1,13 +1,11 @@
 #!/usr/bin/env node
 
 /**
- * single-story-close.js — Close a standalone Story (no parent Epic).
+ * single-story-close.js — Close a Story against `main` (v2 `/deliver` path).
  *
- * Thin CLI entry for the `/single-story-deliver` workflow. Counterpart to
- * `story-close.js`, but skips the Epic-attached machinery (epic-merge-lock,
- * dispatchRecovery, auto-refresh, post-merge pipeline) because a standalone
- * Story has no parent to cascade to and reaches `main` via a human-approved
- * PR rather than an in-script merge.
+ * Thin CLI entry for `/deliver` / `helpers/deliver-story`. Opens a PR from
+ * `story-<id>` to `project.baseBranch`, runs Story-scope review, and arms
+ * auto-merge. There is no Epic parent, epic-merge-lock, or wave merge.
  *
  * Pipeline (each step is a phase under
  * `./lib/orchestration/single-story-close/phases/`):
@@ -23,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`,
@@ -40,25 +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 `/single-story-deliver` run, a
- * CI-driven wrapper, or `/deliver`'s standalone multi-Story fan-out) 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:
  *
- * @see .agents/workflows/helpers/single-story-deliver.md
+ *   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,
@@ -70,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
@@ -97,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,
 });