mandrel 2.20.0 → 2.21.0

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

@@ -28,6 +28,10 @@
  * pre-#4543 pipeline collapsed by treating budget exhaustion as a block.
  */
 
+import nodeFs from 'node:fs';
+import path from 'node:path';
+import { storyTerminalEnvelopePath } from '../config/temp-paths.js';
+import { resolveConfig } from '../config-resolver.js';
 import { validateTerminalEnvelope } from './story-deliver-terminal-schema.js';
 
 // Re-exported so the schema split stays an implementation detail: every
@@ -327,7 +331,95 @@ export const TERMINAL_BEGIN_MARKER = '--- STORY DELIVER TERMINAL ---';
 export const TERMINAL_END_MARKER = '--- END TERMINAL ---';
 
 /**
- * Write a terminal envelope to stdout, between its markers.
+ * Resolve the repo config, or `undefined` when it cannot be read.
+ *
+ * An unreadable `.agentrc.json` must not cost the run its envelope copy: the
+ * path helpers fall back to the framework-default temp root, which is still a
+ * far better outcome than no artifact at all.
+ *
+ * @param {typeof resolveConfig} resolveConfigImpl
+ * @returns {object|undefined}
+ */
+function tolerantConfig(resolveConfigImpl) {
+  try {
+    return resolveConfigImpl();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Persist a terminal envelope beside its Story's gate log (Story #4816).
+ *
+ * Stdout is a channel with exactly one reader — the turn that launched the
+ * close — and that reader is not always still listening. A `story-worker`
+ * that reports progress and ends its turn while the close it started is
+ * mid-gate-chain is behaving reasonably, but the envelope it never relayed is
+ * gone: the router then has to reconstruct the Story's state from labels, and
+ * `deliver-recover.js` used to answer that reconstruction with
+ * "Implementation never finished" — false, and its re-init suggestion can put
+ * a second close on one PR. Observed four times across three workers in one
+ * consumer run. The file is the second channel, and it outlives the turn.
+ *
+ * **Best-effort by construction.** Every failure path returns `null`: a
+ * delivery must never turn a landed PR into a crash because a temp directory
+ * was unwritable. The stdout envelope above is the contract; this is a copy.
+ *
+ * **Atomic by construction.** The payload is written to a pid-scoped
+ * temporary name and renamed into place, because the reader that matters most
+ * is a router polling during a live close — a half-written file would hand it
+ * a parse error at exactly the moment it is trying to avoid guessing.
+ *
+ * A null `storyId` (the `escalated` terminal, which by construction never
+ * authored a Story) has nowhere to be filed and writes nothing.
+ *
+ * `config` is optional and resolved lazily when absent. Two of the emit sites
+ * are `catch` blocks that crashed before any config was resolved, and those
+ * are precisely the runs whose envelope is most worth keeping — so the temp
+ * root is looked up here rather than left at the framework default, which
+ * would file the artifact where a consumer's router never looks (and where
+ * the retention purge would never reap it).
+ *
+ * @param {object} envelope A validated terminal envelope.
+ * @param {{
+ *   config?: object,
+ *   fsImpl?: typeof nodeFs,
+ *   resolveConfigImpl?: typeof resolveConfig,
+ * }} [deps]
+ * @returns {string|null} The path written, or `null` when nothing was.
+ */
+export function persistTerminalEnvelope(
+  envelope,
+  { config, fsImpl = nodeFs, resolveConfigImpl = resolveConfig } = {},
+) {
+  const storyId = envelope?.storyId;
+  if (!Number.isInteger(storyId) || storyId <= 0) return null;
+  let tmpPath = null;
+  try {
+    const resolved = config ?? tolerantConfig(resolveConfigImpl);
+    const target = storyTerminalEnvelopePath(storyId, resolved);
+    fsImpl.mkdirSync(path.dirname(target), { recursive: true });
+    tmpPath = `${target}.${process.pid}.tmp`;
+    fsImpl.writeFileSync(tmpPath, `${JSON.stringify(envelope)}\n`, 'utf8');
+    fsImpl.renameSync(tmpPath, target);
+    return target;
+  } catch {
+    // A rename that never ran leaves the scratch file behind; drop it rather
+    // than accumulating one per failed close.
+    if (tmpPath) {
+      try {
+        fsImpl.rmSync(tmpPath, { force: true });
+      } catch {
+        // Nothing left to try — this whole path is already best-effort.
+      }
+    }
+    return null;
+  }
+}
+
+/**
+ * Write a terminal envelope to stdout, between its markers, and persist a
+ * copy to disk.
  *
  * **Deliberately not `Logger.info`.** The envelope is this CLI's
  * machine-readable contract — every invocation emits exactly ONE, and a
@@ -340,16 +432,37 @@ export const TERMINAL_END_MARKER = '--- END TERMINAL ---';
  *
  * Single home for the marker format so the four emit sites (the runner's
  * terminal, the close CLI's failed-terminal catch, and both confirm-CLI
- * paths) cannot drift apart.
+ * paths) cannot drift apart — and, since Story #4816, the single home for the
+ * on-disk copy too, so no emit path can persist and another forget.
+ * {@link persistTerminalEnvelope} runs **first**: a caller that has read the
+ * markers off stdout can then rely on the file already being there.
  *
  * @param {object} envelope
- * @param {{ write?: (s: string) => void }} [opts] `write` is a test seam.
+ * @param {{
+ *   write?: (s: string) => void,
+ *   config?: object,
+ *   persist?: typeof persistTerminalEnvelope,
+ * }} [opts] `write` and `persist` are test seams; `config` resolves the
+ *   artifact's temp root and is threaded from whichever emit site holds one.
  * @returns {void}
  */
 export function emitTerminalEnvelope(
   envelope,
-  { write = (s) => process.stdout.write(s) } = {},
+  {
+    write = (s) => process.stdout.write(s),
+    config,
+    persist = persistTerminalEnvelope,
+  } = {},
 ) {
+  // Belt and braces around a copy: `persistTerminalEnvelope` already swallows
+  // its own failures, but the stdout envelope is the CONTRACT and the disk
+  // copy is a convenience. Nothing in the secondary path — including a future
+  // injected `persist` — may cost the caller the primary one.
+  try {
+    persist(envelope, { config });
+  } catch {
+    // Intentionally silent: see above.
+  }
   // Story #4685 — compact (not 2-space pretty) JSON. The envelope is a
   // machine contract callers recover with `JSON.parse`, so pretty-printing
   // only adds turn-resident bytes without helping any consumer.

package/.agents/scripts/lib/temp-retention.js

@@ -210,28 +210,43 @@ async function makeEntry(fsp, target, className, storyId, keep = false) {
 }
 
 /**
- * Recover the Story id a run-log basename carries. Both writers that land in
- * `orchestration/` end their name with the scope: `close-gates-4794.log` from
- * the gate sink, `sync-result-story-4794.log` from the terse-result dump.
+ * Extensions this class owns inside `orchestration/`. Story #4816 added
+ * `.json`: the persisted terminal envelope lands beside the gate log, and a
+ * `.log`-only scan would have left one immortal file per delivered Story in a
+ * directory the purge otherwise keeps clean.
+ */
+const ORCHESTRATION_EXTENSIONS = Object.freeze(['.log', '.json']);
+
+/**
+ * Recover the Story id a run-artifact basename carries. Every writer that
+ * lands in `orchestration/` ends its name with the scope: `close-gates-4794.log`
+ * from the gate sink, `sync-result-story-4794.log` from the terse-result dump,
+ * `story-deliver-terminal-4794.json` from the terminal-envelope persist.
  *
  * @param {string} name
  * @returns {number|null}
  */
 function storyIdFromLogName(name) {
-  const match = TRAILING_ID_PATTERN.exec(name.replace(/\.log$/, ''));
+  const match = TRAILING_ID_PATTERN.exec(name.replace(/\.(log|json)$/, ''));
   return match ? Number(match[1]) : null;
 }
 
 /**
- * `<tempRoot>/orchestration/*.log` — close gate transcripts and terse-result
- * detail dumps. A log whose name carries no id (there are none today, but the
- * class owns the directory) is age-floored rather than dropped from the class.
+ * `<tempRoot>/orchestration/*.{log,json}` — close gate transcripts,
+ * terse-result detail dumps, and persisted terminal envelopes. An artifact
+ * whose name carries no id (there are none today, but the class owns the
+ * directory) is age-floored rather than dropped from the class.
  */
 async function scanOrchestrationLogs(tempRoot, fsp) {
   const dir = path.join(tempRoot, ORCHESTRATION_DIRNAME);
   const entries = [];
   for (const dirent of await safeReaddir(fsp, dir)) {
-    if (!dirent.isFile() || !dirent.name.endsWith('.log')) continue;
+    if (
+      !dirent.isFile() ||
+      !ORCHESTRATION_EXTENSIONS.some((ext) => dirent.name.endsWith(ext))
+    ) {
+      continue;
+    }
     const entry = await makeEntry(
       fsp,
       path.join(dir, dirent.name),

package/.agents/scripts/single-story-confirm-merge.js

@@ -204,7 +204,7 @@ async function logConfirmResult(result, terminal, config) {
       status: terminal?.status,
     },
   });
-  emitTerminalEnvelope(terminal);
+  emitTerminalEnvelope(terminal, { config });
   await emitTerminalFriction({ envelope: terminal, config });
   return { success: terminal.status !== 'failed', result, terminal };
 }

package/.agents/workflows/helpers/deliver-light.md

@@ -49,7 +49,9 @@ multi-capability enumeration). Size is enforced where ground truth is available:
 the diff backstop in step 4. Do not talk yourself past that one.
 
 Sensitivity is the exception and stays absolute: a footprint touching an auth,
-crypto, billing, or migration class routes `full` however small or mechanical.
+crypto, billing, or migration class routes `full` however small or mechanical —
+and unlike a ceiling, it is **not overridable** (§ Recording a proceed-light
+answer).
 
 ## Four invariants (do not skip one)
 
@@ -58,9 +60,11 @@ crypto, billing, or migration class routes `full` however small or mechanical.
    **and** a ledgered model verdict with a recorded reason. Both must agree on
    `lite`.
 2. **Over-scope stops — it never hard-fails.** An over-ceiling prompt STOPS and
-   asks the operator to escalate to `/plan` or proceed light. Under `--yes` it
-   fails closed to an **`escalated` terminal envelope** that ends the session
-   (§ Escalation is terminal).
+   asks the operator to escalate to `/plan` or proceed light. **Both answers
+   are executable** — `--operator-proceed-light` records the second one
+   (§ Recording a proceed-light answer). Under `--yes` it fails closed to an
+   **`escalated` terminal envelope** that ends the session (§ Escalation is
+   terminal).
 3. **Diff-derived backstop.** After implementation the ACTUAL change set is
    re-checked — the diff is the real scope signal — and an over-ceiling diff is
    blocked rather than landed.
@@ -89,7 +93,10 @@ crypto, billing, or migration class routes `full` however small or mechanical.
      `nextCommands`. Continue to step 2.
    - **`ask-operator`** — predicted scope exceeds the light ceilings. STOP and
      ask the operator to escalate to `/plan` or proceed light. Do not proceed
-     on your own. This is a **question, not a terminal** — wait for the answer.
+     on your own. This is a **question, not a terminal** — wait for the answer,
+     then act on it: *escalate* leaves for `/plan`, *proceed light* re-runs the
+     same command with `--operator-proceed-light "<their reason>"`
+     (§ Recording a proceed-light answer).
    - **over-scope under `--yes`** — no `action` to branch on: the gate emits an
      **`escalated` terminal envelope** instead (exit 2). § Escalation is
      terminal governs; you are finished.
@@ -144,6 +151,39 @@ crypto, billing, or migration class routes `full` however small or mechanical.
    [`deliver-digest.md`](deliver-digest.md) § 5 — every close
    gate runs byte-identical to the full path.
 
+## Recording a proceed-light answer {#recording-a-proceed-light-answer}
+
+The gate offers the operator two options, so **both** have to be executable.
+Re-run the identical gate command with their answer appended:
+
+```bash
+node .agents/scripts/deliver-light.js --prompt "<prompt>" … \
+  --operator-proceed-light "<the operator's reason, in their words>"
+```
+
+The gate then proceeds light, records the decision in the receipt Story, and
+returns it on the envelope's `override`. Do **not** instead re-shape the
+prediction — shrinking `--refactors` until the gate stops objecting is
+under-declaring the footprint, which is the one thing the coarse design must
+not reward.
+
+It is deliberately narrow, and a refusal is printed rather than silent:
+
+- **Only a size prediction is waivable** — change kinds, magnitude,
+  uncertainty, deployable span. A sensitive-path class, a
+  migration-with-consumers span, and an unknown footprint (undeclared, glob,
+  no acceptance, unclassifiable) are refused: those are risk, not size, and
+  § Scope by effort keeps them absolute.
+- **The ledgered verdict still stands on its own.** The override substitutes
+  for the predicted *shape* only; `--route lite --reason "<why>"` is still
+  required.
+- **Attended-only.** With `--yes` it is a usage error, not a quiet no-op —
+  an unattended run has no operator whose answer this could be, and over-scope
+  there still fails closed (§ Escalation is terminal).
+
+What licenses this at all is step 4: the operator waives a *guess*, never the
+diff backstop, which re-checks the actual change set against ground truth.
+
 ## Escalation is terminal {#escalation-is-terminal}
 
 Over-scope under `--yes` emits a schema-validated `story-deliver-terminal`

package/.agents/workflows/helpers/deliver-story-reference.md

@@ -745,6 +745,39 @@ unconfirmed merge is a **contract violation** — the parent cannot distinguish
 "still working" from "done but silent". `pending` is the honest,
 machine-readable alternative: "not finished, here is exactly how to continue."
 
+### The envelope also lands on disk
+
+Stdout has exactly one reader — the turn that launched the close — and that
+reader is not always still listening. A child that reports progress and ends
+its turn while its close is mid-gate-chain is behaving reasonably, but the
+envelope it never relayed is gone, and reconstructing the Story's state from
+labels costs a recovery round trip plus a full resume of the child. Observed
+four times across three workers in a single consumer run, on unrelated
+footprints, and not new to that run.
+
+So `emitTerminalEnvelope` — the one writer behind every emit site — also
+persists the validated envelope to
+`<tempRoot>/orchestration/story-deliver-terminal-<storyId>.json`:
+
+- **It is the same object**, not a summary. Read it and branch exactly as you
+  would on stdout; the copy is written before the markers are, so a caller
+  that saw them can rely on the file.
+- **It is best-effort.** A failed write returns null and changes nothing about
+  the emitted envelope or the exit code — a landed PR must never become a
+  crash because a temp directory was unwritable.
+- **It is a fallback, not a licence.** A worker still holds its turn until the
+  envelope arrives; see [`agents/story-worker.md`](../../agents/story-worker.md).
+
+`deliver-recover.js` reads the same artifact, plus the freshness of
+`close-gates-<storyId>.log`, to split the one genuinely ambiguous row of its
+table. `agent::executing` with no PR used to answer "Implementation never
+finished" — false for the whole duration of a close, whose gates and push
+happen before any PR exists, and actively hazardous, because acting on its
+re-init suggestion can put a second close on one PR. It now answers
+`close-in-flight` (a gate log touched inside the window: wait, then re-probe)
+or `close-envelope-on-disk` (the close already reached a verdict: relay it),
+and falls back to the original verdict only when neither artifact exists.
+
 ### Exit-code compatibility note (`--no-wait-merge`)
 
 Every close flag keeps its meaning, but the **exit code** of a

package/.agents/workflows/helpers/deliver-story.md

@@ -148,10 +148,13 @@ budget is exhausted. Reference § Step 7.
 
 ## Recovering a stranded Story {#recover}
 
-Unclear state (killed run, lost envelope, a re-run refusal — incl.
-merged-but-label-stale)? Do not guess — probe **read-only** with
+**Lost envelope first: read it off disk.** Close persists each to
+`temp/orchestration/story-deliver-terminal-<storyId>.json`; branch on it per
+digest § 5. Otherwise (killed run, re-run refusal, merged-but-label-stale)
+do not guess — probe **read-only** with
 `node .agents/scripts/deliver-recover.js --story <storyId>`; it prints the
-**one** next command with its evidence, never a menu.
+**one** next command with its evidence, never a menu. A live close answers
+`close-in-flight`: wait, never re-init underneath it.
 
 ## Idempotence & constraints
 

package/docs/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.21.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.20.0...mandrel-v2.21.0) (2026-07-28)
+
+
+### Added
+
+* deliver-light: make the gate's `proceed-light` answer representable, attended-only, and auditable ([#4815](https://github.com/dsj1984/mandrel/issues/4815)) ([#4817](https://github.com/dsj1984/mandrel/issues/4817)) ([74aa28e](https://github.com/dsj1984/mandrel/commit/74aa28e57d0192bcad698461d600806a77de092f))
+* persist the close terminal envelope and teach recovery a live-close state (refs [#4816](https://github.com/dsj1984/mandrel/issues/4816)) ([#4819](https://github.com/dsj1984/mandrel/issues/4819)) ([ffa61d8](https://github.com/dsj1984/mandrel/commit/ffa61d8f56f39c33705bfa379cefdcaaeb523115))
+
 ## [2.20.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.19.0...mandrel-v2.20.0) (2026-07-27)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",