mandrel 2.16.0 → 2.18.0

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

@@ -0,0 +1,166 @@
+/**
+ * story-deliver-terminal-schema.js — load `story-deliver-terminal.schema.json`
+ * and validate envelopes against it.
+ *
+ * Split out of `story-deliver-terminal.js` so the envelope WRITER holds only
+ * the contract's shape and vocabulary, and this module holds the one thing
+ * the writer must never depend on at call time: the filesystem.
+ *
+ * That separation is the fix, not just tidiness. `single-story-close.js`
+ * invoked by a *worktree-relative* path runs the Story worktree's own copy of
+ * the script and then **reaps that worktree** as one of its phases. The schema
+ * used to be read lazily, on the first envelope build — which happens after
+ * the reap — so the read hit a path that no longer existed. The throw landed
+ * inside the close CLI's error path, so a Story whose PR had merged, whose
+ * label was `agent::done`, and whose post-land tail was green exited non-zero
+ * emitting NO envelope at all: the delivery engine's documented return
+ * contract lost to a success, recoverable only by a second close run from the
+ * main checkout.
+ *
+ * Two guarantees close that, and both live here:
+ *
+ *   1. The schema is read and parsed ONCE, at module load. The parsed schema
+ *      outlives the file, so what happens to the directory afterwards is
+ *      irrelevant. Compilation stays lazy — it needs no filesystem — so an
+ *      import costs one small read and nothing else.
+ *   2. An unreadable schema DEGRADES validation rather than throwing. A
+ *      schema violation still fails loudly; see {@link validateTerminalEnvelope}.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Absolute path to the shipped schema — the SSOT this module reads.
+ *
+ * Module-private, like every other `SCHEMA_PATH` in the tree
+ * (`validation-evidence.js`, `signal-validator.js`): the path is an
+ * implementation detail of loading, and callers want the verdict, not the
+ * location.
+ */
+const SCHEMA_PATH = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'story-deliver-terminal.schema.json',
+);
+
+/**
+ * Read and parse the shipped schema. Never throws: a read failure is recorded
+ * on the returned source and degrades validation downstream, because importing
+ * this module must never be what breaks a delivery.
+ *
+ * @returns {{ schema: object|null, error: string|null }}
+ */
+function loadSchemaSource() {
+  try {
+    return {
+      schema: JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8')),
+      error: null,
+    };
+  } catch (err) {
+    return { schema: null, error: err?.message ?? String(err) };
+  }
+}
+
+/**
+ * The schema, read and parsed at module load. Deliberately eager — see the
+ * module header for the failure that made it so.
+ *
+ * @type {{ schema: object|null, error: string|null }}
+ */
+const SCHEMA_SOURCE = loadSchemaSource();
+
+/**
+ * Compiled validators keyed by the source object they came from.
+ *
+ * A `WeakMap` rather than one module-level slot so an injected `schemaSource`
+ * (the test seam) can never poison the validator the production path memoizes.
+ *
+ * @type {WeakMap<object, Function>}
+ */
+const VALIDATORS = new WeakMap();
+
+/**
+ * Compile (once per source) and return the terminal-envelope validator, or
+ * `null` when the source carries no usable schema.
+ *
+ * @param {{ schema: object|null }} source
+ * @returns {Function|null}
+ */
+function getValidator(source) {
+  if (!source?.schema) return null;
+  const cached = VALIDATORS.get(source);
+  if (cached) return cached;
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(source.schema);
+  VALIDATORS.set(source, validate);
+  return validate;
+}
+
+let _unvalidatedWarned = false;
+
+/**
+ * Announce — once per process — that an envelope is going out unvalidated.
+ *
+ * Written straight to stderr rather than through `Logger.warn` for the same
+ * reason `emitTerminalEnvelope` bypasses `Logger.info`: the envelope itself is
+ * unsuppressible, so the notice that one was not checked has to be too. Under
+ * `AGENT_LOG_LEVEL=silent` a level-gated warning would vanish and the degrade
+ * would be invisible.
+ *
+ * @param {string|null|undefined} error
+ * @returns {void}
+ */
+function warnUnvalidated(error) {
+  if (_unvalidatedWarned) return;
+  _unvalidatedWarned = true;
+  process.stderr.write(
+    `[story-deliver-terminal] ⚠️ terminal-envelope schema unavailable (${error ?? 'unknown'}) — ` +
+      `emitting the envelope UNVALIDATED. The return contract is preserved; its shape is not checked. ` +
+      `Expected at: ${SCHEMA_PATH}\n`,
+  );
+}
+
+/**
+ * Validate a candidate envelope against the shipped schema.
+ *
+ * When the schema is unavailable the result reports `validated: false` and
+ * `valid: true` — a **deliberate degrade**, not an oversight. Losing the shape
+ * check costs a guard against a malformed envelope; throwing here costs the
+ * envelope entirely, and the envelope is the documented return contract of the
+ * delivery engine. An unvalidated terminal a caller can act on beats no
+ * terminal at all, so the unreadable-schema case degrades and says so on
+ * stderr while a schema *violation* still fails loudly at the writer.
+ *
+ * @param {object} envelope
+ * @param {{ schemaSource?: { schema: object|null, error: string|null } }} [opts]
+ *   `schemaSource` is a test seam — production always uses the eagerly loaded
+ *   module-level source.
+ * @returns {{ valid: boolean, errors: string[], validated: boolean }}
+ */
+export function validateTerminalEnvelope(
+  envelope,
+  { schemaSource = SCHEMA_SOURCE } = {},
+) {
+  const validate = getValidator(schemaSource);
+  if (!validate) {
+    warnUnvalidated(schemaSource?.error);
+    return { valid: true, errors: [], validated: false };
+  }
+  const valid = validate(envelope);
+  if (valid) return { valid: true, errors: [], validated: true };
+  const errors = (validate.errors ?? []).map(
+    (e) => `${e.instancePath || '/'} ${e.message}`,
+  );
+  return { valid: false, errors, validated: true };
+}

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

