mandrel 2.59.0 → 2.61.0

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

@@ -1,46 +1,16 @@
 #!/usr/bin/env node
 /**
- * CLI: ensure `coverage/coverage-final.json` is present and fresh before the
- * CRAP gate fires. Wired into close-validation (always) and pre-push (with
- * `--skip-when-no-crap-files` so untouched-source pushes stay fast).
+ * Ensures `coverage/coverage-final.json` is fresh before the CRAP gate: skip
+ * when the gate is off, no changed file is under `crap.targetDirs`, or the
+ * content-digest stamp matches; otherwise run `test:coverage` behind the
+ * host-level full-suite lock and stamp on success.
  *
- * Behaviour:
- *   1. Resolve `delivery.quality.crap`. If `enabled === false`, exit 0.
- *   2. With `--skip-when-no-crap-files`: read `git diff --name-only <ref>...HEAD`
- *      (default ref `main`) and exit 0 if no changed file lives under
- *      `crap.targetDirs`.
- *   3. Test freshness: content digest of `crap.targetDirs` vs. the persisted
- *      capture stamp (`coverage/.capture-stamp.json`), falling back to the
- *      artifact-mtime heuristic when no stamp exists. Exit 0 when fresh.
- *   4. Otherwise announce the uncredited full-suite run — naming the
- *      invocation that would have deposited credit — and then spawn
- *      `npm run test:coverage`, serialized behind the host-level full-suite
- *      lock (Story #5173) so two concurrent runs on one checkout do not race;
- *      write a fresh capture stamp on success and propagate the exit code.
- *      With `--require-credited`, step 4 refuses instead of spawning, so the
- *      cost is never paid unannounced.
+ * `--require-credited` must stay an argument, never a config read: as policy
+ * it also refused the depositing run, leaving no path that could deposit.
  *
- * **`--require-credited` is an argument, not a config read (Story #5278).**
- * `delivery.execution.requireCreditedCapture` is a policy about *close*: the
- * close gate must not silently pay for a suite the worker was supposed to
- * have deposited. Reading it here applied the refusal to every invocation
- * including the worker's depositing one, so turning the policy on left no
- * path that could ever deposit and bricked the CRAP gate outright. The policy
- * now lives where it is enforced — `close-validation/gates.js` passes this
- * flag when the consumer sets it — and a bare invocation always runs.
- *
- * Step 3 is preceded by the changed-file skip when
- * `delivery.quality.gates.crap.incrementalCoverage.skipWhenUnchanged` is on
- * (the default): no changed file under `crap.targetDirs` versus `baseRef`
- * means no capture at all.
- *
- * Exit codes:
- *   0 — coverage is fresh (or capture skipped/succeeded).
- *   1 — capture run failed (broken tests or coverage-threshold breach), or
- *       the run was refused because it carried no credit and
- *       `--require-credited` was passed. The caller MUST
- *       surface this — silently passing here would defeat the CRAP gate's
- *       `requireCoverage: true` policy.
+ * Exit codes: 0 fresh/skipped/captured; 1 capture failed or refused (callers
+ * MUST surface it); 75 lock wait expired and deferred (only under
+ * `MANDREL_FULL_SUITE_LOCK_ON_EXPIRY=defer`); 124 suite timed out.
  */
 import { getChangedFiles } from './lib/changed-files.js';
 import { isDirectInvocation } from './lib/cli-utils.js';
