mandrel 1.94.0 → 2.1.0

package/.agents/scripts/audit-to-stories.js

@@ -12,8 +12,8 @@
  *     Emits a single `audit-to-stories-plan.json` envelope to --out (or
  *     stdout when --json is set).
  *
- *   --emit-epic-seed --plan <plan.json> --out <path>
- *     Read the plan envelope from disk, render the `/plan --idea`
+ *   --emit-plan-seed --plan <plan.json> --out <path>
+ *     Read the plan envelope from disk, render the `/plan --seed`
  *     seed markdown, persist to --out.
  *
  *   --emit-stories --plan <plan.json>
@@ -37,7 +37,7 @@ import { classifyGroupsAgainstGitHub } from './lib/audit-to-stories/dedupe-again
 import { withFingerprints } from './lib/audit-to-stories/finding-adapter.js';
 import { groupFindings } from './lib/audit-to-stories/group-findings.js';
 import { parseAuditReports } from './lib/audit-to-stories/parse-audit-md.js';
-import { buildEpicSeedMarkdown } from './lib/audit-to-stories/seed-epic-from-findings.js';
+import { buildPlanSeedMarkdown } from './lib/audit-to-stories/seed-from-findings.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { Logger } from './lib/Logger.js';
 import { parse as parseStoryBody } from './lib/story-body/story-body.js';
