bullswarm 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # bullswarm changelog
 
+## 0.9.0 — resilient dynamic workflow routing
+
+- Added cooperative `SIGTERM`/`SIGINT` handling, durable `interrupted` states,
+  dead/stale owner reconciliation, and clean resume after interruption.
+- Added capability-context filtering for model recommendations plus an explicit
+  `strategy apply --yes` approval gate and TTL-based automatic refresh.
+- Added setup-time worktree policy and strategy-autopilot choices.
+- Added per-attempt routing reasons/candidate surplus to durable events, state,
+  decision logs, and the printable workflow tree.
+- Added top-level `runs` and `--version` aliases, complete `workflow goal`
+  budget help, and correct phase/terminal display for completed runs.
+
 ## 0.8.0 — autonomous goals, model strategy, and auditable usage
 
 - Added `workflow goal` for bounded observe-plan-execute loops without an

package/README.md

@@ -31,7 +31,7 @@ npm install -g bullswarm   # or: node bin/bullswarm.js directly from a checkout
 bullswarm          # first run: interactive setup wizard
 bullswarm setup    # re-run or repair
 bullswarm pools    # meter state, pace position, quarantine status
-bullswarm strategy refresh  # discover local models and refresh tier suggestions
+bullswarm strategy refresh --apply --yes  # approve capability-aware tier autopilot
 bullswarm run --lane analyze --add-dir ~/some-repo --task-file /tmp/t.md --json
 bullswarm workflow goal "Fix the failing tests and verify the change" --cwd ~/some-repo
 bullswarm health   # re-judge saved outputs; catch gate failures
@@ -57,18 +57,25 @@ connector-declared, dated pricing/benchmark metadata with live quota surplus:
 ```bash
 bullswarm strategy refresh
 bullswarm strategy show --json
+bullswarm strategy apply --yes --refresh-hours 24
+bullswarm strategy auto status
 bullswarm strategy set-subscription command-code \
   --plan GOAT --monthly-usd 10 --included-usd 70 --quota-window monthly
 bullswarm strategy assign high --pool claude-code --model claude-opus-4-6
 bullswarm run --effort high --lane analyze --task-file /tmp/task.md --json
 ```
 
-Setup recommends an initial refresh; run `strategy refresh` whenever a CLI's
-catalog or subscription changes. Discovery commands, model argument syntax,
-pricing, and benchmark declarations remain connector-owned. Unknown license
-value, prices, and benchmarks stay `null` rather than being guessed. An
-assignment is only a preference: quarantine, exhaustion, burst gates, and
-capability checks still win.
+Interactive setup asks whether to enable strategy autopilot; non-interactive
+setup requires the explicit `setup --yes --strategy` flag. Recommendations are
+context-filtered before ranking: high requires analysis plus workflow-planning,
+medium requires build/edit capabilities, and low targets bounded chores. An
+approved policy refreshes stale discovery before later runs and re-applies the
+best eligible models on its configured interval. Disable it with
+`strategy auto off --yes`. Discovery commands, model argument syntax, pricing,
+and benchmark declarations remain connector-owned. Unknown license value,
+prices, and benchmarks stay `null` rather than being guessed. An assignment is
+only a preference: quarantine, exhaustion, burst gates, and capability checks
+still win.
 
 Every run and workflow attempt reports its selected agent/model and estimated
 usage. When a delegate does not expose counters, Bullswarm labels its UTF-8
@@ -94,8 +101,9 @@ bullswarm workflow goal \
   --cwd ~/some-repo --detach --json
 ```
 
-Bullswarm selects an eligible `workflow-planning` orchestrator by live quota
-surplus. The orchestrator observes durable evidence, proposes bounded actions,
+Bullswarm first honors an approved high-tier provider/model assignment when it
+remains eligible, otherwise it selects an eligible `workflow-planning`
+orchestrator by live quota surplus. The orchestrator observes durable evidence, proposes bounded actions,
 and decides when another expansion or verification is necessary. Bullswarm
 validates the proposal, owns agent/process selection, routes workers, and calls
 the orchestrator again until completion, cancellation, failure, approval, or a
@@ -121,7 +129,9 @@ bullswarm workflow goal --resume <shortId> --json
 `--orchestrator <pool>` exists for controlled testing; ordinary use should
 leave selection on `auto`. Hard limits can be adjusted with `--max-agents`,
 `--max-expansion-rounds`, `--max-actions`, `--max-items-per-expansion`, and
-`--max-workflow-seconds`.
+`--max-workflow-seconds`. Interactive setup also records a worktree-isolation
+preference (`agent-decides`, `off`, or `required`); Bullswarm communicates that
+policy to the orchestrator without imposing repository topology itself.
 
 ## Building a workflow from the shell
 
@@ -164,6 +174,7 @@ bullswarm workflow runs --historical       # only historical
 bullswarm workflow runs --name audit-code  # filter by workflow
 bullswarm workflow runs --limit 20         # cap the result count
 bullswarm workflow runs show <shortId>     # state + report + summary
+bullswarm runs show <shortId>              # top-level shorthand
 bullswarm workflow runs delete <shortId> --yes    # remove the run dir
 
 # Resume by shortId — runs the same logic as the full runId
@@ -197,6 +208,16 @@ bullswarm workflow approval approve --json <id>  # then resume the run
 
 Cancellation is persisted as `cancelling`, terminates an active child process,
 records its termination signal and latency evidence, then commits `cancelled`.
+`SIGTERM` and `SIGINT` use the same cooperative child termination path but
+commit a distinct resumable `interrupted` state. On every workflow command,
+active states with a dead/stale owner are automatically reconciled to
+`interrupted` instead of remaining falsely `running`.
+
+Each attempt records the phase/action, selected pool and model, effort tier,
+routing reason, all eligible candidates with quota surplus, timestamps,
+artifact paths, outcome, and reported-or-estimated token/cost/quota usage.
+`workflow tui <id>` renders this breakdown for completed runs as well as live
+ones; `workflow tui --json <id>` exposes the durable audit document.
 
 ### Adaptive workflows
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Route work across coding-agent CLI subscriptions — paced by live quota meters, verified by content, never trusting exit codes.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -95,7 +95,9 @@ The detached runner does not depend on the initiating CLI remaining alive.
 Resume a process-interrupted run from its persisted definition with
 `bullswarm workflow goal --resume <shortId> --json`. Leave orchestrator
 selection automatic in normal use; `--orchestrator=<pool>` is for controlled
-provider QA.
+provider QA. `SIGTERM`/`SIGINT` cooperatively terminate the active delegate and
+persist `interrupted`; later workflow commands also reconcile dead or stale
+owners into that explicit resumable state.
 
 ## Multi-step shape (`bullswarm workflow draft ...`)
 
@@ -187,11 +189,15 @@ among capable pools. For strategic model selection, first run:
 ```bash
 bullswarm strategy refresh
 bullswarm strategy show --json