@@ -62,17 +32,15 @@ import { Logger } from './lib/Logger.js';
 import { hasNpmScript, readPackageScripts } from './lib/npm-scripts.js';
 
 /**
- * Parse the full `process.argv` (index 2 onward) into the capture options.
- *
+ * A `null` ref defers the fallback to `resolveChangedFilesRef`.
  * @param {string[]} argv
- * @returns {{ skipWhenNoCrapFiles: boolean, requireCredited: boolean, ref: string, cwd: string }}
+ * @returns {{ skipWhenNoCrapFiles: boolean, requireCredited: boolean, ref: string | null, cwd: string }}
  */
 export function parseArgs(argv) {
   const out = {
     skipWhenNoCrapFiles: false,
-    // Story #5278 — an ARGUMENT, never a config read. See `runCoverageCapture`.
     requireCredited: false,
-    ref: 'main',
+    ref: null,
     cwd: process.cwd(),
   };
   for (let i = 2; i < argv.length; i += 1) {
@@ -86,16 +54,7 @@ export function parseArgs(argv) {
 }
 
 /**
- * The capture decision core, extracted from the CLI shell so the whole
- * decision table (disabled gate, missing npm script, changed-file skip,
- * freshness skip, capture + stamp) is reachable without spawning
- * `npm run test:coverage` or touching the real filesystem.
- *
- * Every seam on the optional final `deps` parameter defaults to the real
- * implementation (`.agents/rules/test-seams.md` rules 1-2, 4), so the CLI
- * shell below and any production caller are unchanged.
- *
- * @param {string[]} [argv] Full `process.argv`-shaped array.
+ * @param {string[]} [argv]
  * @param {{
  *   resolveConfigImpl?: typeof resolveConfig,
  *   getQualityImpl?: typeof getQuality,
@@ -109,9 +68,9 @@ export function parseArgs(argv) {
  *   filterFilesUnderTargetsImpl?: typeof filterFilesUnderTargets,
  *   logger?: { info: Function, warn: Function, error: Function },
  * }} [deps]
- * @returns {number} process exit code
+ * @returns {Promise<number>}
  */
-export function runCoverageCapture(argv = process.argv, deps = {}) {
+export async function runCoverageCapture(argv = process.argv, deps = {}) {
   const {
     resolveConfigImpl = resolveConfig,
     getQualityImpl = getQuality,
@@ -134,13 +93,7 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
     return 0;
   }
 
-  // Story #4473 — detect the "missing npm script" misconfiguration
-  // distinctly. `close-validation/gates.js` already declines to register
-  // this gate when `test:coverage` is absent, so reaching here without the
-  // script means a direct/pre-push invocation in a consumer that never
-  // defined it. Surface a one-line, fix-naming diagnostic instead of
-  // spawning `npm run test:coverage` only to propagate npm's opaque
-  // "Missing script" exit code.
+  // Name the fix rather than propagate npm's opaque "Missing script" exit.
   if (!hasNpmScriptImpl(readPackageScriptsImpl(args.cwd), 'test:coverage')) {
     logger.error(
       '[coverage-capture] ✖ No "test:coverage" script in package.json. ' +
@@ -150,29 +103,15 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
     return 1;
   }
 
-  // Story #5173 — the host-level full-suite lock. Resolved once here, where
-  // the config is already in scope, and composed over the capture runner so
-  // whichever path reaches the spawn is serialized without either of them
-  // knowing about it. `delivery.execution.fullSuiteLock: false` and
-  // `MANDREL_FULL_SUITE_LOCK=0` each disable it; both hatches live in
-  // `isFullSuiteLockEnabled`.
-  // Two wrappers, composed outermost-first: the credit probe announces (or
-  // refuses) the run, and only a run that survives it reaches the host lock.
-  // Whichever capture path gets here spawns through both without knowing
-  // about either.
+  // Outermost first: the credit probe announces or refuses the run, and only
+  // a surviving run reaches the host-level full-suite lock.
   const capture = creditedCapture(lockedCapture(runCaptureImpl, config), {
     requireCredited: args.requireCredited,
     logger,
   });
 
-  // Story #4981/#5173 — the capture skip, gated by
-  // `delivery.quality.gates.crap.incrementalCoverage.skipWhenUnchanged` (on
-  // by default). `null` means "not applicable" (switched off, or a
-  // ref-resolution error) — fall through to the full-scope path below rather
-  // than silently skipping capture.
-  // The two capture paths take the same collaborators bar one; naming that
-  // set once keeps a new seam from being threaded into one and forgotten on
-  // the other.
+  // Shared so a new seam cannot reach one capture path and miss the other.
+  // An incremental `null` means not applicable: fall through to full scope.
   const shared = {
     crap,
     coverage,
@@ -185,29 +124,26 @@ export function runCoverageCapture(argv = process.argv, deps = {}) {
     logger,
   };
 
-  const incrementalResult = tryIncrementalCapture({
+  const incrementalResult = await tryIncrementalCapture({
     ...shared,
     filterFilesUnderTargetsImpl,
   });
   if (incrementalResult !== null) return incrementalResult;
 
-  return runFullScopeCapture(shared);
+  return await runFullScopeCapture(shared);
 }
 
-// cli-opt-out: synchronous main returns an exit code that is forwarded via process.exit(code); runAsCli's async-main signature does not preserve the result code.
-// The direct-invocation guard keeps `import`ing this module (from the unit
-// tests that drive `runCoverageCapture` with injected seams) side-effect free;
-// invoked as a CLI the behaviour — exit code and log lines — is unchanged.
+// cli-opt-out: main resolves an exit code that is forwarded via process.exit(code); runAsCli's async-main signature does not preserve the result code.
 if (isDirectInvocation(import.meta.url)) {
-  try {
-    // `--help` is answered before the decision core runs: it used to fall
-    // through to the capture path, so asking this script to describe itself
-    // spawned the whole coverage suite.
-    process.exit(
-      handleCoverageCaptureHelp(process.argv) ? 0 : runCoverageCapture(),
-    );
-  } catch (err) {
-    Logger.error('[coverage-capture] unexpected error:', err);
-    process.exit(1);
-  }
+  // `--help` must not reach the core, which would spawn the whole suite.
+  (handleCoverageCaptureHelp(process.argv)
+    ? Promise.resolve(0)
+    : runCoverageCapture()
+  ).then(
+    (code) => process.exit(code),
+    (err) => {
+      Logger.error('[coverage-capture] unexpected error:', err);
+      process.exit(1);
+    },
+  );
 }

package/.agents/scripts/deliver-light.js

@@ -1,58 +1,13 @@
 #!/usr/bin/env node
 
 /**
- * deliver-light.js — the `/deliver-light` entry point (Story #4740).
+ * `/deliver-light` entry point — a thin shell, not a second engine: a
+ * risk-only suitability gate, a receipt Story, then the same init/close
+ * scripts `/mandrel-deliver` uses (never reimplemented). `--backstop`
+ * re-checks the ACTUAL diff, the only size block. An escalation ends the
+ * light path, not the session.
  *
- * A **thin entry point, not a second delivery engine.** It runs the
- * suitability gate, authors a minimal receipt `type::story`, and then hands off
- * to the SAME engine scripts `/mandrel-deliver` uses:
- *
- *   suitability gate  →  inline receipt Story  →  single-story-init.js
- *     →  (agent implements + self-evals)  →  diff backstop
- *     →  single-story-close.js  (close-and-land, every gate byte-identical)
- *
- * Worktree, branch, lease, PR, and merge mechanics are **invoked, never
- * reimplemented** — this file contains no parallel init/close logic
- * ({@link buildNextCommands} references the engine scripts by name). The
- * reusable decision core lives in
- * {@link module:lib/orchestration/light-suitability}; this module is the CLI
- * shell plus the receipt-authoring and diff-backstop wiring.
- *
- * Two modes:
- *
- *   - **gate** (default) — judge a prompt's predicted footprint. On
- *     `proceed-light` it authors the receipt Story (via the plan-persist
- *     `createStoryIssues` surface) and prints the init/close hand-off,
- *     carrying any predicted-shape `warnings[]` (Story #5313: an over-ceiling
- *     prediction warns, it no longer stops). An un-ledgered verdict or an
- *     un-waivable risk rule emits an `escalated` terminal envelope, never
- *     landing silently. The former attended stop-and-ask outcome and the
- *     flag that answered it went with the gate they answered.
- *   - **backstop** (`--backstop --story <id>`) — re-check the ACTUAL diff of
- *     the Story branch after implementation; exit non-zero when it exceeds the
- *     light ceilings, so an over-scope diff is blocked rather than landed.
- *
- * ## Escalation is terminal, not advisory (Story #4746)
- *
- * Over-scope under `--yes` emits a schema-validated `story-deliver-terminal`
- * envelope with status `escalated` and **ends the session**. Before that it was
- * an ordinary gate envelope plus exit 2 — a warning a caller could walk past,
- * and one mandrel-bench 2.13.0 light-arm run did exactly that: it read the
- * escalation, invoked `/mandrel-plan` in the same session, and delivered. In-session
- * planning under-decomposed (ONE Story against the scenario's 3-5 contract,
- * where a fresh `/mandrel-plan` session on the identical seed authored four), so
- * escalation silently produced the outcome the guard exists to prevent.
- * {@link module:lib/orchestration/story-deliver-terminal.buildEscalationTerminal}
- * carries the guarantees the schema then enforces.
- *
- * Usage:
- *   node .agents/scripts/deliver-light.js --prompt "<text>" \
- *     --creates path,path --acceptance 1 --route lite --reason "<why>"
- *   node .agents/scripts/deliver-light.js --prompt "<text>" --amends '#123' --route lite --reason "<why>"
- *   node .agents/scripts/deliver-light.js --backstop --story 4741
- *
- * Exit codes: 0 ok (proceed / clean backstop), 1 usage error, 2 the gate did
- * not proceed light (an `escalated` terminal), 3 the diff backstop blocked.
+ * Exit codes: 0 ok, 1 usage error, 2 escalated, 3 backstop blocked.
  */
 
 import { parseArgs } from 'node:util';
@@ -81,37 +36,26 @@ import { createProvider } from './lib/provider-factory.js';
 const HELP = `\
 Usage:
   deliver-light.js --prompt <text> [--creates csv] [--refactors csv]
-                   [--acceptance n] [--kinds csv] [--magnitude m]
-                   [--uncertainty u] [--route lite|full] [--reason <text>]
-                   [--amends '#id'] [--yes]
+                   --reason <text> [--amends '#id']
   deliver-light.js --backstop --story <id>
 
 The thin /deliver-light entry point: suitability gate → inline receipt Story →
 the same single-story-init.js / single-story-close.js engine /mandrel-deliver uses.
 
-The gate judges EFFORT and RISK, not artifact counts: N instances of one
-mechanical edit is one kind at N sites. A predicted shape past a light ceiling
-is a WARNING on the envelope, not a refusal (Story #5313); only an un-ledgered
-verdict or an un-waivable risk rule (sensitive path, migration span) escalates.
-The --backstop pass enforces size against the actual diff.
+The gate judges RISK, not size. Only two things refuse: a verdict with no
+recorded reason, and an un-waivable risk rule the predicted PATHS trip (a
+sensitive-path class, a migration paired with its consumers). The predicted-
+shape ceilings were self-declared buckets and are gone (Story #5344, after
+Story #5313 had already demoted them to warnings). The --backstop pass measures
+the ACTUAL diff and is the only size block.
 
 Gate options:
   --prompt <text>    Operator prompt describing the change. Required for the gate.
   --creates <csv>    Predicted NEW file paths (comma-separated).
   --refactors <csv>  Predicted edited/existing file paths (comma-separated).
-  --acceptance <n>   Predicted acceptance-criteria count (default 1). Not capped.
-  --kinds <csv>      Distinct KINDS of change (default: one per assumption, so
-                     N same-shaped edits count once).
-  --magnitude <m>    Coarse effort bucket: trivial | moderate | substantial
-                     (default moderate; substantial routes to /mandrel-plan).
-  --uncertainty <u>  determined (the request fixes the shape) | needs-design
-                     (default determined; needs-design routes to /mandrel-plan).
-  --route <r>        Ledgered model verdict route: lite | full.
-  --reason <text>    Recorded reason for a lite verdict (required for lite).
+  --reason <text>    Recorded reason for taking the light path. Required: an
+                     un-ledgered verdict escalates.
   --amends <#id>     Mark this as an amendment of an existing issue.
-  --yes              Unattended marker. Escalation is terminal either way;
-                     the flag is accepted so unattended callers keep their
-                     invocation shape.
 
 Backstop options:
   --backstop         Re-check the ACTUAL diff after implementation. Bounds the
@@ -126,8 +70,6 @@ Backstop options:
 `;
 
 /**
- * Split a comma-separated path list into trimmed, non-empty entries.
- *
  * @param {string|undefined} csv
  * @returns {string[]}
  */
@@ -140,9 +82,6 @@ export function parseCsvPaths(csv) {
 }
 
 /**
- * Assemble the predicted `changes[]` footprint from the declared creates /
- * refactors lists — the input {@link deriveLightSuitability} shape-checks.
- *
  * @param {{ creates?: string[], refactors?: string[] }} args
  * @returns {Array<{ path: string, assumption: string }>}
  */
@@ -154,63 +93,26 @@ export function buildPredictedChanges({ creates = [], refactors = [] } = {}) {
 }
 
 /**
- * Synthesize a predicted-acceptance array of the requested length — the shape
- * gate reads the count, not the text, so placeholder strings suffice. A count
- * below 1 yields a single-item array (a Story with no contract cannot be judged
- * trivial, and the shape derivation rejects a zero-length acceptance anyway).
- *
- * @param {unknown} count
- * @returns {string[]}
- */
-export function synthesizeAcceptance(count) {
-  const n =
-    typeof count === 'number' && Number.isFinite(count) && count >= 1
-      ? Math.floor(count)
-      : 1;
-  return Array.from({ length: n }, (_v, i) => `AC-${i + 1}`);
-}
-
-/**
- * Run the suitability gate purely — no I/O. Returns the outcome envelope the
- * CLI serializes. The prompt text and `--amends` target are deliberately **not**
- * inputs: routing is shape-checked identically whether or not the change is an
- * amendment (Story #4740 R3), and the prompt's text carries no routing signal —
- * the predicted footprint does. Both flow into the receipt Story instead.
- *
+ * Pure. The prompt and `--amends` are deliberately not inputs: only the
+ * recorded reason and the predicted paths carry a routing signal.
  * @param {{
  *   creates?: string[],
  *   refactors?: string[],
- *   acceptance?: number,
- *   kinds?: string[],
- *   magnitude?: string,
- *   uncertainty?: string,
- *   route?: string,
  *   reason?: string,
  *   injectedRules?: object,
- * }} args `kinds` / `magnitude` / `uncertainty` are the declared effort-and-risk
- *   axes the gate judges (Story #4764); omitting them declares no signal, not a
- *   small one — an unrecognized bucket is reported as a warning (Story #5313).
+ * }} args
  * @returns {{ action: string, suitability: object, outcome: object }}
  */
 export function runLightGate({
   creates = [],
   refactors = [],
-  acceptance,
-  kinds,
-  magnitude,
-  uncertainty,
-  route,
   reason,
   injectedRules,
 } = {}) {
   const predictedChanges = buildPredictedChanges({ creates, refactors });
   const suitability = deriveLightSuitability({
     predictedChanges,
-    predictedAcceptance: synthesizeAcceptance(acceptance),
-    predictedKinds: kinds,
-    predictedMagnitude: magnitude,
-    predictedUncertainty: uncertainty,
-    verdict: { route, reason },
+    verdict: { reason },
     injectedRules,
   });
   const outcome = resolveLightGateOutcome({ suitability });
@@ -218,9 +120,6 @@ export function runLightGate({
 }
 
 /**
- * Author the receipt Story via the plan-persist creation surface (reused, not
- * reimplemented). Injectable seams keep it unit-testable without a network.
- *
  * @param {{
  *   provider: object,
  *   prompt: string,
@@ -256,10 +155,6 @@ export async function createLightReceipt({
 }
 
 /**
- * The engine hand-off — the SAME scripts `/mandrel-deliver` uses. Named here as
- * commands, never reimplemented: this is the whole of deliver-light's
- * relationship to worktree/branch/lease/PR/merge mechanics.
- *
  * @param {number} storyId
  * @returns {{ init: string, close: string }}
  */
@@ -271,9 +166,6 @@ export function buildNextCommands(storyId) {
 }
 
 /**
- * Emit a JSON envelope on stdout (the machine surface) so a headless caller can
- * branch on it. Human-readable log lines stay on stderr.
- *
  * @param {object} envelope
  * @param {boolean} pretty
  */
@@ -286,10 +178,7 @@ function emit(envelope, pretty) {
 }
 
 /**
- * Backstop mode — re-check the actual diff. The decision lives in
- * {@link module:lib/orchestration/light-backstop}; this branches and prints.
- *
- * @param {object} values Parsed CLI values.
+ * @param {object} values
  * @param {{ resolveFn?: typeof resolveBackstopOutcome }} [deps]
  * @returns {Promise<number>}
  */
@@ -310,25 +199,9 @@ async function runBackstopMode(values, deps = {}) {
 }
 
 /**
- * Gate mode — judge the prompt and, on proceed, author the receipt Story.
- *
- * The three outcomes are deliberately asymmetric in what they emit:
- *
- *   - **`escalate-plan`** returns a schema-validated `escalated` **terminal
- *     envelope** and stops (Story #4746). It is placed **first**, above every
- *     creation call site, so "nothing was started" is a property of the
- *     control flow rather than a claim the envelope makes about itself.
- *   - **`proceed-light`** authors the receipt Story and prints the hand-off,
- *     carrying the predicted-shape `warnings[]` (Story #5313) on the envelope
- *     and on stderr, so an over-ceiling prediction is stated rather than
- *     silently waved through. The former attended stop-and-ask outcome is
- *     gone: the gate never had a question a human could answer that the diff
- *     backstop does not answer better.
- *
- * The injectable seams exist so the no-side-effect guarantee is testable
- * without a network: a test asserts the escalate path never reaches them.
- *
- * @param {object} values Parsed CLI values.
+ * The escalate branch sits above every creation call site, so "nothing was
+ * started" is a property of the control flow, not a claim of the envelope.
+ * @param {object} values
  * @param {{
  *   createProviderFn?: typeof createProvider,
  *   resolveConfigFn?: typeof resolveConfig,
@@ -356,13 +229,6 @@ export async function runGateMode(values, deps = {}) {
   const gate = runLightGate({
     creates: parseCsvPaths(values.creates),
     refactors: parseCsvPaths(values.refactors),
-    acceptance: values.acceptance
-      ? Number.parseInt(String(values.acceptance), 10)
-      : 1,
-    kinds: parseCsvPaths(values.kinds),
-    magnitude: values.magnitude,
-    uncertainty: values.uncertainty,
-    route: values.route,
     reason: values.reason,
   });
 
@@ -372,16 +238,14 @@ export async function runGateMode(values, deps = {}) {
       reasons: gate.outcome.reasons,
     });
     emitTerminalFn(envelope);
-    // The refusal is still telemetered (Story #4856): the ceilings stay
-    // recalibratable from evidence even now that only risk rules refuse.
+    // Telemetered so the rules stay recalibratable from evidence.
     await recordRefusalFn({ gate, amends: values.amends });
     Logger.warn(
-      `[deliver-light] ESCALATED to /mandrel-plan — this session ENDS here; run ${envelope.nextCommand} in a FRESH session: ${gate.outcome.reasons.join('; ')}`,
+      `[deliver-light] ESCALATED to /mandrel-plan — the light path ENDS here; run ${envelope.nextCommand}, seeded with these reasons: ${gate.outcome.reasons.join('; ')}`,
     );
     return exitCodeForTerminal(envelope);
   }
 
-  const warnings = gate.outcome.warnings ?? [];
   const provider = createProviderFn(resolveConfigFn());
   const receipt = await createReceiptFn({
     provider,
@@ -398,15 +262,11 @@ export async function runGateMode(values, deps = {}) {
       action: 'proceed-light',
       storyId: receipt.storyId,
       url: receipt.url,
-      warnings,
       nextCommands: buildNextCommands(receipt.storyId),
       outcome: gate.outcome,
     },
     values.pretty,
   );
-  for (const warning of warnings) {
-    Logger.warn(`[deliver-light] ⚠ ${warning}`);
-  }
   Logger.info(
     `[deliver-light] receipt Story #${receipt.storyId} created — hand off to single-story-init.js.`,
   );
@@ -419,14 +279,8 @@ async function main() {
       prompt: { type: 'string' },
       creates: { type: 'string' },
       refactors: { type: 'string' },
-      acceptance: { type: 'string' },
-      kinds: { type: 'string' },
-      magnitude: { type: 'string' },
-      uncertainty: { type: 'string' },
-      route: { type: 'string' },
       reason: { type: 'string' },
       amends: { type: 'string' },
-      yes: { type: 'boolean', default: false },
       backstop: { type: 'boolean', default: false },
       story: { type: 'string' },
       pretty: { type: 'boolean', default: false },

package/.agents/scripts/deliver-recover.js

@@ -1,40 +1,13 @@
 #!/usr/bin/env node
 
 /**
- * deliver-recover.js — probe a stranded Story's live state and print the ONE
- * command that resumes it (Story #4543).
+ * Read-only: probes a stranded Story's live state and prints the ONE command
+ * that resumes it — never a menu, and never a re-dispatch, which would re-run
+ * init under live work and put a second close on one PR. Covers the
+ * merged-but-label-stale Story that `/mandrel-deliver` refuses outright.
  *
- * Read-only by construction. This CLI mutates nothing: it reads the ticket's
- * labels and lease, the Story branch locally and via its tracking ref, the
- * worktree, and the PR (state + checks), then walks a fixed decision table
- * and prints one command with the evidence it was derived from. It never
- * prints a menu — a menu of options is what the operator already has, and it
- * is the thing they cannot act on.
- *
- * The strand this exists for above all others is the **merged-but-label-stale**
- * Story: a `/mandrel-deliver` re-run refuses it outright, because
- * `single-story-init.js` hard-errors on an already-closed Story. Before this
- * surface, that Story had no automated way back.
- *
- * Every command it prints **resumes** — it re-enters the in-flight worker or
- * close, or closes the branch that is already pushed. None of them re-dispatch
- * the Story, and that is deliberate: since Story #4876 the close-and-land tail
- * belongs to the dispatching orchestrator, so a worker returning without a
- * terminal envelope is the expected shape rather than evidence the Story never
- * ran. Answering it with a fresh dispatch re-runs `single-story-init.js`
- * underneath live work and puts a second close on one PR.
- *
- * Usage:
- *   node .agents/scripts/deliver-recover.js --story <STORY_ID> [--cwd <main-repo>]
- *                                           [--json]
- *
- * Exit codes:
- *   0 — a recovery shape was resolved and its next command printed (including
- *       the "nothing to recover" shapes). Reading state is not a failure.
- *   1 — the probe itself could not run (unreadable ticket, bad input).
- *
- * @see .agents/scripts/lib/orchestration/deliver-recover.js
- * @see .agents/schemas/story-deliver-terminal.schema.json
+ * Exit codes: 0 a shape resolved (including nothing-to-recover), 1 the probe
+ * itself could not run.
  */
 
 import { parseArgs } from 'node:util';
@@ -94,15 +67,6 @@ export function parseArgv(argv) {
 }
 
 /**
- * Probe and report. Exported for testing.
- *
- * The optional final `deps` parameter is the module's injectable seam
- * (`.agents/rules/test-seams.md` rules 1-2): config resolution, provider
- * construction, the probe itself, the renderer, and the log sink each default
- * to the real implementation, so the CLI path and every production caller are
- * unchanged. The pre-existing `injected*` fields on the first argument stay
- * supported for callers already threading a resolved provider/config.
- *
  * @param {object} [args]
  * @param {{
  *   resolveConfigImpl?: typeof resolveConfig,