@@ -291,7 +291,7 @@ async function main() {
     args: process.argv.slice(2),
     options: {
       scan: { type: 'boolean' },
-      'emit-epic-seed': { type: 'boolean' },
+      'emit-plan-seed': { type: 'boolean' },
       'emit-stories': { type: 'boolean' },
       glob: { type: 'string' },
       severity: { type: 'string' },
@@ -315,9 +315,9 @@ async function main() {
     return;
   }
 
-  if (values['emit-epic-seed']) {
+  if (values['emit-plan-seed']) {
     const plan = loadPlan(values.plan);
-    const md = buildEpicSeedMarkdown({
+    const md = buildPlanSeedMarkdown({
       groups: plan.groups ?? [],
       findings: plan.findings ?? [],
       sourceReports: plan.sourceReports ?? [],
@@ -346,7 +346,7 @@ async function main() {
   }
 
   throw new Error(
-    'Usage: node audit-to-stories.js (--scan | --emit-epic-seed | --emit-stories) [options]',
+    'Usage: node audit-to-stories.js (--scan | --emit-plan-seed | --emit-stories) [options]',
   );
 }
 

package/.agents/scripts/boot-sweep.js

@@ -72,7 +72,7 @@ Options:
  * returns the sweep envelope so no caller can be blocked by a failure.
  *
  * DI-friendly: `injectedConfig` / `injectedProvider` let a caller (e.g.
- * `epic-deliver-prepare.js`) reuse an already-resolved config + provider,
+ * `single-story-init.js`) reuse an already-resolved config + provider,
  * and `injectedSweep` swaps the engine for unit tests.
  *
  * @param {{

package/.agents/scripts/bootstrap.js

@@ -45,8 +45,8 @@
  *                             and custom fields. Off by default — the project
  *                             board object is still created when a project
  *                             name is supplied, but decoration is skipped.
- *   --with-issue-forms        Opt-in: generate .github/ISSUE_TEMPLATE/story.yml
- *                             and epic.yml. Off by default.
+ *   --with-issue-forms        Opt-in: generate .github/ISSUE_TEMPLATE/story.yml.
+ *                             Off by default.
  *   --reap-conflicting-workflows  Delete Projects V2 built-in workflows that
  *                             race against the orchestrator (destructive)
  *   --help                    Print this help
@@ -112,7 +112,7 @@ Flags:
   --with-project-board      Opt-in: provision the Projects V2 Status field
                             and custom fields (default: off — prompted y/N).
   --with-issue-forms        Opt-in: generate .github/ISSUE_TEMPLATE/story.yml
-                            and epic.yml (default: off — prompted y/N).
+                            (default: off — prompted y/N).
   --reap-conflicting-workflows  Delete Projects V2 built-in workflows that
                             race against the orchestrator (destructive)
   --help                    Print this help

package/.agents/scripts/check-dead-exports.js

@@ -9,12 +9,18 @@
  * misconfigured knip installation cannot block CI when we have no current
  * snapshot to compare against.
  *
+ * Story #4575 adds the **production pass** (`--production`), the test-only-
+ * importer discount: default mode counts a test as an importer, so
+ * production-dead code hides behind its own tests. See
+ * `lib/dead-exports-mode.js` for why the two passes carry separate baselines.
+ *
  * Contract:
- *   - Reads the committed baseline at `baselines/dead-exports.json`
- *     (override with `--baseline <path>`). Envelope shape:
+ *   - Reads the committed baseline at `baselines/dead-exports.json` — or
+ *     `baselines/dead-exports-production.json` under `--production`
+ *     (override either with `--baseline <path>`). Envelope shape:
  *       { $schema, kernelVersion, generatedAt, rows: [{ file, symbol }] }
- *   - Spawns `npx knip --reporter json --no-progress`, parses stdout,
- *     extracts `{ file, symbol }` rows from `issues[].exports[]`.
+ *   - Spawns `npx knip --reporter json --no-progress` (plus `--production`),
+ *     parses stdout, extracts `{ file, symbol }` rows from `issues[].exports[]`.
  *   - Diffs current vs. baseline by `(file, symbol)` identity.
  *   - Prints `+ <file>: <symbol>` for each added dead export and
  *     `- <file>: <symbol>` for each removed one, then a summary line.
@@ -25,24 +31,30 @@
  *     Knip spawn/parse failure exits 0 (advisory) with a stderr warning.
  */
 
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { runAsCli } from './lib/cli-utils.js';
+import {
+  extractRowsFromKnip,
+  readKnipOutput,
+  runKnip,
+} from './lib/dead-exports-knip.js';
+import { resolveDeadExportsMode } from './lib/dead-exports-mode.js';
 
 /**
- * Parse argv for `--baseline <path>`, `--json`, and `--knip-output <path>`.
- * `--knip-output` is a test seam: pass a pre-captured knip JSON file instead
- * of spawning knip. Exported so unit tests can pin the parser.
+ * Parse argv for `--baseline <path>`, `--json`, `--knip-output <path>`, and
+ * `--production`. `--knip-output` is a test seam: pass a pre-captured knip JSON
+ * file instead of spawning knip. Exported so unit tests can pin the parser.
  *
  * @param {string[]} argv
- * @returns {{ baselinePath: string | null, json: boolean, knipOutputPath: string | null }}
+ * @returns {{ baselinePath: string | null, json: boolean, knipOutputPath: string | null, production: boolean }}
  */
 export function parseArgv(argv = []) {
   let baselinePath = null;
   let json = false;
   let knipOutputPath = null;
+  let production = false;
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--baseline') {
@@ -53,6 +65,8 @@ export function parseArgv(argv = []) {
       }
     } else if (a === '--json') {
       json = true;
+    } else if (a === '--production') {
+      production = true;
     } else if (a === '--knip-output') {
       const next = argv[i + 1];
       if (next && !next.startsWith('--')) {
@@ -61,7 +75,7 @@ export function parseArgv(argv = []) {
       }
     }
   }
-  return { baselinePath, json, knipOutputPath };
+  return { baselinePath, json, knipOutputPath, production };
 }
 
 /**
@@ -84,36 +98,6 @@ export function loadBaseline(baselinePath) {
   }
 }
 
-/**
- * Pure helper: normalize knip's `--reporter json` output into a flat array of
- * `{ file, symbol }` rows. Knip emits `{ issues: [{ file, exports: [{ name, ... }], ... }, ...] }`.
- * Only `exports` rows are mapped — the dead-export ratchet ignores file-level,
- * dependency-level, and duplicate-level issues (knip surfaces those via
- * separate `rules` keys).
- *
- * @param {unknown} knipEnvelope The parsed knip JSON report.
- * @returns {Array<{ file: string, symbol: string }>}
- */
-export function extractRowsFromKnip(knipEnvelope) {
-  const rows = [];
-  if (!knipEnvelope || typeof knipEnvelope !== 'object') return rows;
-  const issues = Array.isArray(knipEnvelope.issues) ? knipEnvelope.issues : [];
-  for (const issue of issues) {
-    const file = issue?.file;
-    if (typeof file !== 'string' || file.length === 0) continue;
-    const exports_ = Array.isArray(issue.exports) ? issue.exports : [];
-    for (const e of exports_) {
-      const symbol =
-        (e && typeof e.name === 'string' && e.name) ||
-        (e && typeof e.symbol === 'string' && e.symbol) ||
-        null;
-      if (!symbol) continue;
-      rows.push({ file, symbol });
-    }
-  }
-  return rows;
-}
-
 /**
  * Pure helper: diff two `{ file, symbol }` row sets. Returns `added` (in
  * current but not baseline) and `removed` (in baseline but not current).
@@ -151,75 +135,24 @@ export function diffRows(baselineRows, currentRows) {
  * "no drift" signal. When added rows are present the summary includes a
  * "(gate fail)" marker so the ratchet violation is visible in CI output.
  *
+ * `label` distinguishes the two passes in CI logs, which run back to back and
+ * would otherwise emit two identical-looking summaries.
+ *
  * @param {{ added: Array, removed: Array }} diff
+ * @param {string} [label='dead-exports']
  * @returns {string}
  */
-export function renderDiff(diff) {
+export function renderDiff(diff, label = 'dead-exports') {
   const lines = [];
   for (const r of diff.added) lines.push(`+ ${r.file}: ${r.symbol}`);
   for (const r of diff.removed) lines.push(`- ${r.file}: ${r.symbol}`);
   const tag = diff.added.length > 0 ? '(gate fail)' : '(ok)';
   lines.push(
-    `[dead-exports] added=${diff.added.length} removed=${diff.removed.length} ${tag}`,
+    `[${label}] added=${diff.added.length} removed=${diff.removed.length} ${tag}`,
   );
   return lines.join('\n');
 }
 
-/**
- * Spawn `npx knip --reporter json --no-progress` and return the parsed
- * envelope. Returns `null` on spawn / parse failure — the caller logs the
- * underlying error and falls back to treating current rows as empty (which
- * surfaces every baseline row as "removed", a loud-but-safe signal).
- *
- * Exported as a hook so tests can stub the spawn without setting up a
- * functioning knip workspace.
- *
- * @param {{ cwd?: string, spawn?: typeof spawnSync }} [opts]
- * @returns {{ ok: true, envelope: unknown } | { ok: false, error: string }}
- */
-export function runKnip({ cwd = process.cwd(), spawn = spawnSync } = {}) {
-  const result = spawn(
-    process.platform === 'win32' ? 'npx.cmd' : 'npx',
-    ['knip', '--reporter', 'json', '--no-progress'],
-    {
-      cwd,
-      stdio: ['ignore', 'pipe', 'pipe'],
-      encoding: 'utf-8',
-      shell: process.platform === 'win32',
-    },
-  );
-  if (result.error) {
-    return { ok: false, error: `spawn failed: ${result.error.message}` };
-  }
-  const stdout = typeof result.stdout === 'string' ? result.stdout : '';
-  if (stdout.trim().length === 0) {
-    return { ok: false, error: 'knip produced empty stdout' };
-  }
-  try {
-    return { ok: true, envelope: JSON.parse(stdout) };
-  } catch (err) {
-    return {
-      ok: false,
-      error: `knip JSON parse failed: ${err?.message ?? err}`,
-    };
-  }
-}
-
-/**
- * Read a pre-captured knip JSON envelope from disk (for the `--knip-output`
- * test seam). Returns the parsed envelope or `null` on failure.
- *
- * @param {string} filePath
- * @returns {unknown}
- */
-function readKnipOutput(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Top-level CLI entry. Exported so tests can drive the full pipeline through
  * injected hooks without spawning knip.
@@ -242,10 +175,15 @@ export async function runCli({
   runKnipImpl = runKnip,
   loadBaselineImpl = loadBaseline,
 } = {}) {
-  const { baselinePath, json, knipOutputPath } = parseArgv(argv);
+  const { baselinePath, json, knipOutputPath, production } = parseArgv(argv);
+  const {
+    mode,
+    label,
+    baseline: defaultBaseline,
+  } = resolveDeadExportsMode(production);
   const resolvedBaselinePath = path.resolve(
     cwd,
-    baselinePath ?? path.join('baselines', 'dead-exports.json'),
+    baselinePath ?? defaultBaseline,
   );
   const baseline = loadBaselineImpl(resolvedBaselinePath);
   const baselineRows = Array.isArray(baseline?.rows) ? baseline.rows : [];
@@ -256,7 +194,7 @@ export async function runCli({
     knipEnvelope = readKnipOutput(path.resolve(cwd, knipOutputPath));
     if (!knipEnvelope) knipError = `failed to read ${knipOutputPath}`;
   } else {
-    const result = runKnipImpl({ cwd });
+    const result = runKnipImpl({ cwd, production });
     if (result.ok) {
       knipEnvelope = result.envelope;
     } else {
@@ -275,6 +213,7 @@ export async function runCli({
   if (json) {
     const envelope = {
       kind: 'dead-exports-report',
+      mode,
       baselinePath: resolvedBaselinePath,
       baselineRows,
       currentRows,
@@ -287,14 +226,14 @@ export async function runCli({
   } else {
     if (!baseline) {
       stderr.write(
-        `[dead-exports] ⚠ baseline not found at ${resolvedBaselinePath} — treating as empty\n`,
+        `[${label}] ⚠ baseline not found at ${resolvedBaselinePath} — treating as empty\n`,
       );
     }
     if (knipError) {
-      stderr.write(`[dead-exports] ⚠ knip run failed: ${knipError}\n`);
+      stderr.write(`[${label}] ⚠ knip run failed: ${knipError}\n`);
     }
-    stdout.write(`\n--- dead-exports preview ---\n`);
-    stdout.write(`${renderDiff(diff)}\n`);
+    stdout.write(`\n--- ${label} preview ---\n`);
+    stdout.write(`${renderDiff(diff, label)}\n`);
   }
 
   return exitCode;

package/.agents/scripts/check-doc-links.js

@@ -257,8 +257,8 @@ function stripAnchorAndQuery(target) {
 // A slash token is `/<name>` where:
 //   - the preceding char is NOT a word char, `/`, `:`, `.`, `>`, `]`, `)`,
 //     so we don't match URL path segments or fragments embedded in paths
-//     like `temp/epic-<id>/lifecycle.ndjson` (preceded by `>`) or
-//     `temp/epic-[ID]/tickets.json` (preceded by `]`).
+//     like `temp/run-<id>/lifecycle.ndjson` (preceded by `>`) or
+//     `temp/run-[ID]/tickets.json` (preceded by `]`).
 //   - the following char is NOT a word char, `-`, or `.`, so file
 //     extensions like `/tickets.json` and identifier suffixes don't match.
 // The optional `(?::[a-z][a-z0-9-]*)?` tail captures the namespaced

package/.agents/scripts/check-lifecycle-lint.js

@@ -17,7 +17,7 @@
  *   Any module under `.agents/scripts/lib/orchestration/lifecycle/listeners/**`
  *   that calls `bus.on('*', …)` MUST NOT import a side-effecting module.
  *   The static blocklist is small (the modules that mutate GitHub state,
- *   the worktree, or write outside `temp/epic-<id>/`); we match by module
+ *   the worktree, or write outside `temp/run-<id>/`); we match by module
  *   specifier suffix to keep the rule simple and stable.
  *
  * Rule 3 — "Auto-merge lockout" (Story #2253 / Task #2255, Epic #2172
@@ -80,17 +80,14 @@ const SCRIPTS_DIR = path.join(REPO_ROOT, '.agents', 'scripts');
  * auto-merge call could re-enter the codebase.
  */
 const MERGE_LOCKOUT_ALLOWED_SUFFIXES = Object.freeze([
-  // Story #2256 / #2336 — the predicate-gated AutomergeArmer listener is
-  // now the SOLE production code path authorized to call `gh pr merge`.
-  // The legacy `.agents/scripts/epic-deliver-automerge.js` exemption was
-  // removed in Story #2336 / Task #2340 once the CLI was reduced to a
-  // pure `epic.automerge.start` emit shim.
+  // v2 Story close path — the sole production code path authorized to
+  // call `gh pr merge` after the Epic AutomergeArmer listener was removed.
   path.join(
     'lib',
     'orchestration',
-    'lifecycle',
-    'listeners',
-    'automerge-armer.js',
+    'single-story-close',
+    'phases',
+    'auto-merge.js',
   ),
 ]);
 
@@ -339,7 +336,7 @@ export function findMergeLockoutViolations(
           violations.push({
             file,
             line: i + 1,
-            hint: `String literal containing '${FORBIDDEN}' is forbidden outside automerge-armer.js (Story #2253 review High-1). Auto-merge enablement must flow through the AutomergeArmer listener so blocker/review predicates gate the call.`,
+            hint: `String literal containing '${FORBIDDEN}' is forbidden outside single-story-close/phases/auto-merge.js. Auto-merge enablement must flow through the Story close path.`,
           });
           break; // one violation per line is enough
         }

package/.agents/scripts/check-workflow-cli-lint.js

@@ -61,6 +61,19 @@ const BACKTICK_CALL_RE = /`[A-Za-z_$][\w$]*\s*\(/;
 const EXPORTED_FROM_RE = /\bexported from\b/;
 const LIB_IMPORT_RE = /\b(?:import|require)\(\s*['"`][^'"`]*scripts\/lib\//;
 
+/** A markdown table row (leading pipe, optionally indented). */
+const TABLE_ROW_RE = /^\s*\|/;
+/** A markdown heading of any level — the lookback boundary for Rule 4. */
+const HEADING_RE = /^\s*#{1,6}\s/;
+/** A backticked `--flag` occupying a table row's first cell. */
+const FLAG_CELL_RE = /^\s*\|\s*`?--[\w-]+/;
+/** A `.js` script filename — bare or path-qualified. */
+const SCRIPT_NAME_RE = /([\w./-]*[\w-]+\.js)\b/;
+/** A markdown table's delimiter row (`| --- | --- |`). */
+const TABLE_DELIMITER_RE = /^\s*\|[\s|:-]+\|?\s*$/;
+/** Minimum `--flag` rows before a table counts as a flag *table*. */
+export const MIN_FLAG_ROWS = 2;
+
 /**
  * Strip fenced code blocks (``` / ~~~), replacing their lines with empty
  * strings so line numbers stay stable. Complete runnable commands live in
@@ -106,6 +119,82 @@ export function toParagraphs(lines) {
   return paragraphs;
 }
 
+/**
+ * Rule 4 — CLI flag table. Find markdown tables that enumerate the `--flags`
+ * of a script the repo already owns, and flag them as duplicated surface.
+ *
+ * The script's own argument parser is the source of truth for its flags, and
+ * it prints them itself; a copy in prose is drift waiting to happen (the very
+ * drift Story #4546 removed). Prose must point at the command instead.
+ *
+ * The signal is deliberately narrow, to stay at zero false positives:
+ *
+ *   1. The table has at least `MIN_FLAG_ROWS` data rows whose **first cell**
+ *      is a `--flag`. One flag row among prose rows is a contract/behaviour
+ *      table (e.g. "Default | …", "`--dry-run` | …"), not a flag enumeration.
+ *   2. A `.js` script is named between the table and the nearest preceding
+ *      heading (inclusive) — i.e. the section is *about* that script, so the
+ *      table is restating its surface.
+ *
+ * A slash command's own argument table (`/plan`, `/deliver`) has no script
+ * behind it — nothing owns those flags but the workflow prose itself — so
+ * condition 2 leaves it alone by design.
+ *
+ * @param {string[]} rawLines unstripped source lines (fenced commands are the
+ *   usual place a script is named, so this rule reads the original text).
+ * @returns {Array<{ rule: string, line: number, hint: string }>}
+ */
+export function lintFlagTables(rawLines) {
+  const violations = [];
+  let inFence = false;
+
+  for (let i = 0; i < rawLines.length; i++) {
+    if (/^\s*(```|~~~)/.test(rawLines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence || !TABLE_ROW_RE.test(rawLines[i])) continue;
+
+    // Collect the contiguous table block starting here.
+    const start = i;
+    let end = i;
+    while (end + 1 < rawLines.length && TABLE_ROW_RE.test(rawLines[end + 1])) {
+      end += 1;
+    }
+    i = end; // continue scanning after this table
+
+    const flagRows = rawLines
+      .slice(start, end + 1)
+      .filter((l) => !TABLE_DELIMITER_RE.test(l) && FLAG_CELL_RE.test(l));
+    if (flagRows.length < MIN_FLAG_ROWS) continue;
+
+    // Look back to the nearest heading (inclusive) for a named script.
+    let script = null;
+    for (let j = start - 1; j >= 0; j--) {
+      const m = SCRIPT_NAME_RE.exec(rawLines[j]);
+      if (m) {
+        script = m[1];
+        break;
+      }
+      if (HEADING_RE.test(rawLines[j])) break;
+    }
+    if (!script) continue;
+
+    const base = script.split('/').pop();
+    violations.push({
+      rule: 'no-cli-flag-table',
+      line: start + 1,
+      hint:
+        `Workflow prose restates the flag surface of \`${base}\` as a table (${flagRows.length} flag rows). ` +
+        "The script's argument parser owns those flags, so a prose copy is drift waiting to happen. " +
+        `Delete the table and point at the command (\`node .agents/scripts/${base} …\`), keeping only the ` +
+        'judgement a reader cannot get from the command itself. If the script has no help output to point ' +
+        'at, add one — do not re-inline the table.',
+    });
+  }
+  return violations;
+}
+
 /**
  * Lint one markdown source. Returns violations
  * `{ rule, line, hint }[]` (empty when clean).
@@ -115,7 +204,9 @@ export function toParagraphs(lines) {
  */
 export function lintWorkflowSource(source) {
   const violations = [];
+  const rawLines = source.split('\n');
   const lines = stripFences(source);
+  violations.push(...lintFlagTables(rawLines));
   for (const para of toParagraphs(lines)) {
     if (IMPERATIVE_CALL_RE.test(para.text)) {
       violations.push({

package/.agents/scripts/cleanup-repo-test-temp.js

@@ -20,7 +20,12 @@
 import { existsSync, readdirSync, rmSync } from 'node:fs';
 import path from 'node:path';
 import { runAsCli } from './lib/cli-utils.js';
-import { isReservedTestEpicTempDirName } from './lib/test-reserved-epic-temp-ids.js';
+
+const RESERVED_TEST_EPIC_TEMP_DIR = /^epic-999\d{3}$/;
+
+function isReservedTestEpicTempDirName(name) {
+  return RESERVED_TEST_EPIC_TEMP_DIR.test(name);
+}
 
 /**
  * @param {object} [opts]

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

@@ -0,0 +1,122 @@
+#!/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 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 `/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.
+ *
+ * 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
+ */
+
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import {
+  recoverStory,
+  renderRecovery,
+} from './lib/orchestration/deliver-recover.js';
+import { PROJECT_ROOT } from './lib/project-root.js';
+import { createProvider } from './lib/provider-factory.js';
+
+const HELP = `Usage: node .agents/scripts/deliver-recover.js --story <id> [--cwd <main-repo>] [--json]
+
+Probes a Story's live delivery state — labels, lease, branch, worktree, PR
+state and checks — and prints the single next command that resumes it, with
+the evidence it was derived from. Read-only: mutates nothing.
+
+Flags:
+  --story   GitHub issue number of the Story (required).
+  --cwd     Main-repo checkout to probe (default: project root).
+  --json    Emit the full recovery envelope as JSON instead of prose.
+  --help    Show this message.
+`;
+
+export function parseArgv(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      story: { type: 'string' },
+      cwd: { type: 'string' },
+      json: { type: 'boolean', default: false },
+      help: { type: 'boolean', default: false },
+    },
+    strict: false,
+  });
+  return {
+    storyId: Number.parseInt(String(values.story ?? ''), 10),
+    cwd: values.cwd ?? null,
+    json: Boolean(values.json),
+    help: Boolean(values.help),
+  };
+}
+
+/**
+ * Probe and report. Exported for testing.
+ */
+export async function runDeliverRecover({
+  storyId: storyIdParam,
+  cwd: cwdParam,
+  json: jsonParam,
+  argv,
+  injectedProvider,
+  injectedConfig,
+  injectedGh,
+  injectedGitSpawn,
+} = {}) {
+  const parsed =
+    storyIdParam !== undefined
+      ? { storyId: storyIdParam, cwd: cwdParam ?? null, json: !!jsonParam }
+      : parseArgv(argv ?? process.argv.slice(2));
+
+  if (parsed.help) {
+    Logger.info(HELP);
+    return { success: true, result: null };
+  }
+  if (!Number.isInteger(parsed.storyId) || parsed.storyId <= 0) {
+    throw new Error(
+      'Usage: node deliver-recover.js --story <STORY_ID> [--cwd <main-repo>] [--json]',
+    );
+  }
+
+  const cwd = parsed.cwd ?? PROJECT_ROOT;
+  const config = injectedConfig || resolveConfig({ cwd });
+  const provider = injectedProvider || createProvider(config);
+
+  const recovery = await recoverStory({
+    storyId: parsed.storyId,
+    cwd,
+    provider,
+    config,
+    gh: injectedGh,
+    gitSpawnFn: injectedGitSpawn,
+  });
+
+  Logger.info(
+    parsed.json ? JSON.stringify(recovery, null, 2) : renderRecovery(recovery),
+  );
+  return { success: true, result: recovery };
+}
+
+runAsCli(import.meta.url, runDeliverRecover, { source: 'deliver-recover' });

package/.agents/scripts/drain-pending-cleanup.js

@@ -8,7 +8,7 @@
  * any still-stuck entries by enumerating the processes holding handles
  * inside the worktree path and terminating them.
  *
- * Invoked by `/deliver`, `/epic-plan-spec` / `/epic-plan-decompose`
+ * Invoked by `/deliver` and `/plan`
  * (via `drainPendingCleanupAtBoot` → `worktree-sweep.js`), and
  * `story-close` so the pending-cleanup ledger drains automatically
  * across the sprint lifecycle. Operators can also run it standalone: