@ikunin/sprintpilot 1.0.5 → 2.0.5

package/_Sprintpilot/scripts/submodule-lock.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+// submodule-lock.js — serialize concurrent `git submodule update` calls
+// across worktrees so they don't stomp each other's index.lock.
+//
+// Usage:
+//   submodule-lock.js acquire --submodule <name> [--project-root <path>]
+//   submodule-lock.js release --submodule <name> [--project-root <path>]
+//   submodule-lock.js check   --submodule <name> [--project-root <path>]
+//
+// Lock path:
+//   <project-root>/.sprintpilot/submodule-locks/<slug>.lock
+//   (outside .git/ so git doesn't warn about foreign files)
+//
+// Thin wrapper over lock.js --file <lockPath>. Submodule names are
+// slugified for filesystem safety (only [a-z0-9-] survive).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { parseArgs } = require('../lib/runtime/args');
+const log = require('../lib/runtime/log');
+
+const VALID_ACTIONS = ['acquire', 'release', 'check'];
+const LOCK_SCRIPT = path.join(__dirname, 'lock.js');
+
+function help() {
+  log.out(
+    [
+      'Usage:',
+      '  submodule-lock.js acquire --submodule <name> [--project-root <path>]',
+      '  submodule-lock.js release --submodule <name>',
+      '  submodule-lock.js check   --submodule <name>',
+    ].join('\n'),
+  );
+}
+
+function slugify(name) {
+  return String(name)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64);
+}
+
+function lockPathFor(projectRoot, submodule) {
+  const slug = slugify(submodule);
+  if (!slug) throw new Error(`invalid submodule name: '${submodule}' slugifies to empty`);
+  return path.join(projectRoot, '.sprintpilot', 'submodule-locks', `${slug}.lock`);
+}
+
+function ensureDirFor(filePath) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function runLockScript(action, lockFile) {
+  const res = spawnSync(
+    process.execPath,
+    [LOCK_SCRIPT, action, '--file', lockFile, '--stale-minutes', '30'],
+    { encoding: 'utf8' },
+  );
+  return {
+    status: res.status === null ? 1 : res.status,
+    stdout: (res.stdout || '').trim(),
+    stderr: (res.stderr || '').trim(),
+  };
+}
+
+function acquire(projectRoot, submodule) {
+  const lockFile = lockPathFor(projectRoot, submodule);
+  ensureDirFor(lockFile);
+  return runLockScript('acquire', lockFile);
+}
+
+function release(projectRoot, submodule) {
+  const lockFile = lockPathFor(projectRoot, submodule);
+  return runLockScript('release', lockFile);
+}
+
+function check(projectRoot, submodule) {
+  const lockFile = lockPathFor(projectRoot, submodule);
+  return runLockScript('check', lockFile);
+}
+
+function main() {
+  const { opts, positional } = parseArgs(process.argv.slice(2));
+  if (opts.help || positional.length === 0) {
+    help();
+    process.exit(opts.help ? 0 : 1);
+  }
+  const action = positional[0];
+  if (!VALID_ACTIONS.includes(action)) {
+    log.error(`unknown action '${action}'. Valid: ${VALID_ACTIONS.join(', ')}`);
+    process.exit(1);
+  }
+  const submodule = opts.submodule;
+  if (!submodule) {
+    log.error('--submodule is required');
+    process.exit(1);
+  }
+  const projectRoot = opts['project-root'] || process.cwd();
+
+  let res;
+  try {
+    if (action === 'acquire') res = acquire(projectRoot, submodule);
+    else if (action === 'release') res = release(projectRoot, submodule);
+    else res = check(projectRoot, submodule);
+  } catch (e) {
+    log.error(e.message);
+    process.exit(1);
+  }
+  if (res.stdout) process.stdout.write(`${res.stdout}\n`);
+  if (res.stderr) process.stderr.write(`${res.stderr}\n`);
+  process.exit(res.status);
+}
+
+module.exports = {
+  VALID_ACTIONS,
+  slugify,
+  lockPathFor,
+  acquire,
+  release,
+  check,
+};
+
+if (require.main === module) {
+  main();
+}

package/_Sprintpilot/scripts/summarize-timings.js

