mandrel 2.60.0 → 2.62.0

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

@@ -1,17 +1,7 @@
 /**
- * single-story-close/failed-terminal.js — the `failed` terminal a close
- * emits when a phase crashes, and the gate reconstruction it carries.
- *
- * Split out of `single-story-close.js` so the CLI entry stays an entry: it
- * parses args, dispatches the runner, and maps a terminal onto an exit code.
- * The reasoning about which gates had run by the time a phase died belongs
- * with the envelope it feeds, not in the file that owns process lifetime.
- *
- * 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.
+ * single-story-close/failed-terminal.js — the `failed` envelope a close
+ * emits when a phase throws, so a crashed close still reports which phase
+ * died and which gates had run.
  */
 
 import { Logger } from '../../Logger.js';
@@ -21,16 +11,12 @@ import {
 } from '../story-deliver-terminal.js';
 
 /**
- * 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.
+ * The phase order `setPhase` walks; it MUST track `runPrePushPhases`, since
+ * it decides which gates had cleared when a later phase died.
  */
 const PHASE_ORDER = Object.freeze([
   'init',
   'wrong-tree-guard',
-  // Story #5172 — base-sync now precedes close-validation, so the tree the
-  // gates validate is the tree the push sends. The order here is not
-  // decoration: it is how a failed terminal decides which gates had already
-  // cleared, so it MUST track `runPrePushPhases`.
   'base-sync',
   'close-validation',
   'push',
@@ -42,7 +28,6 @@ const PHASE_ORDER = Object.freeze([
   'done',
 ]);
 
-/** Each reported gate and the pipeline phase that decides it. */
 const GATE_PHASES = Object.freeze([
   ['validation', 'close-validation'],
   ['baseSync', 'base-sync'],
@@ -50,18 +35,9 @@ const GATE_PHASES = Object.freeze([
 ]);
 
 /**
- * The names the unified baselines gate can register under, mirrored from
- * `BASELINES_GATE_NAMES` in `lib/close-validation/gates.js` (Story #5172) —
- * all three, matching the projection the SUCCESS path applies in
- * `runner.js#baselinesEnvelopeGates`, so the two endings of one run cannot
- * key the same gate differently.
- *
- * Deliberately a local copy rather than an import: several close suites
- * replace that module wholesale via `t.mock.module`, and a named import here
- * would fail to link against a mock that does not re-export the constant —
- * turning an unrelated test's mock into a load error on the CLI's own entry
- * path. `tests/close-validation-gates-enum.test.js` pins the two lists
- * against each other so the copy cannot drift.
+ * Mirrors `BASELINES_GATE_NAMES` in `lib/close-validation/gates.js`. A local
+ * copy, not an import, because close suites mock that module wholesale and a
+ * named import would fail to link; a test pins the two lists equal.
  */
 const BASELINES_ENTRY_NAMES = Object.freeze([
   'check-baselines',
@@ -70,21 +46,8 @@ const BASELINES_ENTRY_NAMES = Object.freeze([
 ]);
 
 /**
- * Project the baselines entries out of the per-gate outcomes THIS run
- * observed (Story #5279).
- *
- * This used to RECONSTRUCT them: it inferred, from the phase the run died in
- * plus the name of the failing gate, what the two split entries "must have"
- * done — and it did so over a hardcoded pair, so every failed close reported
- * both split names whether or not the run had ever registered them. A repo
- * whose config resolves to the unsplit `check-baselines`, or to only one half
- * of the pair, got envelope keys for gates that did not exist; a run that
- * died at `init` got them too, reported as `skipped`, which reads as "the
- * gate was turned off" rather than "there was no such gate".
- *
- * Reporting instead of reconstructing removes the whole class: an outcome
- * appears only for a gate the run actually observed, and the runner tags
- * exactly that set onto the error (`err.closeGates`).
+ * Baselines outcomes the run actually observed (`err.closeGates`) — reported,
+ * never reconstructed, so a gate the run never registered cannot appear.
  *
  * @param {Record<string, string>|null|undefined} observedGates
  * @returns {Record<string, 'passed'|'failed'|'skipped'>}
@@ -98,30 +61,12 @@ function baselinesGatesObserved(observedGates) {
 }
 
 /**
- * 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).
- *
- * Story #5172 — the reported set also carries the baselines entries under
- * their own names, so a failed close says WHICH half of the baselines gate
- * breached instead of a single generic verdict. Story #5279 — those names
- * are REPORTED from `observedGates`, never reconstructed, so only a gate the
- * run registered can appear.
+ * Every gate's outcome, never omitted (a missing gate would read as passing);
+ * an unreached or operator-skipped gate is `skipped`.
  *
  * @param {string} phase The phase the run died in.
  * @param {{ skipValidation?: boolean, skipSync?: boolean,
  *   observedGates?: Record<string, string>|null }} args
- *   Parsed CLI args, plus the per-gate outcomes the runner tagged onto the
- *   error.
  * @returns {Record<string, 'passed'|'failed'|'skipped'>}
  */
 export function gatesForFailedPhase(phase, args = {}) {
@@ -138,31 +83,13 @@ export function gatesForFailedPhase(phase, args = {}) {
 }
 
 /**
- * Build the `failed` terminal for a phase that crashed. 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.
- *
- * **Never throws.** This runs on the path that already has one failure in
- * hand, so a second failure here must not REPLACE the first: an
- * envelope-build error surfacing as the run's cause sends the operator to
- * diagnose the wrong thing entirely — a close whose PR had already merged
- * once reported a schema `ENOENT` as its fatal error, because the worktree
- * holding the script had been reaped mid-run. On failure this returns null
- * and the caller rethrows the original.
- *
- * `err.closeGates` — tagged by the runner — carries the per-gate outcomes the
- * run observed, which is what lets the reported gates name the baselines
- * entries that actually ran (Story #5172 / #5279) instead of a hardcoded pair.
+ * Never throws: a build failure here must not replace the original error as
+ * the run's reported cause, so it returns null and the caller rethrows.
+ * `err.closePhase` and `err.closeGates` are tagged by the runner.
  *
  * @param {unknown} err
  * @param {{ storyId?: string|number, skipValidation?: boolean, skipSync?: boolean }} args
- *   Parsed CLI args — the story id the envelope reports on, plus the skip
- *   flags `gatesForFailedPhase` needs.
- * @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)
- *   or the envelope itself could not be assembled.
+ * @returns {object|null} null when the story id is unknown or assembly failed.
  */
 export function failedTerminalFor(err, args = {}) {
   const phase = err?.closePhase ?? 'init';

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

@@ -1,59 +1,10 @@
 /**
- * single-story-close/gate-log.js — bounded gate output for the close path
- * (Story #4736).
+ * single-story-close/gate-log.js — captures close gate output to an artifact;
+ * success emits a digest line, failure replays the tail inline. Never throws.
  *
- * ## Why
- *
- * `runCloseValidation` streams every child gate's stdout/stderr line through
- * an injected `log`, and the close phase used to hand it `Logger.info` — whose
- * default sink is `console.log`. A single successful close therefore wrote the
- * whole of `npm test`, the linter, and the baseline checks onto the invoking
- * agent's stdout: ~50KB, over the host's inline tool-result ceiling. The caller
- * got a truncated preview, had to open the persisted file anyway, and re-ran
- * close for a clean envelope — burning the run's most expensive stretch to
- * re-derive output it already had.
- *
- * Story #4708 set the contract this restores compliance with (see
- * `rules/orchestration-error-handling.md` § Output Contract): compact digest
- * plus an on-disk artifact path, ≤ ~2KB on the **default success path**.
- *
- * ## The shape
- *
- * A sink captures every gate line to a log under the gitignored temp tree and
- * emits nothing inline. What happens next depends on the outcome, because the
- * two outcomes want opposite things:
- *
- *   - **success** — the caller wants the verdict, not the evidence.
- *     {@link GateLogSink#digest} is one line: the pass count and the log path.
- *   - **failure** — the evidence IS the point, and making the caller open a
- *     file to see why a gate went red just moves the cost.
- *     {@link GateLogSink#replay} puts the captured tail back inline.
- *
- * `AGENT_LOG_LEVEL=verbose` opts back into live inline streaming (the
- * "existing log-level control"): the capture still happens, so the artifact is
- * written either way.
- *
- * The sink never throws. A log directory that cannot be written degrades to
- * inline streaming — losing the size bound is strictly better than losing the
- * gate output that says why a close failed.
- *
- * ## Why the artifact is written asynchronously (Story #4766)
- *
- * This sink is the `log` callable that `close-validation/process.js` invokes
- * from inside the gate child's stdout/stderr `'data'` handler — once per line.
- * The first cut wrote each line with `fs.writeSync`, which blocks the event
- * loop while the child keeps writing: the OS pipe buffer fills, the child's
- * write fails with `EAGAIN`, and a child that does not tolerate that dies. On
- * a clean `main` `biome ci .` already emits ~625 lines, and it aborts with
- * exit 101 (a `biome_console` panic, not a lint violation) when it happens —
- * so the first gate of any close could die on plumbing while its verdict was
- * green.
- *
- * So the write path buffers into an async stream instead: per-line work is
- * O(1) and never touches a syscall on the drain path. The cost is that the
- * artifact is not on disk the instant a line is logged, which is why the sink
- * exposes {@link GateLogSink#flush} — callers await it before reading,
- * replaying, or naming the artifact as final.
+ * Writes are async, never `fs.writeSync`: this runs in the gate child's
+ * `'data'` handler, and a blocking write fills the pipe until the child dies
+ * on `EAGAIN`. Await {@link GateLogSink#flush} before reading the artifact.
  */
 
 import nodeFs from 'node:fs';
@@ -62,46 +13,27 @@ import path from 'node:path';
 import { orchestrationLogDir } from '../../config/temp-paths.js';
 import { Logger, resolveLevel } from '../../Logger.js';
 
-/**
- * How many trailing captured lines {@link GateLogSink#replay} puts back
- * inline. A failed gate's actionable evidence — the assertion, the stack, the
- * summary counts — sits at the end of its output; the head is startup noise.
- * The full text is always in the artifact regardless.
- */
+/** Trailing lines replayed on failure; a failed gate's evidence sits at the end. */
 export const REPLAY_TAIL_LINES = 200;
 
 /**
- * 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.
+ * `closeGateLogPath` (temp-paths.js) spells the same name for the reader; it
+ * is not imported because that helper resolves tempRoot (a git spawn). The
+ * two spellings are pinned equal by test.
  */
 function logNameFor(storyId) {
   return `close-gates-${storyId ?? 'unknown'}.log`;
 }
 
-/**
- * A capturing sink for close-validation gate output.
- *
- * Not exported as a constructor — {@link createGateLogSink} owns the
- * degradation decision, so every instance in the wild has already resolved
- * whether it has a writable artifact.
- */
+/** Built only by {@link createGateLogSink}, which owns the degradation decision. */
 class GateLogSink {
   /**
    * @param {{ logPath: string|null, streamInline: boolean, write: (line: string) => void, flush?: () => Promise<void>, emit: (line: string) => void }} args
    */
   constructor({ logPath, streamInline, write, flush, emit }) {
-    /** Absolute path of the artifact, or `null` when capture is unavailable. */
+    /** `null` when capture is unavailable. */
     this.logPath = logPath;
-    /** Whether lines are ALSO echoed inline as they arrive. */
     this.streamInline = streamInline;
-    /** Number of lines captured so far. */
     this.lineCount = 0;
     this._write = write;
     this._flush = flush ?? (() => Promise.resolve());
@@ -110,7 +42,6 @@ class GateLogSink {
   }
 
   /**
-   * The `log` callable handed to `runCloseValidation` / `buildDefaultGates`.
    * Bound, because it is passed by reference into the gate machinery.
    *
    * @type {(message: string) => void}
@@ -127,11 +58,7 @@ class GateLogSink {
   }
 
   /**
-   * Settle the artifact: wait for every buffered line to reach disk and close
-   * the file. Idempotent, never throws, and a no-op on the degraded (no
-   * artifact) path. Await it before reading {@link GateLogSink#logPath} or
-   * handing the path to anyone — the write path is async precisely so it never
-   * stalls a gate child's pipe.
+   * Wait for every buffered line to reach disk. Idempotent, never throws.
    *
    * @returns {Promise<void>}
    */
@@ -140,9 +67,6 @@ class GateLogSink {
   }
 
   /**
-   * The success-path digest: one line, no gate output. Names the artifact so
-   * the caller can open it on demand rather than carrying it all session.
-   *
    * @returns {string}
    */
   digest() {
@@ -153,9 +77,7 @@ class GateLogSink {
   }
 
   /**
-   * Put the captured tail back inline — the failure path, where the evidence
-   * is what the caller came for. A no-op when the lines were already streamed
-   * inline (verbose, or degraded capture), so nothing is ever printed twice.
+   * Replay the captured tail inline; a no-op when already streamed inline.
    *
    * @returns {number} Lines replayed.
    */
@@ -173,13 +95,8 @@ class GateLogSink {
 }
 
 /**
- * Wrap an already-open artifact fd in a non-blocking line writer.
- *
- * `write` hands the line to a `fs.WriteStream` — O(1), no syscall on the
- * caller's stack — and `flush` ends the stream, resolving once every buffered
- * line has reached disk (or the stream has errored; a half-written artifact is
- * still better than a dead close). Both are best-effort by construction: the
- * stream's `'error'` is absorbed, so nothing here can abort a close.
+ * Non-blocking line writer over an open fd. Stream errors are absorbed, so
+ * nothing here can abort a close.
  *
  * @param {typeof nodeFs} fs
  * @param {string} logPath
@@ -217,8 +134,6 @@ function createArtifactWriter(fs, logPath, handle) {
 }
 
 /**
- * Build the gate-output sink for one close run.
- *
  * @param {{
  *   storyId: number|null,
  *   logDir?: string,
@@ -226,11 +141,7 @@ function createArtifactWriter(fs, logPath, handle) {
  *   logger?: { info: (m: string) => void },
  *   level?: string,
  *   config?: object,
- * }} [args] `logDir` defaults to the configured `<tempRoot>/orchestration`
- *   (Story #4794 — was a hardcoded `<cwd>/temp/orchestration`, which ignored
- *   `project.paths.tempRoot` and hid the artifact from the retention purge);
- *   `level` defaults to the live Logger level so `AGENT_LOG_LEVEL=verbose`
- *   restores streaming.
+ * }} [args] `logDir` defaults to `<tempRoot>/orchestration`.
  * @returns {GateLogSink}
  */
 export function createGateLogSink({
@@ -250,12 +161,10 @@ export function createGateLogSink({
   try {
     fs.mkdirSync(dir, { recursive: true });
     logPath = path.join(dir, logNameFor(storyId));
-    // Truncate: each close run owns its artifact outright, so a re-run never
-    // hands the reader a file interleaving two runs' gates.
+    // Truncate so a re-run never interleaves two runs' gates.
     writer = createArtifactWriter(fs, logPath, fs.openSync(logPath, 'w'));
   } catch {
-    // No artifact — fall back to inline streaming rather than dropping the
-    // gate output on the floor.
+    // No artifact: stream inline rather than drop the gate output.
     return new GateLogSink({
       logPath: null,
       streamInline: true,