mandrel 1.57.0

package/.agents/scripts/diagnose.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+
+/**
+ * diagnose.js — `/diagnose` CLI runner.
+ *
+ * Thin reader over the checks registry (`lib/checks/index.js`). Assembles
+ * state for the requested scope, runs every check declared on that scope
+ * with `autoFix: false`, and renders the findings as either a fixed-width
+ * table (default) or single-line JSON (`--json`).
+ *
+ * Distinct from `diagnose-friction.js`: that script wraps a shell command
+ * with telemetry capture and writes per-Story friction signals; this one
+ * is a stateless read of the registry, with no side effects beyond stdout
+ * and an exit code.
+ *
+ * Usage:
+ *   node .agents/scripts/diagnose.js [--scope <scope>] [--fail-on-blocker] [--json]
+ *
+ * Flags:
+ *   --scope <s>          Filter checks by scope. Defaults to `diagnose`.
+ *                        Pass `all` to run every registered check regardless
+ *                        of scope. Any other value is forwarded to the
+ *                        runner verbatim — checks whose `scope[]` includes
+ *                        that string fire.
+ *   --fail-on-blocker    Exit 2 when at least one finding has
+ *                        severity === 'blocker'. Without this flag the
+ *                        runner always exits 0 even if blockers are
+ *                        present; `/diagnose` is by default an advisory
+ *                        read.
+ *   --json               Emit a single line of JSON to stdout shaped as
+ *                        `{ scope, findings: [...] }`. Suppresses the
+ *                        human table and any auxiliary log lines on
+ *                        stdout. Errors still go to stderr.
+ *
+ * Exit codes:
+ *   0  — no blockers, OR `--fail-on-blocker` not set.
+ *   2  — `--fail-on-blocker` set AND at least one blocker finding.
+ *   1  — internal error (registry load failure, etc.). The runner never
+ *        crashes on a missing check directory — that returns the empty
+ *        findings set with exit 0.
+ */
+
+import { runChecks } from './lib/checks/index.js';
+import { assembleState } from './lib/checks/state.js';
+import { parseStandardCliArgs } from './lib/cli/standard-args.js';
+import { runAsCli } from './lib/cli-utils.js';
+
+const DEFAULT_SCOPE = 'diagnose';
+
+/**
+ * Parse the CLI argv slice (i.e. argv without the leading node/script
+ * elements). Exported for direct unit testing — keeps the parse pure so
+ * tests can drive it without spawning a subprocess.
+ *
+ * @param {string[]} argv
+ * @returns {{ scope: string, failOnBlocker: boolean, json: boolean }}
+ */
+export function parseArgs(argv) {
+  // `--help` / `-h` and `--scope <value>` require diagnose-specific error
+  // semantics ('HELP' sentinel for validateDiagnoseArgs; "requires a
+  // value" message for missing value). Pre-scan for those before
+  // delegating the rest to the shared parser.
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') throw new Error('HELP');
+    if (a === '--scope') {
+      const next = argv[i + 1];
+      if (!next || next.startsWith('--')) {
+        throw new Error('--scope requires a value');
+      }
+      // Skip the value token so the shared parser doesn't see a stray
+      // positional, but leave it in `argv` for parseStandardCliArgs to
+      // consume.
+      i++;
+    }
+  }
+  try {
+    const { values } = parseStandardCliArgs({
+      argv,
+      extras: {
+        scope: { type: 'string', default: DEFAULT_SCOPE },
+        'fail-on-blocker': { type: 'boolean', alias: 'failOnBlocker' },
+      },
+    });
+    return {
+      scope: values.scope,
+      failOnBlocker: values.failOnBlocker,
+      json: values.json,
+    };
+  } catch (err) {
+    if (err && err.code === 'UNKNOWN_FLAG') {
+      // Preserve the legacy `unknown argument: --foo` phrasing so
+      // operator-visible error text stays stable.
+      throw new Error(`unknown argument: --${err.flag}`);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Render a list of findings as a fixed-width plain-text table. The column
+ * order is the same one the README documents and the tests pin:
+ * `id`, `severity`, `scope`, `summary`, `fix command`.
+ *
+ * An empty findings list renders as a single-line `(no findings)` marker
+ * underneath the column header, so the output shape is stable across the
+ * clean-state and dirty-state cases — operators see the same columns
+ * either way.
+ *
+ * @param {Array<import('./lib/checks/index.js').Finding>} findings
+ * @returns {string}
+ */
+export function renderTable(findings) {
+  const headers = ['id', 'severity', 'scope', 'summary', 'fix command'];
+  const rows = findings.map((f) => [
+    String(f.id ?? ''),
+    String(f.severity ?? ''),
+    String(f.scope ?? ''),
+    String(f.summary ?? ''),
+    String(f.fixCommand ?? ''),
+  ]);
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => r[i].length)),
+  );
+  const formatRow = (cells) =>
+    cells.map((c, i) => c.padEnd(widths[i])).join('  ');
+  const lines = [formatRow(headers)];
+  lines.push(widths.map((w) => '-'.repeat(w)).join('  '));
+  if (rows.length === 0) {
+    lines.push('(no findings)');
+  } else {
+    for (const r of rows) lines.push(formatRow(r));
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Programmatic entry point. Exported so tests can call it directly and
+ * inspect the return shape without spawning a subprocess.
+ *
+ * @param {object} [opts]
+ * @param {string[]} [opts.argv]   Defaults to `process.argv.slice(2)`.
+ * @param {string} [opts.cwd]      Defaults to `process.cwd()`.
+ * @param {(line: string) => void} [opts.stdout]
+ *   Defaults to a `process.stdout.write` wrapper that appends a newline.
+ * @param {Array<import('./lib/checks/index.js').Check>} [opts.registry]
+ *   Optional pre-loaded registry — tests pass fixture checks. When omitted
+ *   the runner discovers checks from the default `lib/checks/` directory.
+ * @param {string} [opts.dir]      Override the discovery dir for the
+ *   default registry path. Forwarded to `loadRegistry()`.
+ * @returns {Promise<{ exitCode: number, findings: object[], scope: string }>}
+ */
+export async function runDiagnose({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = (line) => process.stdout.write(`${line}\n`),
+  registry,
+  dir,
+} = {}) {
+  const { scope, failOnBlocker, json } = parseArgs(argv);
+  // `all` is an alias for "every scope" — the underlying runner treats an
+  // undefined scope the same way. Mapping it here keeps the CLI surface
+  // honest (operators reading --help see the word, not a JS quirk).
+  const runnerScope = scope === 'all' ? undefined : scope;
+  // assembleState's scope projection is keyed by the scope name. If the
+  // operator passes an unknown scope the state assembler falls back to an
+  // empty key list, which is fine — checks that needed env/git state will
+  // simply report missing. We pass `diagnose` as a sensible default for
+  // the `all` case so the broad-surface checks have their state available.
+  const stateScope = runnerScope ?? DEFAULT_SCOPE;
+  const state = assembleState({ scope: stateScope, cwd });
+  const { findings } = await runChecks({
+    scope: runnerScope,
+    autoFix: false,
+    state,
+    registry,
+    dir,
+  });
+  const hasBlocker = findings.some((f) => f.severity === 'blocker');
+  const exitCode = failOnBlocker && hasBlocker ? 2 : 0;
+  if (json) {
+    stdout(JSON.stringify({ scope, findings }));
+  } else {
+    stdout(renderTable(findings));
+  }
+  return { exitCode, findings, scope };
+}
+
+/**
+ * Classify a caught error from `runDiagnose` into a side-effect-free
+ * response envelope. Returns one of:
+ *
+ *   - `{ kind: 'help', text }`  — user passed `--help` / `-h`.
+ *   - `{ kind: 'error', text, exitCode }` — every other thrown shape.
+ *
+ * Extracted from `main` so the CLI's terminal branch (which `main`
+ * exercises) stays straight-line and so the help-vs-error guard cascade
+ * is testable without spawning the CLI or stubbing `process.exit`. The
+ * caller owns the actual stdout/stderr write and exit.
+ *
+ * @param {unknown} err
+ * @returns {{kind: 'help', text: string} | {kind: 'error', text: string, exitCode: number}}
+ */
+export function validateDiagnoseArgs(err) {
+  if (err && err.message === 'HELP') {
+    return {
+      kind: 'help',
+      text: [
+        'Usage: diagnose [--scope <scope>] [--fail-on-blocker] [--json]',
+        '',
+        'Options:',
+        '  --scope <s>         Filter checks by scope (default: diagnose).',
+        '                      Use `all` to run every registered check.',
+        '  --fail-on-blocker   Exit 2 when at least one finding is a blocker.',
+        '  --json              Emit findings as a single line of JSON.',
+        '',
+      ].join('\n'),
+    };
+  }
+  const message = err?.message ? err.message : String(err);
+  return { kind: 'error', text: `[diagnose] ${message}\n`, exitCode: 1 };
+}
+
+async function main() {
+  try {
+    const { exitCode } = await runDiagnose();
+    if (exitCode !== 0) process.exit(exitCode);
+    return;
+  } catch (err) {
+    const response = validateDiagnoseArgs(err);
+    if (response.kind === 'help') {
+      process.stdout.write(response.text);
+      return;
+    }
+    process.stderr.write(response.text);
+    process.exit(response.exitCode);
+  }
+}
+
+runAsCli(import.meta.url, main, { source: 'diagnose' });

package/.agents/scripts/dispatcher.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * dispatcher.js — CLI Entry Point for the Dispatch Engine
+ *
+ * Thin wrapper around the dispatcher SDK. Parses CLI arguments,
+ * delegates core logic to `lib/orchestration/dispatch-engine.js`, then
+ * handles file I/O and console output.
+ *
+ * Usage:
+ *   node dispatcher.js <ticketId> [--dry-run]
+ *
+ * The script auto-detects whether the ticket is an Epic or Story
+ * and routes to the appropriate execution mode.
+ *
+ * Successor to the retired mandrel MCP tools. See ADR 20260424-702a in docs/decisions.md for the migration table.
+ *
+ * @see .agents/schemas/dispatch-manifest.json
+ */
+
+import { runAsCli } from './lib/cli-utils.js';
+import {
+  dispatch,
+  resolveAndDispatch,
+} from './lib/orchestration/dispatch-engine.js';
+
+// Re-export SDK functions so that direct consumers of dispatcher.js
+// (tests, CI scripts) continue to work without modification.
+export { dispatch, resolveAndDispatch };
+
+// ---------------------------------------------------------------------------
+// Presentation helpers (CLI-only — not part of the SDK)
+// ---------------------------------------------------------------------------
+
+import { parseSprintArgs } from './lib/cli-args.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import {
+  fromSpec,
+  persistManifest,
+  postManifestEpicComment,
+  postParkedFollowOnsComment,
+  printStoryDispatchTable,
+} from './lib/presentation/manifest-renderer.js';
+import { createProvider } from './lib/provider-factory.js';
+import { loadSpec, loadState } from './lib/spec/index.js';
+
+/**
+ * Best-effort: load the structural spec + state for `epicId` and render
+ * the dispatch manifest Markdown via `fromSpec`. Returns `null` when the
+ * spec is absent or any loader step throws (parse/validation/io errors
+ * downgrade to fallback so the pre-spec dispatcher path keeps working
+ * untouched). Story #1501 — preserves `fromManifest` behaviour for
+ * non-spec callers.
+ *
+ * The loaders are injectable so tests can drive the spec-present /
+ * spec-absent branches without writing to the real `.agents/epics/`
+ * directory.
+ *
+ * @param {object} manifest — the dispatch manifest already built by `resolveAndDispatch`.
+ * @param {{
+ *   loadSpec?: typeof loadSpec,
+ *   loadState?: typeof loadState,
+ *   fromSpec?: typeof fromSpec,
+ *   loaderOpts?: object,
+ * }} [deps]
+ * @returns {string|null} pre-rendered Markdown, or null on any failure.
+ */
+/**
+ * Overlay live Story `status` labels from the just-built manifest onto the
+ * loaded state mapping. The spec-aware renderer (`buildManifestFromSpec`)
+ * looks up each Story's status via `state.mapping[slug].lastObservedAgentState`;
+ * that field is only refreshed by the structural reconciler, so during
+ * `/epic-deliver` execution it stays `null` and every Story renders as ⬜
+ * pending even after the Story merges. The wave-runner replaced the
+ * dispatcher-per-wave refresh loop and the local state.json never sees
+ * the progress signal.
+ *
+ * Under the 3-tier hierarchy (Epic #3163) the runtime manifest's wave
+ * records carry `stories[]` (each with the live `storyId` + `status` from
+ * `fetchEpicContext`'s GH query), not the retired `tasks[]` shape. The
+ * overlay walks `manifest.waves[].stories[]` and copies each Story's
+ * status onto the slug that matches its `storyId` (issueNumber). Pure;
+ * returns the mutated state. Safe on null/undefined.
+ *
+ * @param {object|null|undefined} state
+ * @param {object|null|undefined} manifest
+ * @returns {object|null|undefined}
+ */
+export function overlayLiveTaskStateFromManifest(state, manifest) {
+  if (!state?.mapping || !manifest?.waves) return state;
+  const issueNumberToSlug = new Map();
+  for (const [slug, entry] of Object.entries(state.mapping)) {
+    if (entry && typeof entry.issueNumber === 'number') {
+      issueNumberToSlug.set(entry.issueNumber, slug);
+    }
+  }
+  for (const wave of manifest.waves) {
+    if (!Array.isArray(wave?.stories)) continue;
+    for (const story of wave.stories) {
+      const slug = issueNumberToSlug.get(story?.storyId);
+      if (!slug) continue;
+      if (
+        typeof story.status === 'string' &&
+        story.status.startsWith('agent::')
+      ) {
+        state.mapping[slug].lastObservedAgentState = story.status;
+      }
+    }
+  }
+  return state;
+}
+
+export function tryRenderFromSpec(manifest, deps = {}) {
+  const epicId = manifest?.epicId;
+  if (!epicId || manifest.type === 'story-execution') return null;
+  const loadSpecFn = deps.loadSpec ?? loadSpec;
+  const loadStateFn = deps.loadState ?? loadState;
+  const fromSpecFn = deps.fromSpec ?? fromSpec;
+  const overlayFn =
+    deps.overlayLiveTaskState ?? overlayLiveTaskStateFromManifest;
+  const loaderOpts = deps.loaderOpts ?? {};
+  try {
+    const spec = loadSpecFn(epicId, loaderOpts);
+    const state = loadStateFn(epicId, loaderOpts);
+    const overlayedState = overlayFn(state, manifest);
+    return fromSpecFn(spec, {
+      state: overlayedState,
+      generatedAt: manifest.generatedAt,
+      executor: manifest.executor,
+      dryRun: manifest.dryRun,
+      agentTelemetry: manifest.agentTelemetry,
+    });
+  } catch (err) {
+    /* node:coverage ignore next */
+    Logger.debug?.(
+      `[Dispatcher] spec-aware render unavailable for Epic #${epicId} (${err?.name ?? 'Error'}: ${err?.message ?? 'unknown'}); falling back to fromManifest`,
+    );
+    return null;
+  }
+}
+/**
+ * High-level orchestrator that resolves the execution strategy, generates the manifest,
+ * persists the files to temp, and outputs summaries.
+ *
+ * @param {number} ticketId
+ * @param {boolean} [dryRun]
+ * @param {{ provider?: object }} [opts] - Optional overrides. `provider`
+ *   lets callers pass a provider whose per-instance ticket cache is already
+ *   primed, so dashboard regeneration issues zero extra REST calls.
+ */
+/* node:coverage ignore next 8 */
+function persistAndAnnounceMarkdown(manifest) {
+  const specMarkdown = tryRenderFromSpec(manifest);
+  if (specMarkdown !== null) {
+    Logger.info(
+      `[Dispatcher] 📐 Rendering Markdown via fromSpec (spec found for Epic #${manifest.epicId})`,
+    );
+  }
+  persistManifest(manifest, specMarkdown ? { markdown: specMarkdown } : {});
+}
+
+/* node:coverage ignore next 13 */
+async function postManifestCommentSafely(manifest, provider) {
+  try {
+    const result = await postManifestEpicComment(manifest, provider);
+    if (result.posted) {
+      Logger.info(
+        `[Dispatcher] 💬 Dispatch manifest comment posted on Epic #${manifest.epicId}`,
+      );
+    }
+  } catch (err) {
+    /* node:coverage ignore next */
+    Logger.warn(
+      `[Dispatcher] Non-fatal: could not post manifest comment — ${err.message}`,
+    );
+  }
+}
+
+/* node:coverage ignore next 16 */
+async function postParkedCommentSafely(manifest, provider) {
+  try {
+    const parkedResult = await postParkedFollowOnsComment(manifest, provider);
+    if (!parkedResult.posted) return;
+    const hasExtras = parkedResult.recuts > 0 || parkedResult.parked > 0;
+    Logger.info(
+      hasExtras
+        ? `[Dispatcher] 🪝 Parked follow-ons comment posted on Epic #${manifest.epicId} (${parkedResult.recuts} recut, ${parkedResult.parked} parked)`
+        : `[Dispatcher] 🪝 No out-of-manifest Stories detected on Epic #${manifest.epicId}`,
+    );
+  } catch (err) {
+    /* node:coverage ignore next */
+    Logger.warn(
+      `[Dispatcher] Non-fatal: could not post parked-follow-ons comment — ${err.message}`,
+    );
+  }
+}
+
+/* node:coverage ignore next 6 */
+async function maybePostEpicComments(manifest, resolveProvider) {
+  if (manifest.type === 'story-execution' || !manifest.epicId) return;
+  const provider = resolveProvider();
+  await postManifestCommentSafely(manifest, provider);
+  await postParkedCommentSafely(manifest, provider);
+}
+
+/* node:coverage ignore next 18 */
+function logStoryManifestPaths(manifest) {
+  const stories = manifest.stories ?? [];
+  const eid = stories.find((s) => s?.epicId)?.epicId;
+  if (eid && stories.length === 1) {
+    const sid = stories[0].storyId;
+    Logger.info(
+      `\n[Dispatcher] ✅ Story manifest: temp/epic-${eid}/stories/story-${sid}/manifest.json`,
+    );
+    Logger.info(
+      `[Dispatcher] 📄 Markdown: temp/epic-${eid}/stories/story-${sid}/manifest.md\n`,
+    );
+    return;
+  }
+  const key = stories.map((s) => s.storyId).join('-');
+  Logger.info(
+    `\n[Dispatcher] ✅ Story manifest: temp/story-manifest-${key}.json`,
+  );
+  Logger.info(`[Dispatcher] 📄 Markdown: temp/story-manifest-${key}.md\n`);
+}
+
+/* node:coverage ignore next 10 */
+function logEpicManifestSummary(manifest) {
+  const epicId = manifest.epicId;
+  Logger.info(`\n[Dispatcher] ✅ Manifest: temp/epic-${epicId}/manifest.json`);
+  Logger.info(`[Dispatcher] 📄 Markdown: temp/epic-${epicId}/manifest.md`);
+  Logger.info(
+    `[Dispatcher] Progress: ${manifest.summary.doneStories}/${manifest.summary.totalStories} stories done (${manifest.summary.progressPercent}%)`,
+  );
+  Logger.info(`[Dispatcher] Dispatched: ${manifest.summary.dispatched}`);
+  printStoryDispatchTable(manifest.storyManifest);
+}
+
+/* node:coverage ignore next 7 */
+function logManifestSummary(manifest) {
+  if (manifest.type === 'story-execution') {
+    logStoryManifestPaths(manifest);
+    return;
+  }
+  logEpicManifestSummary(manifest);
+}
+
+export async function generateAndSaveManifest(
+  ticketId,
+  dryRun = false,
+  opts = {},
+) {
+  const manifest = await resolveAndDispatch({
+    ticketId,
+    dryRun,
+    provider: opts.provider,
+  });
+  persistAndAnnounceMarkdown(manifest);
+  await maybePostEpicComments(
+    manifest,
+    () => opts.provider ?? createProvider(resolveConfig()),
+  );
+  logManifestSummary(manifest);
+  return manifest;
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+/* node:coverage ignore next */
+/* node:coverage ignore next */
+async function main() {
+  const { ticketId, dryRun } = parseSprintArgs();
+
+  if (!ticketId) {
+    Logger.error(
+      '[Dispatcher] Error: No valid Issue ID provided.\n' +
+        'Usage: node dispatcher.js <ticketId> [--dry-run]',
+    );
+    process.exit(1);
+  }
+
+  await generateAndSaveManifest(ticketId, dryRun);
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'Dispatcher',
+  onError: (err) => {
+    Logger.error('[Dispatcher] Fatal error:', err.message);
+    process.exit(1);
+  },
+});

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

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/**
+ * .agents/scripts/drain-pending-cleanup.js
+ *
+ * Force-drain helper: reads `.worktrees/.pending-cleanup.json`, retries
+ * Stage 1 cleanup for every entry, and (on Windows, by default) escalates
+ * any still-stuck entries by enumerating the processes holding handles
+ * inside the worktree path and terminating them.
+ *
+ * Invoked by `/epic-deliver`, `/epic-plan-spec` / `/epic-plan-decompose`
+ * (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:
+ *
+ *   node .agents/scripts/drain-pending-cleanup.js              # full drain + escalate
+ *   node .agents/scripts/drain-pending-cleanup.js --no-escalate  # passive drain only
+ *   node .agents/scripts/drain-pending-cleanup.js --dry-run      # report only
+ *
+ * Exit code: 0 when manifest is empty after the drain, 0 with warnings
+ * if entries remain (operator inspection useful), 1 only on hard error
+ * (config load, fatal exception).
+ */
+
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
+import * as gitUtils from './lib/git-utils.js';
+import { Logger } from './lib/Logger.js';
+import {
+  findHoldersInPath,
+  forceDrainPendingCleanup,
+} from './lib/worktree/lifecycle/force-drain.js';
+import { readManifest } from './lib/worktree/lifecycle/pending-cleanup.js';
+
+const progress = Logger.createProgress('drain-pending-cleanup', {
+  stderr: false,
+});
+
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      escalate: { type: 'boolean', default: true },
+      'dry-run': { type: 'boolean', default: false },
+      'worktree-root': { type: 'string' },
+    },
+    strict: false,
+  });
+
+  const config = resolveConfig();
+  const wtConfig = config.delivery?.worktreeIsolation;
+  const worktreeRoot = path.resolve(
+    PROJECT_ROOT,
+    values['worktree-root'] ?? wtConfig?.root ?? '.worktrees',
+  );
+
+  const before = readManifest(worktreeRoot);
+  if (before.length === 0) {
+    progress('SCAN', 'pending-cleanup manifest is empty — nothing to drain.');
+    return;
+  }
+
+  progress(
+    'SCAN',
+    `pending-cleanup manifest has ${before.length} entry(ies): ${before
+      .map((e) => `story-${e.storyId}(attempts=${e.attempts ?? 0})`)
+      .join(', ')}`,
+  );
+
+  if (values['dry-run']) {
+    for (const entry of before) {
+      const holders = findHoldersInPath(entry.path);
+      progress(
+        'DRY-RUN',
+        `story-${entry.storyId} path=${entry.path} holders=${holders.length}` +
+          (holders.length > 0
+            ? ` (${holders.map((h) => `pid=${h.pid}/${h.name}`).join(', ')})`
+            : ''),
+      );
+    }
+    return;
+  }
+
+  const result = await forceDrainPendingCleanup({
+    repoRoot: PROJECT_ROOT,
+    worktreeRoot,
+    git: gitUtils,
+    escalate: values.escalate,
+    logger: {
+      info: (m) => progress('DRAIN', m),
+      warn: (m) => progress('DRAIN', `⚠️ ${m}`),
+      error: (m) => Logger.error(`[drain-pending-cleanup] ${m}`),
+    },
+  });
+
+  if (result.drained.length > 0) {
+    progress(
+      'DRAIN',
+      `✅ drained ${result.drained.length} entry(ies): ${result.drained
+        .map((id) => `story-${id}`)
+        .join(', ')}`,
+    );
+  }
+  if (result.escalated.length > 0) {
+    const summary = result.escalated
+      .map((id) => `story-${id}=[${(result.killedPids[id] ?? []).join(',')}]`)
+      .join(', ');
+    progress('ESCALATE', `terminated holders: ${summary}`);
+  }
+  if (result.noHolders && result.noHolders.length > 0) {
+    progress(
+      'ESCALATE',
+      `⚠️ no user-mode holders for: ${result.noHolders
+        .map((id) => `story-${id}`)
+        .join(
+          ', ',
+        )} — kernel-held lock (Search indexer / AV); will retry next sweep`,
+    );
+  }
+  if (result.persistent.length > 0) {
+    progress(
+      'PERSIST',
+      `⚠️ persistent-lock remains on: ${result.persistent
+        .map((id) => `story-${id}`)
+        .join(', ')} — entries retained in ledger for next sweep`,
+    );
+  }
+  if (result.stillPending.length > 0) {
+    progress(
+      'STILL-PENDING',
+      `⚠️ still-pending (below threshold): ${result.stillPending
+        .map((id) => `story-${id}`)
+        .join(', ')}`,
+    );
+  }
+
+  const after = readManifest(worktreeRoot);
+  progress(
+    'DONE',
+    `pending-cleanup manifest now has ${after.length} entry(ies). ` +
+      `Drained=${result.drained.length}, escalated=${result.escalated.length}, persistent=${result.persistent.length}.`,
+  );
+}
+
+runAsCli(import.meta.url, main, { source: 'drain-pending-cleanup' });