@@ -0,0 +1,362 @@
+#!/usr/bin/env node
+
+// summarize-timings.js — merge .timings/<story>.jsonl shards into a report.
+//
+// Usage:
+//   summarize-timings.js [--project-root <path>] [--format text|json|md]
+//                        [--session-only] [--quiet]
+//
+// Behavior:
+//   Reads every .jsonl file under _bmad-output/implementation-artifacts/
+//   .timings/. Pairs start/end events by (story, phase) in LIFO order.
+//   Computes:
+//     - Wall-clock per story (min-start to max-end)
+//     - Per-phase aggregates: count, sum_ms, p50, p95, max
+//     - Hotspots: phases whose sum_ms consumes > 5% of total paired time
+//
+// Output:
+//   --format text (default) → stdout, human-readable table
+//   --format json           → stdout, JSON dump
+//   --format md             → markdown; also written to an artifact:
+//       default:          .timings/summary-<YYYY-MM-DD>.md
+//       --session-only:   .timings/summary-session-<ISO-ts>.md
+//
+// Hotspot threshold is fixed at 5% per the PR 2 contract.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { parseArgs } = require('../lib/runtime/args');
+const log = require('../lib/runtime/log');
+
+const HOTSPOT_THRESHOLD = 0.05;
+
+function help() {
+  log.out(
+    [
+      'Usage:',
+      '  summarize-timings.js [--project-root <path>] [--format text|json|md]',
+      '                       [--session-only] [--quiet]',
+      '',
+      'Defaults: --format text, reads cwd.',
+      '  --session-only   Writes artifact as summary-session-<ts>.md.',
+      '  --quiet          Suppresses stdout for md format (still writes artifact).',
+    ].join('\n'),
+  );
+}
+
+function timingsDir(projectRoot) {
+  return path.join(projectRoot, '_bmad-output', 'implementation-artifacts', '.timings');
+}
+
+function readShards(projectRoot) {
+  const dir = timingsDir(projectRoot);
+  if (!fs.existsSync(dir)) return [];
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+  const events = [];
+  for (const f of files) {
+    const full = path.join(dir, f);
+    const raw = fs.readFileSync(full, 'utf8');
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let obj;
+      try {
+        obj = JSON.parse(trimmed);
+      } catch {
+        continue; // skip corrupt lines rather than abort the summary
+      }
+      if (!obj || typeof obj !== 'object') continue;
+      if (!obj.event || !obj.story || !obj.phase || !obj.ts) continue;
+      const ms = Date.parse(obj.ts);
+      if (Number.isNaN(ms)) continue;
+      events.push({ ...obj, _ms: ms });
+    }
+  }
+  // Stable sort by timestamp so pairing is deterministic.
+  events.sort((a, b) => a._ms - b._ms);
+  return events;
+}
+
+function pairEvents(events) {
+  // Returns { stories: { [story]: { first, last, phases: { [phase]: number[] } } },
+  //           phaseAgg: { [phase]: number[] },
+  //           onceCount: { [phase]: number },
+  //           orphans: [{story, phase, event, ts}] }
+  const stories = {};
+  const phaseAgg = {};
+  const onceCount = {};
+  const openByStoryPhase = {}; // key = story::phase → stack of start ms
+
+  const ensureStory = (s) => {
+    if (!stories[s]) stories[s] = { first: null, last: null, phases: {} };
+    return stories[s];
+  };
+
+  for (const ev of events) {
+    const s = ensureStory(ev.story);
+    if (s.first === null || ev._ms < s.first) s.first = ev._ms;
+    if (s.last === null || ev._ms > s.last) s.last = ev._ms;
+
+    if (ev.event === 'once') {
+      onceCount[ev.phase] = (onceCount[ev.phase] || 0) + 1;
+      continue;
+    }
+    const key = `${ev.story}::${ev.phase}`;
+    if (ev.event === 'start') {
+      if (!openByStoryPhase[key]) openByStoryPhase[key] = [];
+      openByStoryPhase[key].push(ev._ms);
+      continue;
+    }
+    if (ev.event === 'end') {
+      const stack = openByStoryPhase[key];
+      if (!stack || stack.length === 0) continue; // orphan end — skip
+      const startMs = stack.pop();
+      const duration = ev._ms - startMs;
+      if (duration < 0) continue;
+      if (!s.phases[ev.phase]) s.phases[ev.phase] = [];
+      s.phases[ev.phase].push(duration);
+      if (!phaseAgg[ev.phase]) phaseAgg[ev.phase] = [];
+      phaseAgg[ev.phase].push(duration);
+    }
+  }
+
+  const orphans = [];
+  for (const key of Object.keys(openByStoryPhase)) {
+    const [story, phase] = key.split('::');
+    for (const startMs of openByStoryPhase[key]) {
+      orphans.push({ story, phase, event: 'start-without-end', ts: new Date(startMs).toISOString() });
+    }
+  }
+
+  return { stories, phaseAgg, onceCount, orphans };
+}
+
+function percentile(sorted, p) {
+  if (sorted.length === 0) return 0;
+  if (sorted.length === 1) return sorted[0];
+  // Nearest-rank; fine for our small N.
+  const idx = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+  return sorted[Math.max(0, idx)];
+}
+
+function aggregate(paired) {
+  const phases = Object.keys(paired.phaseAgg).sort();
+  const rows = phases.map((phase) => {
+    const durations = [...paired.phaseAgg[phase]].sort((a, b) => a - b);
+    const sum = durations.reduce((acc, v) => acc + v, 0);
+    return {
+      phase,
+      count: durations.length,
+      sum_ms: sum,
+      p50_ms: percentile(durations, 50),
+      p95_ms: percentile(durations, 95),
+      max_ms: durations[durations.length - 1],
+    };
+  });
+  const totalPaired = rows.reduce((acc, r) => acc + r.sum_ms, 0);
+  const withPct = rows.map((r) => ({
+    ...r,
+    pct_of_total: totalPaired > 0 ? r.sum_ms / totalPaired : 0,
+  }));
+  withPct.sort((a, b) => b.sum_ms - a.sum_ms);
+  const hotspots = withPct.filter((r) => r.pct_of_total > HOTSPOT_THRESHOLD);
+
+  const stories = Object.keys(paired.stories).sort().map((key) => {
+    const s = paired.stories[key];
+    const wall_ms = s.first !== null && s.last !== null ? s.last - s.first : 0;
+    const phaseSum = Object.values(s.phases)
+      .flat()
+      .reduce((acc, v) => acc + v, 0);
+    return { story: key, wall_ms, phase_sum_ms: phaseSum, phase_count: Object.keys(s.phases).length };
+  });
+
+  return {
+    total_paired_ms: totalPaired,
+    phases: withPct,
+    hotspots,
+    stories,
+    once_markers: paired.onceCount,
+    orphans: paired.orphans,
+  };
+}
+
+function fmtMs(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${(ms / 60_000).toFixed(1)}m`;
+}
+
+function fmtPct(p) {
+  return `${(p * 100).toFixed(1)}%`;
+}
+
+function renderText(report) {
+  const lines = [];
+  lines.push('Sprintpilot phase-timing summary');
+  lines.push(`Total paired phase time: ${fmtMs(report.total_paired_ms)}`);
+  lines.push('');
+  lines.push('Per-story wall-clock:');
+  if (report.stories.length === 0) {
+    lines.push('  (no data)');
+  } else {
+    for (const s of report.stories) {
+      lines.push(
+        `  ${s.story}  wall=${fmtMs(s.wall_ms)}  phase-sum=${fmtMs(s.phase_sum_ms)}  phases=${s.phase_count}`,
+      );
+    }
+  }
+  lines.push('');
+  lines.push('Phase aggregates (sorted by sum):');
+  if (report.phases.length === 0) {
+    lines.push('  (no paired start/end events)');
+  } else {
+    lines.push('  phase                                    count    sum     p50     p95     max    %');
+    for (const r of report.phases) {
+      lines.push(
+        `  ${r.phase.padEnd(40)} ${String(r.count).padStart(5)}  ${fmtMs(r.sum_ms).padStart(6)}  ${fmtMs(r.p50_ms).padStart(6)}  ${fmtMs(r.p95_ms).padStart(6)}  ${fmtMs(r.max_ms).padStart(6)}  ${fmtPct(r.pct_of_total).padStart(6)}`,
+      );
+    }
+  }
+  lines.push('');
+  if (report.hotspots.length > 0) {
+    lines.push(`Hotspots (> ${HOTSPOT_THRESHOLD * 100}% of total):`);
+    for (const h of report.hotspots) {
+      lines.push(`  ${h.phase}  ${fmtPct(h.pct_of_total)}  ${fmtMs(h.sum_ms)}`);
+    }
+  } else {
+    lines.push('Hotspots: none above threshold');
+  }
+  if (Object.keys(report.once_markers).length > 0) {
+    lines.push('');
+    lines.push('Once markers:');
+    for (const [phase, count] of Object.entries(report.once_markers)) {
+      lines.push(`  ${phase}  ×${count}`);
+    }
+  }
+  if (report.orphans.length > 0) {
+    lines.push('');
+    lines.push(`Orphaned starts (no matching end): ${report.orphans.length}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function renderMarkdown(report) {
+  const lines = [];
+  lines.push('# Sprintpilot phase-timing summary');
+  lines.push('');
+  lines.push(`**Total paired phase time:** ${fmtMs(report.total_paired_ms)}`);
+  lines.push('');
+  lines.push('## Per-story wall-clock');
+  lines.push('');
+  if (report.stories.length === 0) {
+    lines.push('_No data._');
+  } else {
+    lines.push('| Story | Wall | Phase sum | # phases |');
+    lines.push('|---|---|---|---|');
+    for (const s of report.stories) {
+      lines.push(`| ${s.story} | ${fmtMs(s.wall_ms)} | ${fmtMs(s.phase_sum_ms)} | ${s.phase_count} |`);
+    }
+  }
+  lines.push('');
+  lines.push('## Phase aggregates');
+  lines.push('');
+  if (report.phases.length === 0) {
+    lines.push('_No paired start/end events._');
+  } else {
+    lines.push('| Phase | Count | Sum | p50 | p95 | Max | % total |');
+    lines.push('|---|---:|---:|---:|---:|---:|---:|');
+    for (const r of report.phases) {
+      lines.push(
+        `| \`${r.phase}\` | ${r.count} | ${fmtMs(r.sum_ms)} | ${fmtMs(r.p50_ms)} | ${fmtMs(r.p95_ms)} | ${fmtMs(r.max_ms)} | ${fmtPct(r.pct_of_total)} |`,
+      );
+    }
+  }
+  lines.push('');
+  lines.push(`## Hotspots (> ${HOTSPOT_THRESHOLD * 100}% of total)`);
+  lines.push('');
+  if (report.hotspots.length === 0) {
+    lines.push('_None above threshold._');
+  } else {
+    for (const h of report.hotspots) {
+      lines.push(`- \`${h.phase}\` — ${fmtPct(h.pct_of_total)} (${fmtMs(h.sum_ms)})`);
+    }
+  }
+  if (Object.keys(report.once_markers).length > 0) {
+    lines.push('');
+    lines.push('## Once markers');
+    lines.push('');
+    for (const [phase, count] of Object.entries(report.once_markers)) {
+      lines.push(`- \`${phase}\` ×${count}`);
+    }
+  }
+  if (report.orphans.length > 0) {
+    lines.push('');
+    lines.push(`_Orphaned starts (no matching end): ${report.orphans.length}_`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function artifactPath(projectRoot, sessionOnly) {
+  const dir = timingsDir(projectRoot);
+  if (sessionOnly) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(dir, `summary-session-${ts}.md`);
+  }
+  const date = new Date().toISOString().slice(0, 10);
+  return path.join(dir, `summary-${date}.md`);
+}
+
+function main() {
+  const { opts } = parseArgs(process.argv.slice(2), { booleanFlags: ['session-only', 'quiet'] });
+  if (opts.help) {
+    help();
+    process.exit(0);
+  }
+  const projectRoot = opts['project-root'] || process.cwd();
+  const format = opts.format || 'text';
+  const sessionOnly = opts['session-only'] === true;
+  const quiet = opts.quiet === true;
+
+  const events = readShards(projectRoot);
+  const paired = pairEvents(events);
+  const report = aggregate(paired);
+
+  if (format === 'json') {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return;
+  }
+  if (format === 'md') {
+    const body = renderMarkdown(report);
+    const out = artifactPath(projectRoot, sessionOnly);
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    fs.writeFileSync(out, body);
+    if (!quiet) process.stdout.write(`${body}\nWrote: ${out}\n`);
+    else process.stdout.write(`${out}\n`);
+    return;
+  }
+  if (format === 'text') {
+    process.stdout.write(renderText(report));
+    return;
+  }
+  log.error(`unknown --format '${format}'. Valid: text, json, md`);
+  process.exit(1);
+}
+
+module.exports = {
+  HOTSPOT_THRESHOLD,
+  timingsDir,
+  readShards,
+  pairEvents,
+  aggregate,
+  percentile,
+  renderText,
+  renderMarkdown,
+  artifactPath,
+  fmtMs,
+  fmtPct,
+};
+
+if (require.main === module) {
+  main();
+}

package/_Sprintpilot/scripts/sync-status.js

@@ -120,6 +120,17 @@ function main() {
     worktreeCleaned = v === true || String(v).toLowerCase() === 'true' ? 'true' : 'false';
   }
 
+  // Epic-granularity metadata (PR 5). When the autopilot runs with
+  // git.granularity=epic, every story in the epic shares one branch.
+  // We record epic_id + granularity on every block so downstream code
+  // can "find the branch for this epic" by scanning the file.
+  const epicId = opts['epic-id'];
+  const granularity = opts.granularity || 'story';
+  if (!['story', 'epic'].includes(granularity)) {
+    log.error(`invalid --granularity '${granularity}': must be story|epic`);
+    process.exit(1);
+  }
+
   const fields = [
     { key: 'branch', value: branch },
     { key: 'worktree', value: worktree },
@@ -130,6 +141,8 @@ function main() {
     { key: 'merge_status', value: mergeStatus },
     { key: 'pr_url', value: prUrl },
     { key: 'worktree_cleaned', value: worktreeCleaned, raw: true },
+    { key: 'epic_id', value: epicId },
+    { key: 'granularity', value: granularity === 'story' ? undefined : granularity },
   ];
 
   const block = buildBlock(story, fields);

package/_Sprintpilot/scripts/with-retry.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+
+// with-retry.js — run a command with jittered-backoff retries on
+// transient git ref-lock failures.
+//
+// Usage:
+//   with-retry.js -- <command> [args...]
+//   with-retry.js --attempts 3 --min-ms 500 --max-ms 2000 -- <command> [args...]
+//   with-retry.js --pattern '<regex>' -- <command> [args...]
+//
+// Retry trigger:
+//   stderr is scanned for the default ref-lock regex (case-insensitive):
+//     cannot lock ref|Unable to create.*\.lock|Reference already exists|failed to lock|lock.ref
+//   Custom regex via --pattern. Any command that matches the pattern AND
+//   exits non-zero is retried up to --attempts times with jittered backoff
+//   in [--min-ms, --max-ms]. All other non-zero exits are returned as-is
+//   (no blind retry — safeguards against hiding real failures).
+//
+// Exit code: the last attempt's exit code. stdout + stderr are forwarded
+// verbatim on each attempt.
+
+const { spawnSync } = require('node:child_process');
+
+const { parseArgs } = require('../lib/runtime/args');
+const log = require('../lib/runtime/log');
+
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_MIN_MS = 500;
+const DEFAULT_MAX_MS = 2000;
+const DEFAULT_REF_LOCK_PATTERN = /cannot lock ref|Unable to create.*\.lock|Reference already exists|failed to lock|lock\.ref/i;
+
+function help() {
+  log.out(
+    [
+      'Usage: with-retry.js [options] -- <command> [args...]',
+      '',
+      'Options:',
+      '  --attempts N       Max attempts (default 3, min 1).',
+      '  --min-ms N         Backoff lower bound (default 500).',
+      '  --max-ms N         Backoff upper bound (default 2000).',
+      '  --pattern REGEX    Override the retry-trigger regex (case-insensitive).',
+      '  --no-shell         Always use execFile semantics (implicit — no shell).',
+      '',
+      'Retries only when stderr matches the pattern AND exit code is non-zero.',
+    ].join('\n'),
+  );
+}
+
+function jitteredDelay(minMs, maxMs) {
+  const lo = Math.max(0, minMs);
+  const hi = Math.max(lo, maxMs);
+  return lo + Math.floor(Math.random() * (hi - lo + 1));
+}
+
+function sleepSync(ms) {
+  // Node's child_process lacks a portable sleep; use spawnSync to block.
+  if (ms <= 0) return;
+  spawnSync(process.execPath, ['-e', `setTimeout(()=>process.exit(0), ${ms})`], {
+    stdio: 'ignore',
+  });
+}
+
+function shouldRetry(stderr, pattern) {
+  if (!stderr) return false;
+  return pattern.test(String(stderr));
+}
+
+function runOnce(cmd, args, inherit = false) {
+  const res = spawnSync(cmd, args, {
+    stdio: inherit ? 'inherit' : 'pipe',
+    encoding: 'utf8',
+  });
+  return {
+    status: res.status,
+    signal: res.signal,
+    stdout: res.stdout || '',
+    stderr: res.stderr || '',
+    error: res.error,
+  };
+}
+
+function runWithRetry({ cmd, args, attempts = DEFAULT_ATTEMPTS, minMs = DEFAULT_MIN_MS, maxMs = DEFAULT_MAX_MS, pattern = DEFAULT_REF_LOCK_PATTERN, onAttempt = null }) {
+  const actualAttempts = Math.max(1, attempts | 0);
+  let last = null;
+  for (let i = 0; i < actualAttempts; i++) {
+    const res = runOnce(cmd, args);
+    last = res;
+    if (typeof onAttempt === 'function') onAttempt({ attempt: i + 1, ...res });
+    if (res.status === 0) return { ...res, attempts: i + 1 };
+    if (!shouldRetry(res.stderr, pattern)) return { ...res, attempts: i + 1 };
+    if (i + 1 >= actualAttempts) break;
+    sleepSync(jitteredDelay(minMs, maxMs));
+  }
+  return { ...last, attempts: actualAttempts };
+}
+
+function splitAtSeparator(argv) {
+  const idx = argv.indexOf('--');
+  if (idx === -1) return { flags: argv, cmdArgs: [] };
+  return { flags: argv.slice(0, idx), cmdArgs: argv.slice(idx + 1) };
+}
+
+function main() {
+  const { flags, cmdArgs } = splitAtSeparator(process.argv.slice(2));
+  const { opts } = parseArgs(flags);
+  if (opts.help || cmdArgs.length === 0) {
+    help();
+    process.exit(opts.help ? 0 : 1);
+  }
+  const attempts = opts.attempts !== undefined ? Number.parseInt(String(opts.attempts), 10) : DEFAULT_ATTEMPTS;
+  const minMs = opts['min-ms'] !== undefined ? Number.parseInt(String(opts['min-ms']), 10) : DEFAULT_MIN_MS;
+  const maxMs = opts['max-ms'] !== undefined ? Number.parseInt(String(opts['max-ms']), 10) : DEFAULT_MAX_MS;
+  let pattern = DEFAULT_REF_LOCK_PATTERN;
+  if (opts.pattern) {
+    try {
+      pattern = new RegExp(String(opts.pattern), 'i');
+    } catch (e) {
+      log.error(`invalid --pattern regex: ${e.message}`);
+      process.exit(1);
+    }
+  }
+  const [cmd, ...rest] = cmdArgs;
+  const res = runWithRetry({ cmd, args: rest, attempts, minMs, maxMs, pattern });
+  process.stdout.write(res.stdout);
+  process.stderr.write(res.stderr);
+  if (res.attempts > 1) {
+    process.stderr.write(`with-retry: ${res.attempts} attempts, final exit ${res.status}\n`);
+  }
+  process.exit(res.status === null ? 1 : res.status);
+}
+
+module.exports = {
+  DEFAULT_ATTEMPTS,
+  DEFAULT_MIN_MS,
+  DEFAULT_MAX_MS,
+  DEFAULT_REF_LOCK_PATTERN,
+  shouldRetry,
+  jitteredDelay,
+  runWithRetry,
+  splitAtSeparator,
+};
+
+if (require.main === module) {
+  main();
+}