+bullswarm strategy apply --yes --refresh-hours 24
+bullswarm strategy auto status
 bullswarm strategy assign high --pool <pool> --model <model>
 ```
 
-Connector-declared discovery, dated benchmark/pricing evidence, and live quota
-produce high/medium/low suggestions; unknown evidence remains null. A step's
+Connector-declared discovery, dated benchmark/pricing evidence, live quota,
+and tier-specific capability requirements produce high/medium/low suggestions;
+unknown evidence remains null. `apply --yes` is the explicit approval gate: it
+persists assignments and enables TTL-based discovery/re-application. A step's
 `effort` or a lane default (`analyze=high`, `build=medium`, `chore=low`) can use
 an assignment, but it never bypasses capability, quarantine, exhaustion, or
 burst-gate safety. Each attempt records the chosen agent/model and labeled
@@ -200,7 +206,8 @@ token, cost, and normalized-quota estimates in the workflow tree.
 Run state also exposes the versioned plan, action ledger, aggregate usage, every attempt,
 planner decisions and reasons, budgets, `currentPhase`, `currentStep`, and
 `activeAgents` in `workflow tui --json <shortId>`. Each attempt includes its
-pool, selected model, effort tier, usage/cost estimate, status, task/output artifacts, timings, failure
+pool, selected model, effort tier, routing reason and eligible candidates,
+usage/cost estimate, status, task/output artifacts, timings, failure
 reason, and child-process termination evidence. `workflow tui` displays the
 same information interactively. `workflow events` supports replay after a
 monotonic sequence cursor.

package/src/cli.js

@@ -15,7 +15,7 @@ import { judgeContent } from './lib/verify.js';
 import { getVersion } from './lib/version.js';
 import { release } from './lib/release.js';
 import { cmdWorkflow } from './workflow/cli.js';
-import { cmdStrategy } from './strategy-cli.js';
+import { cmdStrategy, maybeRefreshStrategy } from './strategy-cli.js';
 
 export function getBullswarmDir() {
   const h = process.env.BULLSWARM_HOME?.trim();
@@ -33,7 +33,7 @@ function parseArgs(argv) {
     if (argv[i].startsWith('--')) {
       const key = argv[i].slice(2);
       if (key === 'json') args.json = true;
-      else if (i + 1 < argv.length) args[key] = argv[++i];
+      else if (i + 1 < argv.length && !argv[i + 1].startsWith('--')) args[key] = argv[++i];
       else args[key] = true;
     } else rest.push(argv[i]);
   }
@@ -97,6 +97,11 @@ async function cmdRun(opts) {
     return 1;
   }
 
+  // Only an explicitly approved strategy policy may change assignments.
+  // Once approved, refresh capability-aware recommendations on its TTL.
+  await maybeRefreshStrategy(getBullswarmDir());
+  state = loadState(getBullswarmDir());
+
   sweepQuarantines(state, now);
 
   const { pools } = await buildPoolsLive(getBullswarmDir(), now, {
@@ -281,11 +286,18 @@ async function cmdSetup(opts) {
   // defaults and never prompts.
   if (opts.yes || !process.stdin.isTTY) {
     const r = autoSetup(getBullswarmDir(), { reason: opts.yes ? 'flag' : 'non-tty' });
-    if (opts.json) console.log(JSON.stringify({ ok: true, mode: 'auto', ...r }, null, 2));
+    let strategy = null;
+    if (opts.yes && opts.strategy) {
+      const { refreshStrategy, applyStrategyRecommendations } = await import('./strategy-cli.js');
+      const report = await refreshStrategy(getBullswarmDir());
+      strategy = applyStrategyRecommendations(getBullswarmDir(), report);
+    }
+    if (opts.json) console.log(JSON.stringify({ ok: true, mode: 'auto', ...r, strategy }, null, 2));
     else {
       console.log(`setup complete (${r.reason}): enabled ${r.enabledPools.join(', ')}`);
       if (r.repaired.length) console.log(`repaired connector files: ${r.repaired.join(', ')}`);
       console.log(`model strategy: ${r.strategyCommand} (discovers models and refreshes tier suggestions)`);
+      if (strategy) console.log(`strategy autopilot: applied ${Object.keys(strategy.applied).join(', ')} tiers; refresh every ${strategy.policy.refreshHours}h`);
     }
     return 0;
   }
@@ -394,16 +406,19 @@ export async function main(argv) {
       return cmdDoctor(opts);
     case 'workflow':
       return cmdWorkflow(rest);
+    case 'runs':
+      return cmdWorkflow(['runs', ...rest]);
     case 'strategy':
       return cmdStrategy(rest, { bullswarmDir: getBullswarmDir() });
     case 'version':
+    case '--version':
       console.log(getVersion());
       return 0;
     case 'release':
       return cmdRelease(opts);
     default:
       console.error(
-        `unknown verb "${verb}". try: setup | run | health | pools | strategy | doctor | workflow | version | release`,
+        `unknown verb "${verb}". try: setup | run | health | pools | strategy | doctor | workflow | runs | version | release`,
       );
       return 2;
   }

package/src/lib/state.js

@@ -21,6 +21,7 @@ export const DEFAULT_STATE = {
   config: {
     depthLimit: 2,
     callerName: 'claude-code',
+    worktreeIsolation: 'agent-decides',
   },
 };
 

package/src/lib/strategy.js

@@ -129,14 +129,41 @@ function candidateScore(candidate, tier) {
   return freeBonus * 200 - costRank * 20 + quality * 10 + pace;
 }
 
+export const TIER_CONTEXTS = {
+  high: {
+    lane: 'analyze',
+    capabilities: ['strong-analysis', 'workflow-planning'],
+    description: 'analysis and autonomous orchestration',
+  },
+  medium: {
+    lane: 'build',
+    capabilities: ['code-reading', 'file-editing'],
+    description: 'implementation and verification',
+  },
+  low: {
+    lane: 'chore',
+    capabilities: [],
+    description: 'bounded chores and low-cost work',
+  },
+};
+
+function supportsContext(pool, context) {
+  const lanes = pool.lanes ?? pool.connector?.lanes ?? [];
+  const capabilities = pool.capabilities ?? pool.connector?.capabilities ?? [];
+  return lanes.includes(context.lane)
+    && context.capabilities.every((capability) => capabilities.includes(capability));
+}
+
 export function buildStrategy({ connectors, pools, state, discoveries }) {
   const subscriptions = pools.map((pool) => subscriptionView(pool, state));
   const tiers = ['high', 'medium', 'low'];
   const suggestions = {};
   for (const tier of tiers) {
+    const context = TIER_CONTEXTS[tier];
     const candidates = [];
     for (const pool of pools) {
       if (pool.enabled === false || pool.quarantine || pool.burstGate) continue;
+      if (!supportsContext(pool, context)) continue;
       const discovery = discoveries[pool.name];
       for (const model of discovery?.models ?? []) {
         if (model.tier !== tier) continue;
@@ -149,6 +176,7 @@ export function buildStrategy({ connectors, pools, state, discoveries }) {
     suggestions[tier] = {
       assignment: configured,
       recommended: candidates[0] ? { pool: candidates[0].pool.name, model: candidates[0].model.id } : null,
+      requirements: context,
       candidates: candidates.slice(0, 8).map((candidate) => ({
         pool: candidate.pool.name,
         model: candidate.model.id,
@@ -161,10 +189,10 @@ export function buildStrategy({ connectors, pools, state, discoveries }) {
         score: Math.round(candidate.score * 10) / 10,
       })),
       basis: tier === 'high'
-        ? 'dated benchmark score when declared (quality rank fallback), then live quota surplus and cost rank'
+        ? 'analysis/workflow-planning capability, then dated benchmark score (quality rank fallback), live quota surplus, and cost rank'
         : tier === 'medium'
-          ? 'balanced dated benchmark or quality rank, live quota surplus, and cost rank'
-          : 'free/low-cost first, then dated benchmark or quality rank and live quota surplus',
+          ? 'build/editing capability, then balanced dated benchmark or quality rank, live quota surplus, and cost rank'
+          : 'chore capability and free/low-cost first, then dated benchmark or quality rank and live quota surplus',
     };
   }
   return {

package/src/setup.js

@@ -357,7 +357,32 @@ export async function runWizard(bullswarmDir, opts = {}) {
   console.log(`\nWrote ${bullswarmDir}/state.json and routing.json`);
   if (repaired.length) console.log(`Repaired connector files: ${repaired.join(', ')}`);
 
-  // 5. Integration blocks — diff + approval
+  // 5. Optional execution style. Agent-decides is the neutral default: it
+  // communicates preference without forcing a repository/worktree topology.
+  const worktreeAnswer = (
+    await rl.question('worktree isolation [agent/off/required] (default agent): ')
+  ).trim().toLowerCase();
+  state.config ??= {};
+  state.config.worktreeIsolation = worktreeAnswer === 'required'
+    ? 'required' : worktreeAnswer === 'off' ? 'off' : 'agent-decides';
+  saveState(bullswarmDir, state);
+  console.log(`  worktree isolation: ${state.config.worktreeIsolation}`);
+
+  // Strategy changes actual provider/model routing, so discovery plus daily
+  // auto-application always requires an explicit setup answer.
+  const strategyAnswer = (
+    await rl.question('discover models and enable capability-aware daily strategy autopilot? [y/N] ')
+  ).trim().toLowerCase();
+  if (strategyAnswer === 'y' || strategyAnswer === 'yes') {
+    const { refreshStrategy, applyStrategyRecommendations } = await import('./strategy-cli.js');
+    const report = await refreshStrategy(bullswarmDir);
+    const applied = applyStrategyRecommendations(bullswarmDir, report);
+    console.log(`  strategy tiers applied: ${Object.entries(applied.applied).map(([tier, value]) => `${tier}=${value.pool}/${value.model}`).join(', ')}`);
+  } else {
+    console.log('  strategy autopilot: off (enable later with bullswarm strategy apply --yes)');
+  }
+
+  // 6. Integration blocks — diff + approval
   for (const [label, path] of [
     ['CLAUDE.md', join(process.env.HOME ?? '', '.claude', 'CLAUDE.md')],
     ['AGENTS.md', join(process.cwd(), 'AGENTS.md')],

package/src/strategy-cli.js

@@ -24,6 +24,12 @@ function numberOrNull(value, label) {
   return n;
 }
 
+function refreshHoursValue(value) {
+  const hours = Number(value ?? 24);
+  if (!Number.isFinite(hours) || hours <= 0) throw new Error('refresh-hours must be a positive number');
+  return hours;
+}
+
 function render(report) {
   const lines = [`bullswarm strategy · ${report.capturedAt}`, '', 'subscriptions:'];
   for (const sub of report.subscriptions) {
@@ -42,6 +48,21 @@ function render(report) {
   return lines.join('\n');
 }
 
+function strategyUsage() {
+  return `usage: bullswarm strategy <command> [options]
+
+commands:
+  refresh [--json]                         discover models and recommend tiers
+  refresh --apply --yes [--refresh-hours] discover, approve, and enable refresh
+  apply --yes [--refresh-hours <n>]        approve the last recommendations
+  auto status                              inspect the approved refresh policy
+  auto off --yes                           disable automatic re-application
+  show [--json]                            show the last strategy report
+  assign <high|medium|low> --pool --model  set one explicit preference
+  clear-assignment <tier>                  remove one preference
+  set-subscription <pool> [value flags]    record user-known plan economics`;
+}
+
 export async function refreshStrategy(bullswarmDir, { executor, getReadings = getAllMeterReadings } = {}) {
   const state = loadState(bullswarmDir);
   const connectors = loadConnectors(bullswarmDir);
@@ -57,13 +78,82 @@ export async function refreshStrategy(bullswarmDir, { executor, getReadings = ge
   return report;
 }
 
+export function applyStrategyRecommendations(bullswarmDir, report, {
+  refreshHours = 24, enableAutoRefresh = true,
+} = {}) {
+  const approvedRefreshHours = enableAutoRefresh ? refreshHoursValue(refreshHours) : null;
+  const state = loadState(bullswarmDir);
+  state.strategy ??= {};
+  state.strategy.assignments ??= {};
+  const applied = {};
+  for (const tier of ['high', 'medium', 'low']) {
+    const recommended = report?.suggestions?.[tier]?.recommended ?? null;
+    if (!recommended) continue;
+    state.strategy.assignments[tier] = { ...recommended };
+    applied[tier] = { ...recommended };
+  }
+  state.strategy.policy = {
+    ...(state.strategy.policy ?? {}),
+    autoApplyRecommendations: enableAutoRefresh,
+    refreshHours: approvedRefreshHours,
+    approvedAt: new Date().toISOString(),
+    source: 'explicit-user-approval',
+  };
+  state.strategy.lastAppliedAt = new Date().toISOString();
+  // Keep the persisted report aligned with the assignments just applied.
+  if (report) {
+    for (const tier of ['high', 'medium', 'low']) {
+      if (report.suggestions?.[tier]) report.suggestions[tier].assignment = applied[tier] ?? null;
+    }
+    state.strategy.lastReport = report;
+  }
+  saveState(bullswarmDir, state);
+  return { applied, policy: state.strategy.policy };
+}
+
+export async function maybeRefreshStrategy(bullswarmDir, opts = {}) {
+  const state = loadState(bullswarmDir);
+  const policy = state.strategy?.policy ?? {};
+  if (policy.autoApplyRecommendations !== true) return null;
+  try {
+    const hours = refreshHoursValue(policy.refreshHours);
+    const captured = Date.parse(state.strategy?.lastRefreshedAt ?? '');
+    const stale = !Number.isFinite(captured) || (Date.now() - captured) >= hours * 3600_000;
+    if (!stale) return null;
+    const report = await refreshStrategy(bullswarmDir, opts);
+    return {
+      report,
+      ...applyStrategyRecommendations(bullswarmDir, report, { refreshHours: hours }),
+    };
+  } catch (err) {
+    // Discovery is advisory and must never turn an otherwise routable run into
+    // an outage. Keep the last approved assignments and expose the failure.
+    const failed = loadState(bullswarmDir);
+    failed.strategy ??= {};
+    failed.strategy.policy ??= policy;
+    failed.strategy.policy.lastRefreshErrorAt = new Date().toISOString();
+    failed.strategy.policy.lastRefreshError = err.message;
+    saveState(bullswarmDir, failed);
+    return { error: err.message, retainedAssignments: failed.strategy.assignments ?? {} };
+  }
+}
+
 export async function cmdStrategy(args, { bullswarmDir }) {
   const [sub = 'show', ...rest] = args;
   const opts = parseFlags(rest);
   try {
+    if (sub === 'help' || sub === '--help' || opts.help) {
+      console.log(strategyUsage());
+      return 0;
+    }
     if (sub === 'refresh' || sub === 'recommend') {
+      if (opts.apply && opts.yes !== true) throw new Error('--apply changes routing; pass --yes to approve');
       const report = await refreshStrategy(bullswarmDir);
-      console.log(opts.json ? JSON.stringify(report, null, 2) : render(report));
+      const applied = opts.apply
+        ? applyStrategyRecommendations(bullswarmDir, report, {
+          refreshHours: refreshHoursValue(opts['refresh-hours']),
+        }) : null;
+      console.log(opts.json ? JSON.stringify(applied ? { report, ...applied } : report, null, 2) : render(report));
       return 0;
     }
     if (sub === 'show') {
@@ -110,6 +200,32 @@ export async function cmdStrategy(args, { bullswarmDir }) {
       console.log(JSON.stringify({ action: 'tier-assigned', tier, assignment: state.strategy.assignments[tier] }, null, 2));
       return 0;
     }
+    if (sub === 'apply') {
+      if (opts.yes !== true) throw new Error('strategy apply changes routing; pass --yes to approve');
+      const state = loadState(bullswarmDir);
+      const report = state.strategy?.lastReport ?? await refreshStrategy(bullswarmDir);
+      const result = applyStrategyRecommendations(bullswarmDir, report, {
+        refreshHours: refreshHoursValue(opts['refresh-hours']),
+      });
+      console.log(JSON.stringify({ action: 'strategy-applied', ...result }, null, 2));
+      return 0;
+    }
+    if (sub === 'auto') {
+      const mode = opts.rest[0] ?? 'status';
+      const state = loadState(bullswarmDir);
+      state.strategy ??= {};
+      state.strategy.policy ??= {};
+      if (mode === 'off') {
+        if (opts.yes !== true) throw new Error('strategy auto off changes routing policy; pass --yes to approve');
+        state.strategy.policy.autoApplyRecommendations = false;
+        state.strategy.policy.disabledAt = new Date().toISOString();
+        saveState(bullswarmDir, state);
+      } else if (mode !== 'status') {
+        throw new Error('usage: bullswarm strategy auto <status|off> [--yes]');
+      }
+      console.log(JSON.stringify({ action: 'strategy-auto', policy: state.strategy.policy }, null, 2));
+      return 0;
+    }
     if (sub === 'clear-assignment') {
       const tier = opts.rest[0];
       if (!['high', 'medium', 'low'].includes(tier)) throw new Error('usage: bullswarm strategy clear-assignment <high|medium|low>');
@@ -120,7 +236,7 @@ export async function cmdStrategy(args, { bullswarmDir }) {
       console.log(JSON.stringify({ action: 'tier-assignment-cleared', tier }, null, 2));
       return 0;
     }
-    throw new Error('usage: bullswarm strategy <show|refresh|recommend|set-subscription|assign|clear-assignment>');
+    throw new Error(strategyUsage());
   } catch (err) {
     console.error(`✗ ${err.message}`);
     return 1;

package/src/workflow/cli.js

@@ -9,15 +9,17 @@ import { homedir } from 'node:os';
 import { spawn } from 'node:child_process';
 import { loadWorkflow, runWorkflow, newRunId } from './runner.js';
 import { validateWorkflow, WorkflowValidationError } from './validate.js';
-import { buildPoolsLive } from '../lib/config.js';
+import { buildPools, buildPoolsLive } from '../lib/config.js';
 import { getAllMeterReadings } from '../meters/registry.js';
 import { WorkflowTui } from './tui.js';
 import { cmdDraft } from './draft-cli.js';
 import { cmdRuns } from './runs-cli.js';
-import { resolveRunId } from './short-id.js';
+import { resolveRunId, reconcileInterruptedRuns } from './short-id.js';
 import { runDashboard, dashboardJson, actionJson, decideApproval } from './dashboard.js';
 import { readEvents } from './events.js';
 import { buildGoalWorkflow } from './goal.js';
+import { maybeRefreshStrategy } from '../strategy-cli.js';
+import { loadState } from '../lib/state.js';
 
 // BULLSWARM_DIR is read on every call so that changes to the
 // BULLSWARM_HOME env var (e.g. set per-test) are honored, not
@@ -76,6 +78,7 @@ function discover() {
 }
 
 export async function cmdWorkflow(args) {
+  reconcileInterruptedRuns(BULLSWARM_DIR());
   const [sub, ...rest] = args;
   const opts = parseFlags(rest);
 
@@ -151,6 +154,24 @@ function goalSettings(opts) {
     .map(([flag, setting]) => [setting, opts[flag]]));
 }
 
+function goalUsage() {
+  return `usage: bullswarm workflow goal "<goal>" [options]
+
+options:
+  --cwd <dir>                    target working directory
+  --detach                       launch independently and return observation commands
+  --json                         emit one machine-readable launch/report document
+  --orchestrator <pool|auto>     pin only for controlled use; default capability routing
+  --max-agents <n>               hard dispatch ceiling (default 30)
+  --max-expansion-rounds <n>     planner expansion ceiling (default 8)
+  --max-actions <n>              durable action ceiling (default 40)
+  --max-items-per-expansion <n>  fanout item ceiling (default 8)
+  --max-workflow-seconds <n>     wall-clock ceiling (default 3600)
+  --concurrency <n>              concurrent dispatch ceiling, max 16 (default 3)
+  --retry-attempts <0..3>        same-pool retry bound (default 1)
+  --resume <shortId|runId>       resume durable unfinished work`;
+}
+
 async function executeGoalDocument({ doc, pools, opts, runId, resumeRunId }) {
   const tui = new WorkflowTui({ quiet: opts.quiet, json: opts.json });
   const result = await runWorkflow({
@@ -242,6 +263,10 @@ async function launchDetachedGoal(doc, opts) {
 }
 
 async function wfGoal(opts) {
+  if (opts.help) {
+    console.log(goalUsage());
+    return 0;
+  }
   const { names, pools } = await livePoolNames();
   let doc;
   let resumeRunId = null;
@@ -278,7 +303,7 @@ async function wfGoal(opts) {
   } else {
     const goal = opts.rest.join(' ').trim();
     if (!goal) {
-      console.error('usage: bullswarm workflow goal "<goal>" [--cwd <dir>] [--detach] [--json]');
+      console.error(goalUsage());
       return 2;
     }
     const orchestrator = opts.orchestrator && opts.orchestrator !== 'auto'
@@ -289,6 +314,7 @@ async function wfGoal(opts) {
         cwd: opts.cwd ?? process.cwd(),
         orchestrator,
         settings: goalSettings(opts),
+        worktreeIsolation: loadState(BULLSWARM_DIR()).config?.worktreeIsolation ?? 'agent-decides',
       });
     } catch (err) {
       console.error(`✗ invalid goal options: ${err.message}`);
@@ -325,6 +351,7 @@ async function wfGoal(opts) {
 
 async function wfCapabilities(opts) {
   const { pools } = await livePoolNames();
+  const coreState = loadState(BULLSWARM_DIR());
   const result = {
     lanes: ['analyze', 'build', 'chore'],
     stepTypes: ['run', 'fanout', 'verify', 'decide'],
@@ -342,12 +369,20 @@ async function wfCapabilities(opts) {
       maxRetryAttempts: 3,
       resume: true,
       cooperativeCancellation: true,
+      cooperativeSignalInterruption: true,
+      staleOwnerReconciliation: true,
       adversarialVerification: true,
     },
     routing: {
       automatic: true,
-      selection: 'highest time-adjusted quota surplus among lane-capable, enabled, non-quarantined, non-burst-gated pools',
-      modelSelection: 'connector-defined; bullswarm does not infer intelligence or change model unless connector command pins one',
+      selection: 'approved effort-tier assignment when eligible; otherwise highest time-adjusted quota surplus among lane/capability-eligible, enabled, non-quarantined, non-burst-gated pools',
+      modelSelection: 'connector-declared discovery and model flag; approved capability-aware strategy assignments may select a model',
+      strategyPolicy: coreState.strategy?.policy ?? null,
+      assignments: coreState.strategy?.assignments ?? {},
+    },
+    worktreeIsolation: {
+      policy: coreState.config?.worktreeIsolation ?? 'agent-decides',
+      enforcement: 'optional agent execution-style preference; Bullswarm does not impose repository topology',
     },
     pools: pools.map((p) => ({
       name: p.name,
@@ -526,12 +561,14 @@ async function wfValidate(opts) {
 
 async function livePoolNames() {
   try {
+    await maybeRefreshStrategy(BULLSWARM_DIR());
     const { pools } = await buildPoolsLive(BULLSWARM_DIR(), Date.now(), {
       getReadings: getAllMeterReadings,
     });
     return { names: pools.map((p) => p.name), pools };
-  } catch {
-    return { names: [], pools: [] };
+  } catch (err) {
+    const { pools } = buildPools(BULLSWARM_DIR(), Date.now());
+    return { names: pools.map((p) => p.name), pools, meterWarning: err.message };
   }
 }
 

package/src/workflow/dashboard.js

@@ -29,7 +29,7 @@ export function requestCancel(bullswarmDir, token) {
   const statePath = join(resolved.runDir, 'state.json');
   if (!existsSync(statePath)) throw new Error(`run "${token}" has no state.json`);
   const state = JSON.parse(readFileSync(statePath, 'utf8'));
-  if (state.finishedAt || ['completed', 'failed', 'cancelled'].includes(state.status)) {
+  if (state.finishedAt || ['completed', 'failed', 'cancelled', 'interrupted', 'budget_exhausted'].includes(state.status)) {
     return { ...resolved, state, alreadyFinished: true };
   }
   state.cancelRequested = true;
@@ -88,13 +88,19 @@ export function renderDashboard({ rows, selected = 0, message = null } = {}) {
 export function renderDetails(row, { interactive = true } = {}) {
   const state = row?.state ?? {};
   const phases = state._doc?.phases ?? [];
+  const displayedPhase = state.currentPhase?.name
+    ?? state.steps?.at(-1)?.phase
+    ?? state.stage
+    ?? 'starting';
+  const displayedCurrent = state.currentStep?.id
+    ?? (state.finishedAt ? `terminal:${state.status ?? state.stage ?? 'finished'}` : '—');
   const lines = [
     `${ESC}2J${ESC}H`,
     ` bullswarm · ${state.workflow ?? '?'} · ${row?.shortId ?? row?.runId ?? '?'}`,
     '',
     ` status: ${row?.status ?? state.status ?? 'running'}`,
-    ` phase:  ${row?.phase ?? 'starting'}`,
-    ` current: ${state.currentStep?.id ?? '—'}`,
+    ` phase:  ${row?.phase ?? displayedPhase}`,
+    ` current: ${displayedCurrent}`,
     ` goal:   ${state.intent?.goal ?? state.intent?.description ?? '—'}`,
     ` orchestrator: ${state.orchestration?.selectedPool ?? state.orchestration?.requestedPool ?? 'auto/pending'} · ${state.orchestration?.selectedModel ?? 'connector model'} · ${state.orchestration?.selection ?? 'workflow-defined'}`,
     ` dir:    ${row?.runDir ?? '—'}`,
@@ -129,6 +135,10 @@ export function renderDetails(row, { interactive = true } = {}) {
       const attempt = state.attempts?.[attemptIndex];
       if (attempt) {
         lines.push(`${indent}  ↳ attempt ${attempt.attemptNumber} · ${attempt.pool ?? '—'} · ${attempt.model ?? 'connector model'} · effort=${attempt.effort ?? 'auto'} · ${attempt.status} · ${attempt.startedAt ?? '—'}${attempt.finishedAt ? ` → ${attempt.finishedAt}` : ''}`);
+        if (attempt.routing) {
+          const candidates = (attempt.routing.candidates ?? []).map((candidate) => `${candidate.pool}:${candidate.pace}`).join(', ');
+          lines.push(`${indent}     route: ${attempt.routing.reason}${candidates ? ` · candidates [${candidates}]` : ''}`);
+        }
         lines.push(`${indent}     ${compactUsage(attempt.usage)}`);
       }
     }

package/src/workflow/draft-cli.js

@@ -26,7 +26,7 @@
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { buildPoolsLive } from '../lib/config.js';
+import { buildPools, buildPoolsLive } from '../lib/config.js';
 import { getAllMeterReadings } from '../meters/registry.js';
 import { WorkflowTui } from './tui.js';
 import { runWorkflow, loadWorkflow } from './runner.js';
@@ -164,8 +164,9 @@ async function livePoolNames() {
       getReadings: getAllMeterReadings,
     });
     return { names: pools.map((p) => p.name), pools };
-  } catch {
-    return { names: [], pools: [] };
+  } catch (err) {
+    const { pools } = buildPools(BULLSWARM_DIR(), Date.now());
+    return { names: pools.map((p) => p.name), pools, meterWarning: err.message };
   }
 }
 

package/src/workflow/goal.js

@@ -43,6 +43,7 @@ export function buildGoalWorkflow({
   orchestrator = null,
   name = null,
   settings = {},
+  worktreeIsolation = 'agent-decides',
 } = {}) {
   if (typeof goal !== 'string' || !goal.trim()) {
     throw new Error('goal text is required');
@@ -62,6 +63,14 @@ export function buildGoalWorkflow({
   const maxWorkflowSeconds = positiveInt(settings.maxWorkflowSeconds, 3600, { max: 86_400 });
   const concurrency = positiveInt(settings.concurrency, 3, { max: 16 });
   const retryAttempts = positiveInt(settings.retryAttempts, 1, { min: 0, max: 3 });
+  if (!['agent-decides', 'off', 'required'].includes(worktreeIsolation)) {
+    throw new Error(`invalid worktree isolation policy "${worktreeIsolation}"`);
+  }
+  const worktreeInstruction = worktreeIsolation === 'required'
+    ? 'Worktree isolation policy: required when the selected agent supports it.'
+    : worktreeIsolation === 'off'
+      ? 'Worktree isolation policy: disabled; work in the supplied directory.'
+      : 'Worktree isolation policy: agent decides whether isolation is useful; do not introduce a worktree for routine sequential work.';
 
   return {
     schemaVersion: 'bullswarm.workflow.v1',
@@ -73,11 +82,12 @@ export function buildGoalWorkflow({
       cwd: targetDir,
       autonomous: true,
       requestedOrchestrator: orchestrator ?? 'auto',
+      worktreeIsolation,
     },
     orchestration: {
       mode: 'autonomous',
       requestedPool: orchestrator ?? null,
-      selection: orchestrator ? 'user-pinned-for-testing' : 'capability-and-quota',
+      selection: orchestrator ? 'user-pinned-for-testing' : 'capability-strategy-and-quota',
       completionPolicy: {
         requireSuccessfulWorker: true,
         requireSuccessfulVerification: true,
@@ -110,7 +120,7 @@ export function buildGoalWorkflow({
           addDir: targetDir,
           timeoutSec: Math.min(900, maxWorkflowSeconds),
         },
-        prompt: AUTONOMOUS_ORCHESTRATOR_PROMPT,
+        prompt: `${AUTONOMOUS_ORCHESTRATOR_PROMPT}\n\n${worktreeInstruction}`,
         timeoutSec: Math.min(900, maxWorkflowSeconds),
         onError: 'fail',
       }],

package/src/workflow/runner.js

@@ -91,8 +91,16 @@ export async function runWorkflow(opts) {
     delete state.cancellationLatencyMs;
     delete state.cancelRequested;
     delete state.cancelRequestedAt;
+    delete state.interruptionSignal;
+    delete state.interruptionRequestedAt;
+    delete state.interruptedAt;
+    delete state.recovery;
     delete state.abortReason;
     state.resumed = true;
+    // Commit cleared terminal/control markers before WorkflowRuntime begins
+    // merging dashboard-side state. Otherwise the first resume event can
+    // re-import the stale cancelRequested marker from the interrupted run.
+    writeFileSync(join(runDir, 'state.json'), `${JSON.stringify(state, null, 2)}\n`);
   } else {
     if (resuming) {
       throw new Error(`cannot resume: no state.json for run ${runId}`);
@@ -189,6 +197,29 @@ export async function runWorkflow(opts) {
     onEvent: opts.onEvent,
     env: opts.env,
   });
+  state.runner = {
+    pid: process.pid,
+    status: 'running',
+    startedAt: new Date().toISOString(),
+    lastHeartbeatAt: new Date().toISOString(),
+  };
+  let interruptionSignal = state.interruptionSignal ?? null;
+  const requestInterruption = (signal) => {
+    if (state.finishedAt || interruptionSignal) return;
+    interruptionSignal = signal;
+    state.interruptionSignal = signal;
+    state.interruptionRequestedAt = new Date().toISOString();
+    state.cancelRequested = true;
+    state.cancelRequestedAt ??= state.interruptionRequestedAt;
+    state.status = 'interrupting';
+    state.stage = 'interrupting';
+    runtime.emit('run.interruption_requested', { signal, requestedAt: state.interruptionRequestedAt });
+  };
+  const onSigterm = () => requestInterruption('SIGTERM');
+  const onSigint = () => requestInterruption('SIGINT');
+  process.on('SIGTERM', onSigterm);
+  process.on('SIGINT', onSigint);
+  try {
   state.availableCapabilities = {
     pools: pools.map((pool) => ({
       name: pool.name,
@@ -230,6 +261,7 @@ export async function runWorkflow(opts) {
   let completedByPlanner = false;
   let waitingForApproval = false;
   let budgetExhausted = false;
+  let interrupted = false;
   const retryAttempts = state.settings.retryAttempts ?? 1;
 
   for (let pi = 0; pi < doc.phases.length && !aborted && !cancelled && !completedByPlanner && !waitingForApproval && !budgetExhausted; pi++) {
@@ -327,32 +359,43 @@ export async function runWorkflow(opts) {
   try {
     const diskState = JSON.parse(readFileSync(join(runDir, 'state.json'), 'utf8'));
     cancelled ||= diskState.cancelRequested === true;
+    interruptionSignal ??= diskState.interruptionSignal ?? null;
   } catch { /* use the in-memory cancellation state */ }
-  if (cancelled) {
+  interrupted = Boolean(interruptionSignal);
+  if (cancelled && !interrupted) {
     state.status = 'cancelling';
     state.cancellingAt = new Date().toISOString();
     runtime.emit('run.cancelling', { requestedAt: state.cancelRequestedAt ?? null });
   }
-  state.status = cancelled ? 'cancelled' : waitingForApproval ? 'waiting_for_approval' : budgetExhausted ? 'budget_exhausted' : (aborted ? 'failed' : 'completed');
-  state.stage = cancelled ? 'cancelled' : waitingForApproval ? 'waiting_for_approval' : budgetExhausted ? 'budget_exhausted' : (aborted ? 'failed' : 'delivered');
+  state.status = interrupted ? 'interrupted' : cancelled ? 'cancelled' : waitingForApproval ? 'waiting_for_approval' : budgetExhausted ? 'budget_exhausted' : (aborted ? 'failed' : 'completed');
+  state.stage = interrupted ? 'interrupted' : cancelled ? 'cancelled' : waitingForApproval ? 'waiting_for_approval' : budgetExhausted ? 'budget_exhausted' : (aborted ? 'failed' : 'delivered');
   delete state.currentPhase;
   delete state.currentStep;
   delete state.activeAgents;
-  if (cancelled) {
+  if (cancelled && !interrupted) {
     state.cancelledAt = finishedAt;
     const requested = Date.parse(state.cancelRequestedAt ?? '');
     state.cancellationLatencyMs = Number.isFinite(requested) ? Math.max(0, Date.parse(finishedAt) - requested) : null;
   }
-  if (abortReason) state.abortReason = abortReason;
+  if (interrupted) {
+    state.interruptedAt = finishedAt;
+    state.abortReason = `runner interrupted by ${interruptionSignal}`;
+    state.recovery = { resumable: true, signal: interruptionSignal, interruptedAt: finishedAt };
+  }
+  if (abortReason && !interrupted) state.abortReason = abortReason;
   runtime.persist();
 
   const preliminaryReport = buildReport(state, doc, runDir);
-  runtime.emit(cancelled ? 'run.cancelled' : waitingForApproval ? 'run.waiting_for_approval' : budgetExhausted ? 'run.budget_exhausted' : 'run.completed', { runId, status: state.status, report: preliminaryReport.summary });
+  runtime.emit(interrupted ? 'run.interrupted' : cancelled ? 'run.cancelled' : waitingForApproval ? 'run.waiting_for_approval' : budgetExhausted ? 'run.budget_exhausted' : 'run.completed', { runId, status: state.status, report: preliminaryReport.summary });
   const report = buildReport(state, doc, runDir);
   writeFileSync(join(runDir, 'report.json'), `${JSON.stringify(report, null, 2)}\n`);
   opts.onEvent?.({ type: 'workflow.completed', runId, status: state.status, report: report.summary });
 
   return { runId, runDir, state, report };
+  } finally {
+    process.removeListener('SIGTERM', onSigterm);
+    process.removeListener('SIGINT', onSigint);
+  }
 }
 
 async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
@@ -573,6 +616,13 @@ export function buildReport(state, doc, runDir) {
     finishedAt: state.finishedAt,
     resumed: state.resumed === true,
     abortReason: state.abortReason ?? null,
+    interruption: state.interruptionSignal ? {
+      signal: state.interruptionSignal,
+      requestedAt: state.interruptionRequestedAt ?? null,
+      interruptedAt: state.interruptedAt ?? null,
+    } : null,
+    recovery: state.recovery ?? null,
+    resumeHistory: state.resumeHistory ?? [],
     summary: {
       stepsTotal: stepResults.length,
       stepsOk: simpleOk,

package/src/workflow/runtime.js

@@ -74,6 +74,14 @@ export class WorkflowRuntime {
   }
 
   persist() {
+    this.state.runner = {
+      ...(this.state.runner ?? {}),
+      pid: process.pid,
+      status: this.state.finishedAt ? this.state.status : 'running',
+      startedAt: this.state.runner?.startedAt ?? this.state.startedAt ?? new Date().toISOString(),
+      lastHeartbeatAt: new Date().toISOString(),
+      ...(this.state.finishedAt ? { finishedAt: this.state.finishedAt } : {}),
+    };
     // The dashboard may write cancelRequested while a dispatch is running.
     // Preserve that marker when the runner persists its in-memory snapshot.
     try {
@@ -272,6 +280,15 @@ export class WorkflowRuntime {
           taskFile: attemptPaths.taskFile,
           outFile: attemptPaths.outFile,
           why: null,
+          routing: {
+            reason: route.why,
+            candidates: route.candidates,
+            effort: effortTier,
+            lane: step.lane ?? 'chore',
+            requiredCapabilities: step.requiresCapabilities ?? [],
+            configuredAssignment: assignment ?? null,
+            assignmentApplied: assignment?.pool === conn.name ? assignment : null,
+          },
         };
         if (step.type === 'decide' && this.state.orchestration) {
           this.state.orchestration.selections ??= [];
@@ -284,13 +301,16 @@ export class WorkflowRuntime {
           this.state.orchestration.selectedPool = conn.name;
           this.state.orchestration.selectedModel = attemptRecord.model;
           this.state.orchestration.selections.push(selection);
-          this.emit('orchestrator.selected', selection);
+          this.emit('orchestrator.selected', { ...selection, routing: attemptRecord.routing });
         }
         this.state.attempts.push(attemptRecord);
         action.attempts.push(this.state.attempts.length - 1);
         action.status = 'running';
         action.startedAt ??= startedAt;
-        this.emit('attempt.started', { actionId, attemptNumber, pool: conn.name, model: attemptRecord.model });
+        this.emit('attempt.started', {
+          actionId, attemptNumber, pool: conn.name, model: attemptRecord.model,
+          routing: attemptRecord.routing,
+        });
         this.emit('action.started', { actionId, attemptNumber });
 
         this.emit('step.started', {
@@ -413,7 +433,7 @@ export class WorkflowRuntime {
 
         // R7: record EVERY dispatch into the shared decisionLog so
         // `bullswarm health` can correlate workflow outputs.
-        this.appendDecision(step, conn.name, verdict, attemptPaths);
+        this.appendDecision(step, conn.name, verdict, attemptPaths, attemptRecord.routing);
 
         // R7: auth/throttle verdict → quarantine the pool for 10 min so
         // the next dispatch doesn't re-select it.
@@ -494,7 +514,7 @@ export class WorkflowRuntime {
     );
   }
 
-  appendDecision(step, poolName, verdict, paths) {
+  appendDecision(step, poolName, verdict, paths, routing = null) {
     try {
       const coreState = loadState(this.bullswarmDir);
       coreState.decisionLog ??= [];
@@ -508,6 +528,7 @@ export class WorkflowRuntime {
         wallSec: verdict.meta?.wallSec,
         model: verdict.pick?.model ?? null,
         usage: verdict.meta?.usage ?? null,
+        routing,
         outFile: paths?.outFile ?? null,
         source: 'workflow',
         stepId: step.id,

package/src/workflow/short-id.js

@@ -16,8 +16,9 @@
 // not the generator.
 
 import { randomBytes } from 'node:crypto';
-import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { readdirSync, readFileSync, writeFileSync, existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import { appendEvent } from './events.js';
 
 export const SHORT_ID_ALPHABET = '23456789abcdefghijkmnpqrstuvwxyz';
 export const SHORT_ID_LEN = 6;
@@ -111,9 +112,8 @@ export function resolveRunId(bullswarmDir, token) {
 /**
  * Read all runs (one entry per `wf-...` subdir of `~/.bullswarm/workflows/`).
  * Each entry includes the `state.json` summary + the `report.json`
- * summary if it exists. The `ongoing` field is computed by trying to
- * take an exclusive flock on `state.json` (proves the writer process
- * is gone).
+ * summary if it exists. Active states are reconciled against the persisted
+ * owner PID and heartbeat before the `ongoing` field is computed.
  */
 export function listRuns(bullswarmDir) {
   const runsRoot = join(bullswarmDir, 'workflows');
@@ -129,6 +129,7 @@ export function listRuns(bullswarmDir) {
     if (existsSync(sf)) {
       try { state = JSON.parse(readFileSync(sf, 'utf8')); } catch { /* corrupt */ }
     }
+    if (state) state = reconcileInterruptedRun(dir, state);
     if (existsSync(rf)) {
       try { report = JSON.parse(readFileSync(rf, 'utf8')); } catch { /* corrupt */ }
     }
@@ -165,6 +166,94 @@ export function listRuns(bullswarmDir) {
  */
 export const ONGOING_GRACE_MS = 90_000;
 
+const ACTIVE_STATUSES = new Set(['queued', 'running', 'cancelling', 'interrupting']);
+
+export function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Convert an ownerless active state into an explicit resumable interruption.
+ * This is recovery, not garbage collection: outputs and attempts remain and
+ * `workflow goal --resume <id>` can continue from the durable workflow.
+ */
+export function reconcileInterruptedRun(runDir, state, {
+  now = Date.now(), processAlive = isProcessAlive,
+} = {}) {
+  if (!state || state.finishedAt || !ACTIVE_STATUSES.has(state.status)) return state;
+  if (state.status === 'waiting_for_approval' || state.status === 'paused') return state;
+  const statePath = join(runDir, 'state.json');
+  let modifiedAt = 0;
+  try { modifiedAt = statSync(statePath).mtimeMs; } catch { return state; }
+  const heartbeatAt = Date.parse(
+    state.runner?.lastHeartbeatAt
+      ?? Object.values(state.activeAgents ?? {}).map((agent) => agent.lastHeartbeatAt).filter(Boolean).sort().at(-1)
+      ?? '',
+  );
+  const lastLiveAt = Number.isFinite(heartbeatAt) ? heartbeatAt : modifiedAt;
+  const fresh = (now - lastLiveAt) < ONGOING_GRACE_MS;
+  const pid = state.runner?.pid ?? null;
+  const ownerAlive = pid != null && processAlive(pid);
+  // A live PID alone is insufficient because PIDs can be reused. Persisted
+  // heartbeats let us require both identity signals for modern run states.
+  if ((pid != null && ownerAlive && fresh) || (pid == null && fresh)) return state;
+
+  const reconciledAt = new Date(now).toISOString();
+  const reason = pid == null
+    ? 'runner heartbeat expired before a terminal state was persisted'
+    : `runner process ${pid} exited before a terminal state was persisted`;
+  state.status = 'interrupted';
+  state.stage = 'interrupted';
+  state.finishedAt = reconciledAt;
+  state.interruptedAt = reconciledAt;
+  state.abortReason = reason;
+  state.recovery = { resumable: true, reconciledAt, reason };
+  state.runner = { ...(state.runner ?? {}), status: 'interrupted', finishedAt: reconciledAt };
+  for (const attempt of state.attempts ?? []) {
+    if (attempt.status === 'running') {
+      attempt.status = 'abandoned';
+      attempt.finishedAt = reconciledAt;
+      attempt.why = reason;
+    }
+  }
+  for (const action of state.actionLedger ?? []) {
+    if (['running', 'retry_scheduled', 'queued'].includes(action.status)) {
+      action.status = 'interrupted';
+      action.finishedAt = reconciledAt;
+      action.why = reason;
+    }
+  }
+  delete state.activeAgents;
+  delete state.currentPhase;
+  delete state.currentStep;
+  appendEvent(runDir, state, 'run.interrupted_reconciled', { reason, resumable: true });
+  writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+  return state;
+}
+
+export function reconcileInterruptedRuns(bullswarmDir, opts = {}) {
+  const runsRoot = join(bullswarmDir, 'workflows');
+  if (!existsSync(runsRoot)) return [];
+  const changed = [];
+  for (const name of readdirSync(runsRoot)) {
+    const runDir = join(runsRoot, name);
+    const statePath = join(runDir, 'state.json');
+    if (!name.startsWith('wf-') || !existsSync(statePath)) continue;
+    let state;
+    try { state = JSON.parse(readFileSync(statePath, 'utf8')); } catch { continue; }
+    const before = state.status;
+    const next = reconcileInterruptedRun(runDir, state, opts);
+    if (before !== next.status && next.status === 'interrupted') changed.push(name);
+  }
+  return changed;
+}
+
 export function isOngoing(runDir, state) {
   if (state && state.status && state.finishedAt) return false;
   try {