@@ -28,22 +28,12 @@
  * pre-#4543 pipeline collapsed by treating budget exhaustion as a block.
  */
 
-import { readFileSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { validateTerminalEnvelope } from './story-deliver-terminal-schema.js';
 
-import Ajv2020 from 'ajv/dist/2020.js';
-import addFormats from 'ajv-formats';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const SCHEMA_PATH = path.resolve(
-  __dirname,
-  '..',
-  '..',
-  '..',
-  'schemas',
-  'story-deliver-terminal.schema.json',
-);
+// Re-exported so the schema split stays an implementation detail: every
+// consumer still reaches the validator through the envelope module that owns
+// the contract.
+export { validateTerminalEnvelope };
 
 export const TERMINAL_ENVELOPE_KIND = 'story-deliver-terminal';
 
@@ -152,39 +142,6 @@ export const NEXT_COMMANDS = Object.freeze({
   escalateToPlan: (prompt) => `/plan "${quoteForPlan(prompt)}"`,
 });
 
-/** @type {Function|null} */
-let _validator = null;
-
-/**
- * Compile (once) and return the terminal-envelope validator.
- *
- * @returns {Function}
- */
-function getValidator() {
-  if (_validator) return _validator;
-  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
-  const ajv = new Ajv2020({ allErrors: true, strict: false });
-  addFormats(ajv);
-  _validator = ajv.compile(schema);
-  return _validator;
-}
-
-/**
- * Validate a candidate envelope against the shipped schema.
- *
- * @param {object} envelope
- * @returns {{ valid: boolean, errors: string[] }}
- */
-export function validateTerminalEnvelope(envelope) {
-  const validate = getValidator();
-  const valid = validate(envelope);
-  if (valid) return { valid: true, errors: [] };
-  const errors = (validate.errors ?? []).map(
-    (e) => `${e.instancePath || '/'} ${e.message}`,
-  );
-  return { valid: false, errors };
-}
-
 /**
  * Drop `undefined`-valued keys so the schema's `additionalProperties: false`
  * and its nullable unions both stay satisfiable from one optional-argument
@@ -207,9 +164,14 @@ function compact(obj) {
  * Throws a `TypeError` naming the schema violations when the assembled
  * object does not validate. That is deliberate: the whole point of the
  * envelope is that a caller can trust its status without re-probing
- * GitHub, so emitting an unvalidated one would reintroduce the ambiguity
+ * GitHub, so emitting a *malformed* one would reintroduce the ambiguity
  * this replaces.
  *
+ * A schema that cannot be READ is the opposite case and does not throw —
+ * see {@link validateTerminalEnvelope}. "This envelope is wrong" is worth
+ * failing on; "I could not check this envelope" is not worth destroying
+ * the return contract over.
+ *
  * @param {object} args
  * @param {number|null} args.storyId `null` only for an `escalated` terminal,
  *   which by construction never authored a Story.
@@ -227,6 +189,9 @@ function compact(obj) {
  * @param {number} args.elapsedSeconds
  * @param {object|null} [args.waitBudget]
  * @param {string} [args.timestamp]
+ * @param {{ schema: object|null, error: string|null }} [args.schemaSource]
+ *   Test seam; never passed in production. Not part of the envelope — the
+ *   envelope is assembled from named fields only.
  * @returns {object} The validated envelope.
  */
 export function buildTerminalEnvelope({
@@ -245,6 +210,7 @@ export function buildTerminalEnvelope({
   elapsedSeconds = 0,
   waitBudget,
   timestamp = new Date().toISOString(),
+  schemaSource,
 }) {
   const envelope = compact({
     kind: TERMINAL_ENVELOPE_KIND,
@@ -268,7 +234,12 @@ export function buildTerminalEnvelope({
     timestamp,
   });
 
-  const { valid, errors } = validateTerminalEnvelope(envelope);
+  // Passing `{ schemaSource }` unconditionally is safe: an `undefined`
+  // property value is exactly what triggers the destructuring default on the
+  // other side, so production still gets the eagerly-loaded module source.
+  const { valid, errors } = validateTerminalEnvelope(envelope, {
+    schemaSource,
+  });
   if (!valid) {
     throw new TypeError(
       `buildTerminalEnvelope: assembled envelope violates story-deliver-terminal.schema.json:\n` +

package/.agents/scripts/lib/orchestration/ticket-validator-conflicts.js

@@ -449,15 +449,29 @@ function computeMissingBddScaffoldFindings(stories, reach, severity) {
  * Tasks satisfy (a) or (b). When ≥2 such Stories sit in the same wave (no
  * transitive `depends_on` between them), emit a single finding keyed by the
  * registry path.
+ *
+ * Reached from the module's `_internal` named export. The pass is pure — it
+ * performs no filesystem I/O and spawns no process — so its optional final
+ * `deps` parameter seams the three collaborating predicates rather than a
+ * built-in; each entry defaults to the real implementation
+ * (`.agents/rules/test-seams.md` rules 1-3: the defaults live on the function,
+ * never on a module-level mutable variable).
+ *
+ * @param {object} input
+ * @param {{
+ *   isRegistryPathImpl?: typeof isRegistryPath,
+ *   inSameWaveImpl?: typeof inSameWave,
+ *   registryRegistryImpl?: typeof registryRegistry,
+ * }} [deps]
  */
-function computeRegistryFindings({
-  stories,
-  reach,
-  patterns,
-  producers,
-  assumptionEntries,
-  severity,
-}) {
+function computeRegistryFindings(
+  { stories, reach, patterns, producers, assumptionEntries, severity },
+  {
+    isRegistryPathImpl = isRegistryPath,
+    inSameWaveImpl = inSameWave,
+    registryRegistryImpl = registryRegistry,
+  } = {},
+) {
   const findings = [];
   // Build the matching registry path set from producer & creator paths.
   const registryHits = new Map(); // registryPath -> Map<storySlug, producers[]>
@@ -474,7 +488,7 @@ function computeRegistryFindings({
   // (a) direct registry edits — object-form `{ path, assumption }` entries
   // from `indexAssumptionEntries` (and the producer index built from them).
   for (const [path, entries] of producers.entries()) {
-    if (!isRegistryPath(path, patterns)) continue;
+    if (!isRegistryPathImpl(path, patterns)) continue;
     for (const e of entries) {
       bump(path, {
         storySlug: e.storySlug,
@@ -485,7 +499,7 @@ function computeRegistryFindings({
     }
   }
   for (const e of assumptionEntries) {
-    if (!isRegistryPath(e.path, patterns)) continue;
+    if (!isRegistryPathImpl(e.path, patterns)) continue;
     bump(e.path, {
       storySlug: e.storySlug,
       taskSlug: e.taskSlug,
@@ -510,7 +524,7 @@ function computeRegistryFindings({
         continue;
       const childParent = parentDirOf(change.path);
       if (!childParent) continue;
-      for (const reg of registryRegistry(
+      for (const reg of registryRegistryImpl(
         producers,
         assumptionEntries,
         patterns,
@@ -532,7 +546,7 @@ function computeRegistryFindings({
     const cluster = new Set();
     for (let i = 0; i < stories.length; i += 1) {
       for (let j = i + 1; j < stories.length; j += 1) {
-        if (inSameWave(reach, stories[i], stories[j])) {
+        if (inSameWaveImpl(reach, stories[i], stories[j])) {
           cluster.add(stories[i]);
           cluster.add(stories[j]);
         }

package/.agents/scripts/lib/single-story-sweep.js

@@ -90,6 +90,7 @@ const STORY_BRANCH_INCLUDE = 'story-*';
  *   candidates: number,
  *   localDeleted: number,
  *   remoteDeleted: number,
+ *   reaped: string[],
  *   protected: Array<{ branch: string, reason: string, worktreePath?: string|null }>,
  *   contentMerged: Array<{ branch: string, worktreePath: string|null }>,
  *   failures: Array<{ branch: string|null, scope: string, stderr?: string }>,
@@ -147,6 +148,7 @@ export async function sweepMergedBranches({
         candidates: 0,
         localDeleted: 0,
         remoteDeleted: 0,
+        reaped: [],
         protected: [],
         contentMerged: [],
         failures: [],
@@ -296,6 +298,7 @@ async function runSweepUnderLock({
       candidates: 0,
       localDeleted: 0,
       remoteDeleted: 0,
+      reaped: [],
       protected: [],
       contentMerged,
       failures: [],
@@ -320,6 +323,7 @@ async function runSweepUnderLock({
       candidates: reapCandidates.length,
       localDeleted: 0,
       remoteDeleted: 0,
+      reaped: [],
       protected: protectedList,
       contentMerged,
       failures: [],
@@ -365,6 +369,7 @@ function executeReap({
       candidates: candidateCount,
       localDeleted: 0,
       remoteDeleted: 0,
+      reaped: [],
       protected: protectedList,
       contentMerged,
       failures: [{ branch: null, scope: 'execute', stderr: msg }],
@@ -398,6 +403,11 @@ function executeReap({
     candidates: candidateCount,
     localDeleted,
     remoteDeleted,
+    // Story #4794 — the branch names, not just the count. Each one is a merge
+    // this sweep CONFIRMED (merged PR + matching headRefOid), which is exactly
+    // the evidence the temp-retention catch-up needs to purge that Story's
+    // spent artifacts. Previously these existed only inside a log string.
+    reaped: reapable.map((c) => c.branch),
     protected: protectedList,
     contentMerged,
     failures: result.failures,
@@ -503,6 +513,7 @@ function zeroResult({ error }) {
     candidates: 0,
     localDeleted: 0,
     remoteDeleted: 0,
+    reaped: [],
     protected: [],
     contentMerged: [],
     failures: [],

package/.agents/scripts/lib/stdio-flush.js

@@ -0,0 +1,71 @@
+// .agents/scripts/lib/stdio-flush.js
+/**
+ * Stdio drain helper (Story #4783).
+ *
+ * `process.stdout` / `process.stderr` are only synchronous when they point at
+ * a TTY or a regular file. On a **pipe** — every `cmd | consumer`, every
+ * `child_process` capture, every `$(...)` substitution — Node writes
+ * asynchronously once the 64 KiB kernel pipe buffer fills: `write()` returns
+ * `false` and the remaining bytes sit in the stream's internal queue until the
+ * reader drains it.
+ *
+ * `process.exit()` does not wait for that queue. Anything still buffered when
+ * the process terminates is discarded, so a CLI that emits more than a pipe
+ * buffer's worth of output and then exits eagerly silently truncates — the
+ * exit code still reads green, and the consumer parses a half-written
+ * envelope. `runAsCli` is the shared boundary where that used to happen for
+ * every `.agents/scripts` entry point.
+ *
+ * The fix is to stop exiting eagerly (set `process.exitCode` and let the loop
+ * drain naturally). This helper is the belt-and-braces half: an explicit await
+ * on the queued bytes, so the flush is complete before the CLI's last frame
+ * unwinds even when something further out terminates the process.
+ *
+ * @module stdio-flush
+ */
+
+/**
+ * Await the point at which one writable stream's queued bytes have been handed
+ * to the OS. Resolves immediately when the stream has nothing queued, is not
+ * writable, or is not a stream at all — a flush must never be the reason a
+ * process hangs.
+ *
+ * Both settle paths are covered: the zero-length `write()` callback (which
+ * fires after every previously queued chunk, since writes are ordered) and the
+ * `'drain'` event (which fires when a backed-up stream empties). Whichever
+ * lands first resolves; the other is detached.
+ *
+ * @param {NodeJS.WritableStream & { writableLength?: number, writableEnded?: boolean, destroyed?: boolean }} [stream]
+ * @returns {Promise<void>}
+ */
+function drainStream(stream) {
+  if (!stream || typeof stream.write !== 'function') return Promise.resolve();
+  if (stream.destroyed || stream.writableEnded) return Promise.resolve();
+  if ((stream.writableLength ?? 0) === 0) return Promise.resolve();
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      stream.removeListener?.('drain', done);
+      resolve();
+    };
+    stream.once?.('drain', done);
+    // The write callback fires once this (empty) chunk — and therefore every
+    // chunk queued ahead of it — has been flushed to the underlying handle.
+    stream.write('', done);
+  });
+}
+
+/**
+ * Await the drain of the process's stdio streams. Never rejects: a stream that
+ * errored, closed, or was never writable resolves as already-flushed.
+ *
+ * @param {Array<NodeJS.WritableStream|undefined>} [streams] Defaults to
+ *   `[process.stdout, process.stderr]`.
+ * @returns {Promise<void>}
+ */
+export async function flushStdio(streams = [process.stdout, process.stderr]) {
+  await Promise.all(streams.map((stream) => drainStream(stream)));
+}