bullswarm 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # bullswarm changelog
 
+## 0.15.0 — extra Claude Code logins as separate pools
+
+- Claude Code extra logins (`~/.claude-<slug>` / `$CLAUDE_CONFIG_DIR`) become
+  their own pools (`claude-code:<slug>`), metered and spawned with
+  `CLAUDE_CONFIG_DIR` set. Discovery is dynamic from the filesystem; there
+  is no hardcoded extra-profile list. The spawn command for each profile is
+  `CLAUDE_CONFIG_DIR=<dir> claude`.
+
+## 0.14.1 — the TUI survives its writer; steering lands or expires truthfully
+
+Proven on a goal-3 re-run (`d7xyg2`): 1 planner turn / 269 s (baseline 0.13.1: 1 / 294 s), planner context 6.2 k chars (from 32.7 k), auto-completed, deliverable verified, zero observation crashes — `docs/experiments/2026-08-29-dogfood-bullswarm-builds-bullswarm.md`.
+
+- Workflow `state.json`/`report.json`/`workflow.json` writes are atomic
+  (temp + rename, new `src/workflow/fsjson.js`): a concurrent reader can never
+  observe a half-written file. Earned: `workflow tui` crashed with
+  "Unterminated string in JSON at position 138968" parsing `state.json`
+  mid-write (observed twice, 2026-08-29).
+- Observation readers tolerate torn or missing JSON: the TUI keeps painting
+  the last good frame of the same run, and a render or key-handler error is
+  shown in the message line instead of killing the process and stranding the
+  terminal in alt-screen raw mode. Mutating commands (stop, approval) retry
+  the read once and then refuse loudly instead of silently dropping the
+  operator's command. `runs delete` treats an unreadable `state.json` as
+  ongoing (refuses without `--force`) rather than deleting a possibly-live run.
+- An action being re-run (repair round, re-verify, schema retry) reads as
+  `running` and its phase as `active` even when its previous round recorded
+  `ok:false`; a failed mark now means failed-and-not-being-retried. (User
+  report: the TUI showed ✗ "2/2 complete" beside a live spinner.)
+- Pending operator steering defers program self-completion: a clean program
+  with `completion: all-actions-ok` returns to the planner gate (event
+  `decision.completion_deferred`), which delivers the steer — instead of
+  auto-completing and silently discarding it (defect observed live:
+  0 `steering.delivered` events for a queued steer). Steering that can no
+  longer reach any gate is marked `expired_undelivered` with event
+  `steering.expired` at the terminal transition; interrupted runs keep their
+  queue for the resumed run's next gate.
+- Resume re-runs an action the interruption cancelled mid-flight instead of
+  re-planning around a phantom failure: cancelled actions and the dependents
+  blocked only by them are reopened (event `action.reopened`) and the accepted
+  program continues from where it stopped. Observed on a SIGTERM-interrupted
+  run: 1 cancelled action → 4 "blocked" → a spurious planner turn.
+- Planner contract: a verify with several `dependsOn` must set `review`
+  (rule 4); the program's last worker must be covered by a successful verify
+  (rule 8) — both were the causes of extra planner gates on the goal-3 proof
+  run. A corrective turn's `validationFeedback.rejectedResponseExcerpt` is
+  capped at 2 000 chars, and the rejected proposal is resent as a skeleton
+  (ids, shapes, dependsOn; prompts elided) — the planner's thread already
+  holds it verbatim.
+- A verify without `review` is no longer grounds to reject a whole program:
+  it reviews its single (or last) dependency's artifact, or audits the
+  repository directly when it has no `dependsOn` (`reviewScope: repository`).
+  Observed on two proof runs: a 9-action program bounced for one field,
+  costing a 5-minute correction turn each time.
+
 ## 0.14.0 — structured worker output, compact planner contract
 
 - A verify whose reply cannot be parsed as the verdict JSON gets ONE bounded

package/docs/experiments/2026-08-29-dogfood-bullswarm-builds-bullswarm.md

@@ -0,0 +1,171 @@
+# Dogfood 2026-08-29 — bullswarm builds bullswarm (outputSchema + planner refactor)
+
+Observation log of the two dogfood runs that produced 0.14.0, kept verbatim
+from the driving session's notes; the post-run defects below produced 0.14.1.
+
+
+Goal file: `goal4.txt` (7 deliverables, single-implementer constraint). Repo branch: `feat/output-schema`.
+Runtime: local worktree `bullswarm-rt` pinned at main (user: redispatch with local runtime, keep committing; no npm wait).
+Home: default `~/.bullswarm` (heterogeneous pools) — user can `bullswarm workflow tui <shortId>`.
+
+## Attempt 1 — 01:43:37 Z, installed 0.13.1 — failed at validation, nothing ran
+`autonomous workflow invalid (nothing ran): phases[0].steps[0](scout): template ref "{{outputs.x.data.field}}" cannot resolve`.
+Cause: goal text spliced into the scout prompt; validator parsed a quoted ref in user text.
+Fix (bullswarm defect #1): goal → declared `inputs.goal`, inserted at render time; unresolved grammar-valid refs are
+left literal + `template.unresolved_ref` event instead of fatal. Commit `7badea3`, released 0.13.2 (`a0f0965`).
+Verified: scout task file of attempt 3 contains `{{outputs.x.data.field}}` verbatim; only `{{inputs.goal}}` resolved.
+
+## Attempt 2 — 01:47:37 Z — launcher bug (mine, not bullswarm): zsh does not word-split `$BS="node path"`. Fixed script.
+
+## Attempt 3 — 01:48:19 Z, runtime 0.13.2 @ a0f0965 — run `wf-mtdq1l9v-ed22fe` / `75t4n2`
+- 01:48:22 scout → pool `opencode2` model `kaihk/gpt-5.6-luna`. Routing: "most-behind capable pool (surplus 0)";
+  candidates opencode2 pace 0 (unmetered) > grok −7.5 > claude-code −9.4 > codex −49.1.
+  Observation: an unmetered pool reads as exactly on pace (0) and therefore outranks every metered pool that is
+  ahead of pace. Not a crash, but quota-unknown pools capture all work whenever metered pools are burning ahead.
+- 01:48:22 → 01:49:54 scout ok (92 s, opencode2).
+- 01:50:06 → 02:00:40 planner turn 1 (**~634 s** — roughly 2× the goal-2/3 turns; goal text is 6.5 k chars and the
+  program is 12 actions). Decision: `needs_more_work`, 12 actions, `completion: all-actions-ok` attached.
+  Program honours the single-implementer constraint: `impl-src` (all src) ∥ `docs`; `tests-schema`/`tests-adaptive`/
+  `tests-gaps` + `verify-impl(repair 2)` fan out after impl-src; per-writer verifies with repair; `final-report` →
+  `verify-suite(repair 2)`. Note: `verify-impl`'s repair may edit src while the test writers read it — accepted risk,
+  `verify-suite` runs the whole suite at the end.
+- 02:00:31 `impl-src` and `docs` → opencode2 `kaihk/gpt-5.6-luna` (medium effort, "most-behind capable pool (surplus 0)").
+  All build work lands on the unmetered pool while claude-code/grok/codex are ahead of pace. Orchestrator stayed on
+  claude-code (pinned).
+- 02:00:31 → 02:07:09 `impl-src` ok (398 s, opencode2); `docs` ok (140 s). 02:07:11 five actions started at once
+  (3 test writers + verify-impl + verify-docs).
+- 02:08:20 `verify-impl` ok:false → `verify-impl-repair-1` (concerns were concrete and correct: schema JSON omitted from
+  the retry task text; fan-out item resume skipped schemaOk; no combined run+fanout skeleton). 02:08:36 `verify-docs`
+  ok:false → `verify-docs-repair-1` (doc claimed fan-out persists top-level data/schemaOk; doc claimed static validator
+  rejects outputSchema on verify but only decision.js did). Repairs 121 s / 124 s. Both are repair-loop live uses; if the
+  program then self-completes this is the first live exercise of the 0.13.1 fix path.
+- 02:12 → 02:18 second round of repairs: `verify-impl-repair-2` (escalation could allow a 2nd schema retry — legit design
+  nit; "schema.js untracked so absent from git diff --stat" — verifier misreading), `verify-adaptive-tests-repair-1/2`
+  (rejected twice for the same reason: "diff is not purely additive: modifies an existing assertion" — the
+  programFeatures assertion HAD to change; an unrepairable process criterion). Both verifies ended ok:false after
+  maxRounds → `final-report`/`verify-suite` blocked (`failed_terminal: dynamic actions blocked by failed or unresolved
+  dependencies`) → program boundary → planner turn 2 at 02:18:52.
+  Observation (behaviour): a verifier that judges process criteria ("purely additive", "untracked file") instead of the
+  goal's acceptance checks produces rejections no repair can satisfy; two repair rounds (~10 min) were spent before the
+  boundary. Candidate for the prompt audit: verify doctrine "ok:false only for failed acceptance checks; process
+  observations are concerns" and/or runtime: identical concerns after a repair → boundary immediately.
+- 02:18:52 → ~02:25:20 planner turn 2 (~390 s): `needs_more_work`, 3 sequential actions — `recheck-src` (verify, repair 2,
+  depends on verify-impl-repair-2) → `full-suite-report` (run) → `verify-final` (verify, repair 2). Reason correctly
+  notes no whole-suite evidence existed after the repairs (impl-src's npm test predated them).
+- 02:25:52 → 02:32:36 follow-up program: `recheck-src` ok:false → `recheck-src-repair-1` → re-verify ok; `full-suite-report`
+  ok; `verify-final` ok → **`decision.auto_completed` (program-completion)** at 02:32:39.
+## Result (attempt 3)
+- Wall **44 min 17 s** (2 654 s), 28 dispatches (26 opencode2 + 2 planner on claude-code), max concurrent 5,
+  parallelism 1.5, planner 2 turns / 1 045 s (39 % — turn 1 alone 637 s), repairs 6 (2 repaired ok, 4 re-verify
+  rejected), tokens ≈ 108 k (estimate).
+- Deliverable: 10 files changed + 2 new (489+/38−); `npm test` **318/318** (299 + 19) on my own run; validator module,
+  decision/validate/runtime/runner/template changes all present; docs + changelog written.
+- My review: sound; one robustness flaw fixed by hand — `readTrailingObject` used a reverse brace/quote scanner whose
+  escape handling is wrong scanning backwards (a `\"` inside a string could derail it and waste the single retry);
+  replaced with the parse-candidates approach `hasStructuredAnswer` already uses. Double failure now reports the
+  retry's errors. Escalation concern from verify-impl judged mistaken (escalation follows failed dispatches only).
+- 0.13.1 fix path: NOT exercised here either — the latest worker at completion was `full-suite-report`, verified by a
+  direct edge (`verify-final`).
+## Adversarial review via `bullswarm run --lane analyze` (02:36 → 02:39 Z, 206 s, opencode2 kaihk/gpt-5.6-luna)
+- Verdict "do not release" with **two confirmed, reproduced defects** — both in code I had reviewed and passed:
+  (1) my rewritten `readTrailingObject` returned the first schema-valid `{…}` from the right, so a nested object
+  could be recorded (`{"wrapper":{"ok":"inner"}}` → data `{"ok":"inner"}`); (2) `schema.js` used `in`, so
+  `toString`/`constructor`/`__proto__` counted as present/declared. Cleared: escaped quotes, fenced JSON, resume rules,
+  exactly-one retry, validator paths. Fixed + regression tests (320/320); my fix also had an infinite loop when output
+  starts with `{` (lastIndexOf clamps negative fromIndex) — caught by the suite hanging, fixed.
+- Evidence for open item "adversarial verification by default": a 3-minute refute-framed review found what the
+  run's own verifies (6 rounds) and my manual review both missed.
+## Goal 5 — planner context/contract refactor — run `wf-mtds7tzx-95ab05` / `ejk9w2`, 02:49:09 Z, runtime 0.13.2 local
+- scout 72 s (opencode2); planner turn 1 02:50:55 → 02:58:56 (~480 s): 6 actions, completion attached; noticed the goal's
+  stale "318 passing" and used the real 320. Program: impl-src → verify-src(repair 2) → update-tests ∥ update-docs →
+  verify-tests(repair 2) → verify-suite(repair 1).
+- 02:58:56 → 03:09:04 impl-src (~610 s). verify-src rejected twice, both times on SUBSTANTIVE spec points (obsolete
+  skeleton text left in a comment; 6 JSON examples instead of 2; `<item>` instead of `{{item}}` in examples; excerpt
+  policy). One misread to check in the final diff: it called the existing 3 000/36 000-char excerpt caps a violation of
+  "full excerpt" although the goal said "(existing budget logic)" — the repair may have removed the caps.
+  Ordering tension: verify-src runs before update-tests, so it necessarily sees 5 failing old assertions; the planner
+  should either fold assertion updates into impl-src or make verify-src judge src only.
+- Goal 5 finished 04:00:40 Z (71.5 min, 3 planner turns + program-completion, 15 dispatches, plannerSec 1 105+175).
+  Where the time went: 18–20 min planner turns; 12.4 min verify-src repair loop enforcing my over-exacting spec and
+  judging intermediate state; ~8 min decision-3 nit round (`align-prefix-number` + `confirm-docs`) triggered by an
+  UNPARSEABLE final-check verdict; the queued steer (03:57:32, "converge now") was NEVER delivered — 0 steering.delivered events; the run auto-completed (program-completion, 04:00:40) and deliverSteering only runs at planner gates, so auto-completion silently discards pending operator steering. Known issue; convergence came from the runtime, not the steer.
+  Deliverable reviewed + committed `15f1534`: 10-rule contract (2.2 k chars) + 2 examples (1.9 k) replace 16.3 k prefix;
+  compact ledger rows; id-only failures; 200-char stale excerpts; `decision.context_built` size event; 323/323.
+- My follow-up (commit after 15f1534): verify verdict parse failure → ONE bounded re-ask (`verify.verdict_retry`,
+  test with a garbled-once verifier, 324/324); contract amendments (verify scoping, converge-not-polish, restored
+  shared-tree/redundant-verification/operatorSteering lines the merge dropped); re-budgeted "full" excerpts (the
+  uncapped version could have rebuilt the 163 k contexts).
+- Speed answer to the user: ~35 of 66 min (at question time) was real work; fixes target the rest — re-ask (−8 min),
+  verify scoping (−12 min), convergence rule (−nit rounds). Remaining lever: planner turn latency itself (Opus
+  high-effort per boundary; context compaction cuts cost ~7×, latency is model thinking time).
+
+## Post-run defects → 0.14.1 (fixed directly, dogfooding paused by user direction)
+- `workflow tui` crashed twice (`detailRow` dashboard.js:809 `JSON.parse` of
+  state.json mid-write; the throw escaped the repaint timer and killed the TUI,
+  stranding the terminal in alt-screen raw mode). Fix: atomic temp+rename
+  writes for state/report/workflow.json + torn-read-tolerant observation
+  readers + guarded paint/key handlers with last-good-frame fallback.
+- TUI showed phase ✗ "2/2 complete" while a re-verify attempt was live. Fix:
+  an action with an active agent reads as running; phase precedence
+  active > failed > completed.
+- The goal-5 steer was never delivered: auto-completion bypassed the planner
+  gate and silently discarded pending steering (0 steering.delivered events).
+  Fix: pending steering defers self-completion to the planner
+  (`decision.completion_deferred`); undeliverable steering is marked
+  `expired_undelivered` (`steering.expired`) at the terminal transition.
+- Routing concentration on the unmetered pool (26/28 dispatches) confirmed as
+  design intent (quota protection outranks diversity) and documented in the
+  skill rather than changed.
+
+## Proof run 1 — goal-3 re-run `d8pr8s` (wf-mtdvuk9m), 0.14.1-pre @ 0bbe78c
+Baseline (0.13.1, same fixture/goal/pool/flags): 28m42s wall, 1 planner turn, 294 s planner.
+- **completed + verified, deliverable exactly right** (csv+slugify guarded, existing tests byte-identical, 63/63),
+  zero crashes, 8 workers, no repairs.
+- Wall **32m19s**, planner **5 dispatches / 463 s** (195+114+58+66+30). Per-turn latency DOWN (max 195 s vs 294 s);
+  context per turn 6.2k–48k chars (`decision.context_built` measuring itself) vs the old 16.3k prefix + up-to-178k contexts.
+- The 3 extra gates, each diagnosed and fixed in `c0ff947`:
+  1. first proposal rejected — verify with several dependsOn lacked `review` → contract rule 4 now states it;
+  2. evidence-policy boundary + rejected `complete` — final-report left as last unverified worker → rule 8 now
+     states the LAST worker must be covered by a verify;
+  3. one deliberate operator steer — which **live-proved the 0.14.1 steering fix**: `decision.completion_deferred`
+     → `steering.delivered` (first ever observed; the goal-5 defect showed 0) → planner turn honoured it.
+- Also observed and fixed: a corrective turn re-inflated validationFeedback to 24k chars (raw response duplicated
+  the parsed proposal) → excerpt capped at 2k.
+- 0.13.1 completion-evidence policy exercised live for the first time: it refused auto-completion twice, correctly.
+
+## Proof run 2 — goal-3 re-run `djnjka` (wf-mtdx5htt), 0.14.1-pre @ c0ff947 — interrupted, then cancelled
+- Turn-1 proposal **accepted first try** (no validation rejection, no correction turn): contract fix #1 confirmed.
+  Turn-1 context 6,201 chars.
+- At 05:21 the driving session's background task was killed by the harness (not the user); SIGTERM reached the
+  runner, which persisted `interrupted` + resumable (1/3 steps, in-flight `triage` cancelled) — the 0.13 interruption
+  path working as designed.
+- Resume at 05:54 exposed a **resume defect**: the cancelled `triage` was persisted `ok:false` ("workflow
+  cancellation requested"), so its 4 dependents were marked "blocked by failed or unresolved dependencies" and the
+  planner was asked to re-plan around a failure that never happened. Cancelled the run; fixed in `459c58c`
+  (cancelled actions + dependents blocked only by them are reopened on resume, event `action.reopened`; regression
+  test drives a cancel marker into a slow in-flight action and asserts exactly one further planner turn).
+
+## Proof run 3 — goal-3 re-run `4t6m5a` (wf-mtdyyqkw), 0.14.1-pre @ 459c58c — cancelled after diagnosis
+- Turn-1 proposal (9 actions, sound shape: 3 disjoint impl workers ∥ audit of untouched modules → per-module
+  verifies → final-report → verify-final, completion attached) was **rejected** for one field: a zero-dependsOn
+  audit verify carried no `review`. Correction turn cost ~5 min and re-inflated context to 47.8k chars
+  (validationFeedback 38k — the 2k cap on rejectedResponseExcerpt was insufficient because rejectedProposal
+  itself is 37k). Root cause is the validator's posture, not the planner: rejecting a whole program for a field the
+  runtime can default. Fixed in `548eabe`: review defaults to the single/last dependency's artifact, or
+  `reviewScope: repository` for a no-dependency audit; contract rule 4 reworded. Run cancelled to re-prove cleanly.
+
+## Proof run 4 — goal-3 re-run `d7xyg2` (wf-mtdzhw88), 0.14.1-pre @ 548eabe — **PASS**
+| metric | 0.13.1 baseline (x3x2a2-era, same fixture) | 0.14.1-pre run 4 |
+| --- | ---: | ---: |
+| outcome | completed, verified | completed, verified, **auto-completed** (program-completion) |
+| wall | 28 min 42 s | 30 min 12 s |
+| planner turns / plannerSec | 1 / 294 s | **1 / 269 s** |
+| planner context (turn 1) | 32.7 k chars (measured on a sibling run) | **6.2 k chars** |
+| dispatches (workers) | — | 8 (7) · max concurrent 9 |
+| corrections / rejections / repairs / verdict re-asks | 0 / 0 / 0 / 0 | 0 / 0 / 0 / 0 |
+| deliverable | csv + slugify guarded, 63/63 | csv + slugify guarded, **63/63**, existing test files byte-identical |
+Program: scout → probe (all exports, wrong-type matrix) → fanout guards over the discovered modules → verify-guards →
+report → verify-final, `completion: all-actions-ok`. Wall is within noise of baseline (+90 s, dominated by worker
+model time: probe 4.7 min, guards 5.1 min, verify-guards 4.7 min); the planner side is faster and 5× smaller.
+Zero observation crashes across four runs of TUI/watch/runs/result/static-tui polling and a 20 s stress loop
+(1,681 paints against the live writer, 0 torn, 0 throws).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.14.0",
+  "version": "0.15.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

@@ -246,7 +246,12 @@ bullswarm workflow steer <shortId> --message "guidance for the next planner chec
 `capabilities` reports available pools, supported lanes, configured models,
 meter readings, burst gates, quarantine state, retry limits, and the important
 routing rule. Automatic routing chooses the highest time-adjusted quota surplus
-among capable pools. For strategic model selection, first run:
+among capable pools. An unmetered pool reads as exactly on pace (surplus 0), so
+whenever every metered pool is burning ahead of its window (negative
+surplus) the unmetered pool wins ALL work — by design: quota protection
+outranks provider diversity (observed 2026-08-29: 26 of 28 dispatches on
+one unmetered pool). If that concentration is unwanted, meter the pool or
+exclude its models via `strategy exclude-model`. For strategic model selection, first run:
 
 ```bash
 bullswarm strategy refresh
@@ -406,6 +411,17 @@ Resume by shortId:
 bullswarm workflow draft run my-audit --resume <shortId> --json --quiet
 ```
 
+## Writing goals that converge
+
+State outcomes, not measurements. A goal that fixes character counts, exact
+event names, or cosmetic layout turns every verifier into a nit machine:
+observed 2026-08-29 (run `ejk9w2`), a spec with hard numeric limits cost a
+12-minute verify/repair loop enforcing them against an intermediate state.
+Say what must be true at the end (`npm test` passes, the planner receives one
+contract stated once, context stays bounded) and let workers pick the numbers;
+put any hard limit in ONE final acceptance check, not on every intermediate
+verify.
+
 ## Writing prompts that the verify gate will accept
 
 The verify gate (`src/lib/verify.js`) flags outputs as `intent_only`

package/src/lib/claude-accounts.js

@@ -0,0 +1,202 @@
+// Discover Claude Code logins on this machine.
+//
+// One account = one config dir (`~/.claude` by default, or CLAUDE_CONFIG_DIR).
+// Extra homes live next to it as `~/.claude-<slug>`. Credentials:
+//   macOS Keychain `Claude Code-credentials` for ~/.claude
+//   `Claude Code-credentials-<sha256(absPath)[:8]>` for any other home
+//   plus `$dir/.credentials.json` on every platform.
+
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import {
+  DEFAULT_KEYCHAIN_SERVICE,
+  extractCredentials,
+  isUsable,
+  readFromMacKeychain,
+} from '../meters/claude.js';
+
+const HOME_MARKERS = ['.credentials.json', '.claude.json', 'settings.json', 'projects'];
+
+export function defaultClaudeHome(homeDir = homedir()) {
+  return resolve(join(homeDir, '.claude'));
+}
+
+export function keychainServiceForConfigDir(configDir, homeDir = homedir()) {
+  const resolved = resolve(configDir);
+  if (resolved === defaultClaudeHome(homeDir)) return DEFAULT_KEYCHAIN_SERVICE;
+  const hash = createHash('sha256').update(resolved).digest('hex').slice(0, 8);
+  return `${DEFAULT_KEYCHAIN_SERVICE}-${hash}`;
+}
+
+export function accountSlugForConfigDir(configDir, homeDir = homedir()) {
+  const resolved = resolve(configDir);
+  if (resolved === defaultClaudeHome(homeDir)) return null;
+  const base = basename(resolved);
+  if (base.startsWith('.claude-')) {
+    const slug = base.slice('.claude-'.length);
+    return slug.length > 0 ? slug : 'alt';
+  }
+  if (base.startsWith('.claude')) {
+    const rest = base.slice('.claude'.length).replace(/^-+/, '');
+    return rest.length > 0 ? rest : 'alt';
+  }
+  return base || 'alt';
+}
+
+export function poolNameForSlug(slug) {
+  return slug ? `claude-code:${slug}` : 'claude-code';
+}
+
+export function looksLikeClaudeHome(dir) {
+  try {
+    if (!statSync(dir).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return HOME_MARKERS.some((name) => existsSync(join(dir, name)));
+}
+
+export function discoverClaudeConfigDirs(opts = {}) {
+  const homeDir = opts.homeDir ?? homedir();
+  const found = [];
+  const seen = new Set();
+  const add = (dir) => {
+    const resolved = resolve(dir);
+    if (seen.has(resolved)) return;
+    if (!looksLikeClaudeHome(resolved)) return;
+    seen.add(resolved);
+    found.push(resolved);
+  };
+  add(join(homeDir, '.claude'));
+  try {
+    for (const name of readdirSync(homeDir)) {
+      if (!name.startsWith('.claude-')) continue;
+      add(join(homeDir, name));
+    }
+  } catch { /* unreadable home */ }
+  const envDir = opts.envConfigDir ?? process.env.CLAUDE_CONFIG_DIR;
+  if (envDir && String(envDir).trim()) add(String(envDir).trim());
+  return found;
+}
+
+function readCredentialsFile(path) {
+  try {
+    return extractCredentials(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function readAccountCredentials(configDir, opts = {}) {
+  const homeDir = opts.homeDir ?? homedir();
+  const nowMs = opts.nowMs ?? Date.now();
+  const os = opts.platform ?? platform();
+  const keychainRead = opts.readKeychain ?? readFromMacKeychain;
+  const usableOnly = opts.usableOnly !== false;
+
+  const fileCreds = readCredentialsFile(join(configDir, '.credentials.json'));
+  let keychainCreds = null;
+  if (os === 'darwin') {
+    keychainCreds = keychainRead(keychainServiceForConfigDir(configDir, homeDir));
+  }
+  const extraFile = resolve(configDir) === defaultClaudeHome(homeDir)
+    ? readCredentialsFile(join(homeDir, '.config', 'claude', 'credentials.json'))
+    : null;
+
+  const candidates = [];
+  if (keychainCreds) candidates.push({ creds: keychainCreds, source: 'keychain' });
+  if (fileCreds) candidates.push({ creds: fileCreds, source: 'file' });
+  if (extraFile) candidates.push({ creds: extraFile, source: 'file' });
+  for (const c of candidates) {
+    if (!usableOnly || isUsable(c.creds, nowMs)) return c;
+  }
+  return null;
+}
+
+export function profileCommand(configDir, bin = 'claude') {
+  return `CLAUDE_CONFIG_DIR=${configDir} ${bin}`;
+}
+
+export function discoverClaudeAccounts(opts = {}) {
+  const homeDir = opts.homeDir ?? homedir();
+  const dirs = discoverClaudeConfigDirs({
+    homeDir,
+    envConfigDir: opts.envConfigDir,
+  });
+  const accounts = [];
+  const seenTokens = new Set();
+  for (const configDir of dirs) {
+    const got = readAccountCredentials(configDir, opts);
+    if (!got) continue;
+    if (seenTokens.has(got.creds.accessToken)) continue;
+    seenTokens.add(got.creds.accessToken);
+    const slug = accountSlugForConfigDir(configDir, homeDir);
+    accounts.push({
+      configDir,
+      slug,
+      pool: poolNameForSlug(slug),
+      command: profileCommand(configDir, opts.bin ?? 'claude'),
+      creds: got.creds,
+      source: got.source,
+    });
+  }
+  accounts.sort((a, b) => {
+    if (a.slug === null) return -1;
+    if (b.slug === null) return 1;
+    return a.slug.localeCompare(b.slug);
+  });
+  return accounts;
+}
+
+/**
+ * Clone the packaged `claude-code` connector once per extra login.
+ * The default home keeps the historical pool name `claude-code`.
+ * Extra homes become `claude-code:<slug>` with CLAUDE_CONFIG_DIR in env
+ * so spawn bills that seat. Discovery is filesystem-driven — never a
+ * hardcoded profile list.
+ */
+export function expandClaudeAccountConnectors(connectors, opts = {}) {
+  if (opts.disabled === true) return connectors;
+  if (process.env.BULLSWARM_DISABLE_CLAUDE_PROFILES === '1') return connectors;
+  // node:test (and MCP children it spawns) inherit NODE_TEST_CONTEXT. Do not
+  // scan the operator's real extra Claude homes unless the test injects
+  // `accounts` or `homeDir`.
+  if (process.env.NODE_TEST_CONTEXT && opts.accounts == null && opts.homeDir == null) {
+    return connectors;
+  }
+  const base = connectors['claude-code'];
+  if (!base) return connectors;
+  const accounts = opts.accounts ?? discoverClaudeAccounts({
+    homeDir: opts.homeDir,
+    envConfigDir: opts.envConfigDir,
+    bin: base.bin ?? 'claude',
+  });
+  const defaultDir = accounts.find((a) => a.slug == null)?.configDir
+    ?? defaultClaudeHome(opts.homeDir);
+  const bin = base.bin ?? 'claude';
+  base.env = { ...(base.env ?? {}), CLAUDE_CONFIG_DIR: defaultDir };
+  base.profile = {
+    slug: null,
+    configDir: defaultDir,
+    command: profileCommand(defaultDir, bin),
+  };
+  for (const account of accounts) {
+    if (!account.slug) continue;
+    const name = account.pool;
+    if (connectors[name]) continue;
+    const clone = structuredClone(base);
+    clone.name = name;
+    clone.env = { ...(base.env ?? {}), CLAUDE_CONFIG_DIR: account.configDir };
+    clone.configDirs = [account.configDir];
+    clone.flags = { ...(base.flags ?? {}), isCaller: false };
+    clone.profile = {
+      slug: account.slug,
+      configDir: account.configDir,
+      command: account.command,
+    };
+    connectors[name] = clone;
+  }
+  return connectors;
+}

package/src/lib/config.js

@@ -13,8 +13,9 @@ import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadState } from './state.js';
 import { paceScore, isQuarantined } from './route.js';
+import { expandClaudeAccountConnectors } from './claude-accounts.js';
 
-export function loadConnectors(bullswarmDir) {
+export function loadConnectors(bullswarmDir, opts = {}) {
   const dir = join(bullswarmDir, 'connectors');
   if (!existsSync(dir)) return {};
   const out = {};
@@ -28,6 +29,7 @@ export function loadConnectors(bullswarmDir) {
       // never crash a run
     }
   }
+  expandClaudeAccountConnectors(out, opts);
   return out;
 }
 

package/src/lib/watch.js

@@ -78,7 +78,12 @@ export function runDelegate(connector, taskFile, targetDir, opts = {}) {
       // hazard). Caller-supplied opts.env takes precedence over
       // process.env so the runtime can inject BULLSWARM_DEPTH (recursion
       // guard) and other core-owned env contracts.
-      env: { ...process.env, ...(opts.env ?? {}), PWD: resolvedDir },
+      env: {
+        ...process.env,
+        ...(connector.env ?? {}),
+        ...(opts.env ?? {}),
+        PWD: resolvedDir,
+      },
       stdio: ['ignore', 'pipe', 'pipe'],
     });
     opts.onSpawn?.(child.pid);

package/src/meters/claude.js

@@ -19,18 +19,24 @@ export class ClaudeMeterError extends Error {
   }
 }
 
+export const DEFAULT_KEYCHAIN_SERVICE = 'Claude Code-credentials';
+
+export function isUsable(creds, now = Date.now(), skewMs = EXPIRY_SKEW_MS) {
+  return Boolean(creds) && creds.expiresAt - skewMs > now;
+}
+
 export function readOAuthCredentials() {
   if (platform() === 'darwin') {
-    return readFromMacKeychain() ?? readFromCredentialsFile();
+    return readFromMacKeychain(DEFAULT_KEYCHAIN_SERVICE) ?? readFromCredentialsFile();
   }
   return readFromCredentialsFile();
 }
 
-function readFromMacKeychain() {
+export function readFromMacKeychain(service = DEFAULT_KEYCHAIN_SERVICE) {
   try {
     const blob = execFileSync(
       'security',
-      ['find-generic-password', '-s', 'Claude Code-credentials', '-w'],
+      ['find-generic-password', '-s', service, '-w'],
       { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' },
     );
     return extractCredentials(blob);
@@ -73,13 +79,13 @@ function normalizeWindow(raw) {
   };
 }
 
-export function parseClaudeUsage(body) {
+export function parseClaudeUsage(body, pool = 'claude-code') {
   if (!body || typeof body !== 'object') {
     throw new ClaudeMeterError('Claude usage response missing body', 'parse');
   }
   return {
     captured_at: new Date().toISOString(),
-    pool: 'claude-code',
+    pool,
     five_hour: normalizeWindow(body.five_hour) ?? { utilization: null, resets_at: null },
     seven_day: normalizeWindow(body.seven_day) ?? { utilization: null, resets_at: null },
     monthly: null,
@@ -89,12 +95,11 @@ export function parseClaudeUsage(body) {
   };
 }
 
-export async function fetchClaudeUsage() {
-  const creds = readOAuthCredentials();
+export async function fetchClaudeUsageWithCredentials(creds, pool = 'claude-code') {
   if (!creds) {
     throw new ClaudeMeterError('No Claude Code OAuth token. Run `claude` to log in.', 'no_token');
   }
-  if (creds.expiresAt - EXPIRY_SKEW_MS <= Date.now()) {
+  if (!isUsable(creds)) {
     throw new ClaudeMeterError(
       'Claude OAuth token expired; open Claude Code to refresh it.',
       'expired',
@@ -122,5 +127,9 @@ export async function fetchClaudeUsage() {
   } catch (err) {
     throw new ClaudeMeterError(`Failed to parse usage response: ${err.message}`, 'parse');
   }
-  return parseClaudeUsage(body);
+  return parseClaudeUsage(body, pool);
+}
+
+export async function fetchClaudeUsage() {
+  return fetchClaudeUsageWithCredentials(readOAuthCredentials(), 'claude-code');
 }

package/src/meters/registry.js

@@ -6,7 +6,8 @@ import { MeterCache, paceSnapshot, FRESH_MS, STALE_MS } from './framework.js';
 import { fetchCodexUsage, CodexMeterError } from './codex.js';
 import { fetchGrokUsage, GrokMeterError } from './grok.js';
 import { fetchCommandCodeUsage, CommandCodeMeterError } from './command-code.js';
-import { fetchClaudeUsage, ClaudeMeterError } from './claude.js';
+import { fetchClaudeUsage, fetchClaudeUsageWithCredentials, ClaudeMeterError } from './claude.js';
+import { discoverClaudeAccounts, poolNameForSlug } from '../lib/claude-accounts.js';
 
 export const METERS_DIR = () =>
   process.env.BULLSWARM_HOME?.trim() || join(homedir(), '.bullswarm');
@@ -19,7 +20,26 @@ const READERS = {
   claude: fetchClaudeUsage,
 };
 
+function claudeReaderFor(pool) {
+  return async () => {
+    const accounts = discoverClaudeAccounts();
+    const slug = pool.startsWith('claude-code:') ? pool.slice('claude-code:'.length) : null;
+    const account = accounts.find((a) => poolNameForSlug(a.slug) === pool)
+      ?? accounts.find((a) => a.slug === slug);
+    if (!account) {
+      throw new ClaudeMeterError(
+        `No Claude Code OAuth token for pool ${pool}. Log in with CLAUDE_CONFIG_DIR pointing at that home.`,
+        'no_token',
+      );
+    }
+    return fetchClaudeUsageWithCredentials(account.creds, pool);
+  };
+}
+
 export function readerFor(pool) {
+  if (pool === 'claude-code' || pool === 'claude' || pool.startsWith('claude-code:')) {
+    return claudeReaderFor(pool);
+  }
   return READERS[pool] ?? null;
 }
 

package/src/workflow/cli.js

@@ -340,7 +340,7 @@ async function wfGoal(opts) {
     try {
       doc = existsSync(workflowPath)
         ? JSON.parse(readFileSync(workflowPath, 'utf8'))
-        : JSON.parse(readFileSync(statePath, 'utf8'))._doc;
+        : readJsonForUpdate(statePath, 'workflow state')._doc;
     } catch (err) {
       console.error(`✗ cannot load durable workflow for ${resumeRunId}: ${err.message}`);
       return 1;
@@ -457,6 +457,8 @@ async function wfCapabilities(opts) {
       enabled: p.enabled !== false,
       lanes: p.lanes ?? p.connector?.lanes ?? [],
       capabilities: p.capabilities ?? p.connector?.capabilities ?? [],
+      command: p.connector?.profile?.command ?? p.connector?.spawn?.cmd?.[0] ?? null,
+      configDir: p.connector?.profile?.configDir ?? p.connector?.env?.CLAUDE_CONFIG_DIR ?? null,
       model: (() => {
         const cmd = p.connector?.spawn?.cmd ?? [];
         const i = cmd.indexOf('--model');

package/src/workflow/dashboard.js

@@ -1,7 +1,8 @@
 // Interactive workflow dashboard, inspired by Claude Code's /workflows view.
 // It deliberately uses only ANSI sequences and Node's standard streams.
 
-import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
+import { readJsonSafe, readJsonForUpdate, writeJsonAtomic } from './fsjson.js';
 import { fanoutSucceededCount } from './runner.js';
 import { join } from 'node:path';
 import { listRuns, resolveRunId } from './short-id.js';
@@ -44,7 +45,7 @@ export function requestCancel(bullswarmDir, token) {
   if (!resolved) throw new Error(`no run found for "${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'));
+  const state = readJsonForUpdate(statePath, 'workflow state');
   if (state.finishedAt || isTerminalWorkflowStatus(state.status)) {
     return { ...resolved, state, alreadyFinished: true };
   }
@@ -53,7 +54,7 @@ export function requestCancel(bullswarmDir, token) {
   state.status = 'cancelling';
   state.cancellingAt = state.cancelRequestedAt;
   appendEvent(resolved.runDir, state, 'run.cancellation_requested', { requestedAt: state.cancelRequestedAt });
-  writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+  writeJsonAtomic(statePath, state);
   return { ...resolved, state, alreadyFinished: false };
 }
 
@@ -228,6 +229,12 @@ function autonomousControlPlane(state) {
 }
 
 function effectiveActionStatus(action, state) {
+  // A re-running action (repair round, re-verify, schema retry) must read as
+  // running even when a previous round recorded ok:false — a failed mark on
+  // work that is still being retried misreports the run (user report 2026-08-29).
+  const active = Object.values(state.activeAgents ?? {}).some((agent) =>
+    agent.stepId === action.id || String(agent.stepId ?? '').startsWith(`${action.id}[`));
+  if (active || action.status === 'running') return 'running';
   const output = state.outputs?.[action.id];
   if (output?.ok === false) return 'failed_terminal';
   if (output?.ok === true && action.status === 'succeeded') return 'succeeded';
@@ -282,9 +289,10 @@ export function workflowPanelModel(row, {
     const failed = effectiveStatuses.filter((status) => String(status).startsWith('failed')).length;
     const current = name === activePhaseName && !state.finishedAt;
     const active = effectiveStatuses.some((status) => status === 'running');
-    const status = failed ? 'failed'
-      : actions.length && completed === actions.length ? 'completed'
-        : active ? 'active' : current ? 'waiting' : 'pending';
+    const status = active ? 'active'
+      : failed ? 'failed'
+        : actions.length && completed === actions.length ? 'completed'
+          : current ? 'waiting' : 'pending';
     return { name, label: phaseLabel(name, orchestrator), status, actions, completed, total: actions.length };
   });
   const selectedPhase = phases[selectedPhaseIndex];
@@ -806,8 +814,8 @@ function detailRow(bullswarmDir, token) {
   if (!resolved) throw new Error(`no run found for "${token}"`);
   const statePath = join(resolved.runDir, 'state.json');
   const reportPath = join(resolved.runDir, 'report.json');
-  const state = existsSync(statePath) ? JSON.parse(readFileSync(statePath, 'utf8')) : null;
-  const report = existsSync(reportPath) ? JSON.parse(readFileSync(reportPath, 'utf8')) : null;
+  const state = readJsonSafe(statePath);
+  const report = readJsonSafe(reportPath);
   return { ...resolved, state, report, events: readEvents(resolved.runDir), status: state?.status };
 }
 
@@ -823,6 +831,7 @@ export async function runDashboard(bullswarmDir, {
   let selected = 0;
   let detail = Boolean(token);
   let message = null;
+  let lastGoodRow = null;
   let rows = dashboardRows(bullswarmDir);
   let selectedRunId = token ? detailRow(bullswarmDir, token).runId : (rows[selected]?.runId ?? null);
   const ui = {
@@ -838,10 +847,14 @@ export async function runDashboard(bullswarmDir, {
     orchestratorVerbose: false,
     spinnerFrame: 0,
   };
-  const paint = () => {
+  const paintUnsafe = () => {
     if (selected >= rows.length) selected = Math.max(0, rows.length - 1);
     if (detail && selectedRunId) {
-      const row = detailRow(bullswarmDir, selectedRunId);
+      // A torn read while the runner writes state.json yields state:null for
+      // one frame — keep painting the last good snapshot of the same run.
+      const fresh = detailRow(bullswarmDir, selectedRunId);
+      const row = (fresh.state || lastGoodRow?.runId !== fresh.runId) ? fresh : lastGoodRow;
+      if (row === fresh) lastGoodRow = fresh;
       const model = workflowPanelModel(row, {
         phaseIndex: ui.followActivePhase ? null : ui.phaseIndex,
         agentIndex: ui.followActiveAgent ? null : ui.agentIndex,
@@ -858,8 +871,19 @@ export async function runDashboard(bullswarmDir, {
     }
     output.write(renderDashboard({ rows, selected, message }));
   };
+  // A render error must never kill the TUI or strand the terminal in
+  // alt-screen raw mode (crash observed 2026-08-29 at detailRow via the
+  // repaint timer). Show the error in the message line and keep running.
+  const paint = () => {
+    try { paintUnsafe(); } catch (err) {
+      message = `display error: ${err.message}`;
+      try { output.write(renderDashboard({ rows, selected, message })); } catch { /* keep the loop alive */ }
+    }
+  };
   const refresh = () => {
-    rows = dashboardRows(bullswarmDir);
+    try {
+      rows = dashboardRows(bullswarmDir);
+    } catch (err) { message = `display error: ${err.message}`; }
     if (!selectedRunId) selectedRunId = rows[selected]?.runId ?? null;
     paint();
   };
@@ -935,7 +959,7 @@ export async function runDashboard(bullswarmDir, {
         refresh();
       } catch (err) { message = err.message; ui.confirmCancel = false; paint(); }
     };
-    const onData = (buf) => {
+    const onDataUnsafe = (buf) => {
       const key = String(buf);
       if (ui.confirmCancel) {
         if (key === 'y' || key === 'Y') return requestSelectedCancel();
@@ -1019,6 +1043,14 @@ export async function runDashboard(bullswarmDir, {
         return paint();
       }
     };
+    const onData = (buf) => {
+      // A key-handler error (e.g. a drill-in racing the writer) must never
+      // kill the TUI; finish() still restores the terminal on q/Ctrl-C.
+      try { onDataUnsafe(buf); } catch (err) {
+        message = `display error: ${err.message}`;
+        paint();
+      }
+    };
     const onResize = () => paint();
     input.on('data', onData);
     output.on?.('resize', onResize);
@@ -1035,8 +1067,8 @@ export function dashboardJson(bullswarmDir, { all = false, token = null, cancel
     if (!resolved) throw new Error(`no run found for "${token}"`);
     const statePath = join(resolved.runDir, 'state.json');
     const reportPath = join(resolved.runDir, 'report.json');
-    const state = existsSync(statePath) ? JSON.parse(readFileSync(statePath, 'utf8')) : null;
-    const report = existsSync(reportPath) ? JSON.parse(readFileSync(reportPath, 'utf8')) : null;
+    const state = readJsonSafe(statePath);
+    const report = readJsonSafe(reportPath);
     const events = readEvents(resolved.runDir);
     return { action: 'show', ...resolved, state, report, events };
   }
@@ -1048,7 +1080,7 @@ export function actionJson(bullswarmDir, token, actionId) {
   const resolved = resolveRunId(bullswarmDir, token);
   if (!resolved) throw new Error(`no run found for "${token}"`);
   const statePath = join(resolved.runDir, 'state.json');
-  const state = existsSync(statePath) ? JSON.parse(readFileSync(statePath, 'utf8')) : null;
+  const state = readJsonSafe(statePath);
   const action = state?.actionLedger?.find((entry) => entry.id === actionId);
   if (!action) throw new Error(`run "${token}" has no action "${actionId}"`);
   const attempts = (action.attempts ?? []).map((index) => state.attempts?.[index]).filter(Boolean);
@@ -1062,7 +1094,7 @@ export function decideApproval(bullswarmDir, token, decision) {
   const resolved = resolveRunId(bullswarmDir, token);
   if (!resolved) throw new Error(`no run found for "${token}"`);
   const statePath = join(resolved.runDir, 'state.json');
-  const state = JSON.parse(readFileSync(statePath, 'utf8'));
+  const state = readJsonForUpdate(statePath, 'workflow state');
   if (state.status !== 'waiting_for_approval' || !state.approval) {
     throw new Error(`run "${token}" is not waiting for approval`);
   }
@@ -1085,6 +1117,6 @@ export function decideApproval(bullswarmDir, token, decision) {
     gateId: state.approval.gateId,
     decidedAt: at,
   });
-  writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+  writeJsonAtomic(statePath, state);
   return { ...resolved, decision, state };
 }

package/src/workflow/decision.js

@@ -72,10 +72,20 @@ export function normalizeDecisionProposal(proposal) {
         };
       }
       if (action?.type !== 'verify') return action;
-      const singleDependency = Array.isArray(action.dependsOn) && action.dependsOn.length === 1
-        ? action.dependsOn[0] : null;
+      const dependsOn = Array.isArray(action.dependsOn) ? action.dependsOn : [];
+      const singleDependency = dependsOn.length === 1 ? dependsOn[0] : null;
       if (action.review == null) {
-        return singleDependency ? { ...action, review: `outputs.${singleDependency}.outFile` } : action;
+        // A verify reviews an artifact; when the planner names none, take the
+        // obvious one instead of rejecting a whole program for one field
+        // (observed 2026-08-29: a 9-action proposal bounced for a
+        // zero-dependency audit verify, costing a 5-minute correction turn).
+        // One dependency -> its artifact. Several -> the most downstream
+        // (last listed). None -> a repository audit with no artifact.
+        if (singleDependency) return { ...action, review: `outputs.${singleDependency}.outFile` };
+        if (dependsOn.length > 1) {
+          return { ...action, review: `outputs.${dependsOn.at(-1)}.outFile`, reviewDefaultedFrom: 'last-dependency' };
+        }
+        return { ...action, reviewScope: 'repository' };
       }
       if (looksLikeReviewPath(action.review)) return { ...action, review: action.review.trim() };
       if (typeof action.review === 'string' && singleDependency) {
@@ -241,8 +251,10 @@ export function validateDecisionProposal(proposal, {
       }
     }
     if (action.type === 'verify') {
-      if (typeof action.review !== 'string') {
-        issues.push(`${at}.review is required: a verify with one dependsOn reviews that artifact automatically; with several, set review to "outputs.<actionId>.outFile" and put reviewer instructions in prompt`);
+      if (action.review == null && action.reviewScope === 'repository') {
+        // Normalized zero-dependency audit: no artifact to review.
+      } else if (typeof action.review !== 'string') {
+        issues.push(`${at}.review must be a dotted artifact path like "outputs.<actionId>.outFile" when present; omit it to review the single/last dependency's artifact, or to audit the repository when the verify has no dependsOn`);
       } else if (!looksLikeReviewPath(action.review)) {
         issues.push(`${at}.review must be a dotted artifact path like "outputs.<actionId>.outFile" (the artifact to review), not instructions or a filesystem path; put reviewer instructions in ${at}.prompt`);
       } else {

package/src/workflow/draft.js

@@ -58,12 +58,8 @@ export function draftPaths(bullswarmDir, name) {
   return { dir: d, doc: join(d, 'workflow.json'), meta: join(d, 'meta.json') };
 }
 
-function atomicWrite(p, content) {
-  mkdirSync(dirname(p), { recursive: true });
-  const tmp = `${p}.tmp-${randomBytes(3).toString('hex')}`;
-  writeFileSync(tmp, content);
-  renameSync(tmp, p);
-}
+// Hoisted to fsjson.js (shared with runtime/runner state persistence).
+import { atomicWriteFileSync as atomicWrite } from './fsjson.js';
 
 export function draftExists(bullswarmDir, name) {
   return existsSync(draftPaths(bullswarmDir, name).doc);

package/src/workflow/fsjson.js

@@ -0,0 +1,41 @@
+// Atomic JSON persistence + torn-read-tolerant JSON reads.
+//
+// Doctrine:
+//   F1. Every state/report/workflow artifact is written via temp+rename so a
+//       concurrent reader can NEVER observe a half-written file (earned:
+//       `bullswarm workflow tui` crashed with "Unterminated string in JSON at
+//       position 138968" parsing state.json mid-write, 2026-08-29).
+//   F2. Display readers tolerate a missing or torn file (returns fallback):
+//       observation must never crash on the writer's timing.
+//   F3. Mutating read-modify-write readers must NOT silently no-op: they
+//       retry once (rename-atomic writes make the second read succeed) and
+//       then throw a clear error instead of dropping the user's command.
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+export function atomicWriteFileSync(path, content) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp-${randomBytes(3).toString('hex')}`;
+  writeFileSync(tmp, content);
+  renameSync(tmp, path);
+}
+
+export function writeJsonAtomic(path, value) {
+  atomicWriteFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+/** Display-path read: missing or torn file -> fallback, never a throw. */
+export function readJsonSafe(path, fallback = null) {
+  if (!existsSync(path)) return fallback;
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+/** Mutating-path read: retry once, then throw a clear actionable error. */
+export function readJsonForUpdate(path, what = 'file') {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { /* torn or corrupt; retry once */ }
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch (err) {
+    throw new Error(`${what} at ${path} is unreadable (${err.message}); it may be mid-write — retry the command`);
+  }
+}

package/src/workflow/goal.js

@@ -11,11 +11,11 @@ export const PLANNER_RULES_SECTION = [
   '1. Compile the whole program in one decision: the runtime executes all proposed actions and consults you only at a finished-or-blocked boundary, so deferring decidable work costs another round trip.',
   '2. Make every worker prompt self-contained: include the exact goal, absolute cwd, owned files and a no-other-files boundary, expected artifact, acceptance command, and report format, because workers see only their own prompt.',
   '3. Use short kebab-case, forward-only phases and dependsOn only for real data or same-file ordering; recovery uses a new phase and never repeats an identical failed plan.',
-  '4. For known N items, create N run plus N verify actions, each verify depending only on its own run, then one suite verify depending on all; this exposes safe parallelism while preserving per-item evidence.',
+  '4. For known N items, create N run plus N verify actions, each verify depending only on its own run, then one suite verify depending on all; a verify judges the artifact in review (default: its single or last dependency; a verify with no dependsOn audits the repository directly).',
   '5. For unknown items, create discovery ending with RETURN ONLY a JSON object containing an items array, then data-driven fan-out via itemsFrom outputs.<id>.outFile or outputs.<id>.data.<field>; the runtime extracts the list and retries once read-only if needed.',
   '6. Put outputSchema on workers whose reports are consumed or whose claims the runtime must check, so structured data is durable and can drive later fan-out.',
   '7. Put verify.repair on every verify, and scope each verify to what can be true at its point in the graph: work scheduled later is not a defect, and cosmetic mismatches with the goal text are concerns, never ok:false. An ok:false verdict is repaired and re-checked inside the program; ok:true is accepted and concerns are informational, not extra work.',
-  '8. Add completion with all-actions-ok whenever a clean program finishes the goal; when the goal\'s acceptance checks pass, return complete rather than adding polish or alignment actions. Return complete only on durable verified evidence, never proceed, never ask the user, and stop only for a concrete unresolved blocker with a qualified outcome.',
+  '8. Add completion with all-actions-ok whenever a clean program finishes the goal; when the goal\'s acceptance checks pass, return complete rather than adding polish or alignment actions. Completion evidence requires the program\'s LAST worker to be covered by a successful verify — never leave a report or other run as the final unverified action. Return complete only on durable verified evidence, never proceed, never ask the user, and stop only for a concrete unresolved blocker with a qualified outcome.',
   '9. Treat agent-count, workflow-duration, and expansion-round budgets as advisory planning targets, never hard stop conditions; the dispatch budget counts this planner call plus workers, verifiers, retries, and escalations. Converge as targets approach, avoid optional work, and exceed a target only for one essential bounded action or required verification.',
   '10. This is a control-plane thread: do not invoke Bullswarm, use tools, modify files, or propose pool, addDir, taskFile, shell authority, or unbounded work; route and process authority belong to the runtime.',
   'Shared working tree: concurrent workers editing DISJOINT files is the normal parallel mode; order shared files (indexes, barrels) after their feeders with dependsOn, and run the full suite once in a final verify — never while other workers still edit. Avoid redundant expensive verification: later verifiers reuse durable clean full-suite evidence unless it is stale or the code changed again. operatorSteering in the context is explicit operator guidance for this checkpoint: apply it within the original intent; it cannot weaken verification or expand authority.',
@@ -26,7 +26,7 @@ export const PLANNER_EXAMPLES_SECTION = [
   '[{"type":"run","phase":"implement","prompt":"..."},{"type":"run","phase":"report","prompt":"...","outputSchema":{"type":"object"}},{"type":"fanout","phase":"fix","items":["alpha"],"stepTemplate":{"prompt":"Handle {{item}}."}},{"type":"fanout","phase":"fix","itemsFrom":"outputs.discover.outFile","stepTemplate":{"prompt":"Handle {{item}}."}},{"type":"verify","phase":"verify","prompt":"Check the artifact.","repair":{"prompt":"Fix rejected concerns.","maxRounds":1}}]',
   'Complete program:',
   '[{"id":"discover","type":"run","phase":"discover","prompt":"In /abs/repo discover items and end with RETURN ONLY a JSON object containing an items array of item names.","outputSchema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"string"}}},"required":["items"]}},{"id":"fix","type":"fanout","phase":"fix","itemsFrom":"outputs.discover.data.items","stepTemplate":{"prompt":"In /abs/repo edit only the files for {{item}} and run its focused acceptance command."},"dependsOn":["discover"]},{"id":"verify-items","type":"verify","phase":"verify-items","prompt":"Independently verify every item artifact.","dependsOn":["fix"],"repair":{"prompt":"Fix each rejected item in /abs/repo and re-run its focused command.","maxRounds":2}},{"id":"verify-suite","type":"verify","phase":"verify-suite","prompt":"Run the full acceptance command in /abs/repo.","dependsOn":["verify-items"],"repair":{"prompt":"Fix the suite failure in /abs/repo and rerun the suite.","maxRounds":1}}],"completion":{"when":"all-actions-ok","reason":"The item checks and final suite verification prove the goal."}]',
-  'Rules the validator enforces: action type is run, fanout, or verify; fanout has stepTemplate and either items or itemsFrom; verify.review is a string when explicit review is needed; dependsOn names existing or proposed actions; runtime-owned fields are rejected.',
+  'Rules the validator enforces: action type is run, fanout, or verify; fanout has stepTemplate and either items or itemsFrom; verify.review, when given, is outputs.<id>.outFile; dependsOn names existing or proposed actions; runtime-owned fields are rejected.',
 ].join('\n');
 
 export const AUTONOMOUS_ORCHESTRATOR_PROMPT = [

package/src/workflow/runner.js

@@ -5,7 +5,9 @@
 //   settings.stopOnPhaseFailure: abort after a phase with any failure
 // Resume: steps whose recorded verdict is ok:true are skipped (R2).
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { writeJsonAtomic } from './fsjson.js';
+import { readSteering } from './steering.js';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { validateWorkflow } from './validate.js';
@@ -91,7 +93,7 @@ export async function runWorkflow(opts) {
     // A generated goal workflow must be restartable without the initiating
     // process or an external draft file. The exact executable definition is
     // therefore a first-class run artifact.
-    writeFileSync(join(runDir, 'workflow.json'), `${JSON.stringify(doc, null, 2)}\n`);
+    writeJsonAtomic(join(runDir, 'workflow.json'), doc);
   }
 
   let state;
@@ -142,7 +144,7 @@ export async function runWorkflow(opts) {
     // 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`);
+    writeJsonAtomic(join(runDir, 'state.json'), state);
   } else {
     if (resuming) {
       throw new Error(`cannot resume: no state.json for run ${runId}`);
@@ -221,7 +223,7 @@ export async function runWorkflow(opts) {
     state.orchestration = doc.orchestration
       ? { ...(state.orchestration ?? {}), ...doc.orchestration }
       : state.orchestration;
-    writeFileSync(join(runDir, 'workflow.json'), `${JSON.stringify(doc, null, 2)}\n`);
+    writeJsonAtomic(join(runDir, 'workflow.json'), doc);
   }
   if (opts.inputs && Object.keys(opts.inputs).length) {
     state.inputs = { ...state.inputs, ...opts.inputs };
@@ -447,6 +449,20 @@ export async function runWorkflow(opts) {
     state.recovery = { resumable: true, signal: interruptionSignal, interruptedAt: finishedAt };
   }
   if (abortReason && !interrupted) state.abortReason = abortReason;
+  // Steering queued after the last planner gate must end truthfully: on a
+  // real terminal transition (not interrupted — a resume still has gates
+  // ahead — and not waiting for approval), mark undelivered entries expired.
+  if (!waitingForApproval && !interrupted) {
+    const undelivered = readSteering(runDir).filter((entry) =>
+      !(state.steering ?? []).some((known) => known.id === entry.id));
+    if (undelivered.length) {
+      state.steering = [
+        ...(state.steering ?? []),
+        ...undelivered.map((entry) => ({ ...entry, status: 'expired_undelivered', expiredAt: finishedAt })),
+      ];
+      runtime.emit('steering.expired', { steeringIds: undelivered.map((entry) => entry.id) });
+    }
+  }
   runtime.persist();
 
   const preliminaryReport = buildReport(state, doc, runDir);
@@ -456,7 +472,7 @@ export async function runWorkflow(opts) {
         : state.status === 'blocked' ? 'run.blocked' : 'run.completed';
   runtime.emit(terminalEvent, { runId, status: state.status, report: preliminaryReport.summary, outcome: state.outcome ?? null });
   const report = buildReport(state, doc, runDir);
-  writeFileSync(join(runDir, 'report.json'), `${JSON.stringify(report, null, 2)}\n`);
+  writeJsonAtomic(join(runDir, 'report.json'), report);
   opts.onEvent?.({ type: 'workflow.completed', runId, status: state.status, report: report.summary });
 
   return { runId, runDir, state, report };
@@ -845,6 +861,41 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
 
   // Resume accepted expansion work before asking the planner for a new
   // semantic decision. Successful actions are skipped by durable output.
+  // An action the interruption cancelled mid-flight (status `cancelled`,
+  // output `ok:false` "workflow cancellation requested") is unfinished work,
+  // not a failure: clear its output so it re-runs, and clear the outputs of
+  // the dependents that were blocked only because of it — otherwise resume
+  // asks the planner to re-plan around a phantom failure (observed on run
+  // djnjka, 2026-08-29: 1 cancelled action → 4 "blocked" → spurious turn).
+  const ledgerById = new Map((state.actionLedger ?? []).map((entry) => [entry.id, entry]));
+  const reopened = new Set();
+  for (const entry of state.plan?.actions ?? []) {
+    if (entry.source !== 'planner' || !entry.definition) continue;
+    if (ledgerById.get(entry.id)?.status === 'cancelled') reopened.add(entry.id);
+  }
+  let grew = reopened.size > 0;
+  while (grew) {
+    grew = false;
+    for (const entry of state.plan?.actions ?? []) {
+      if (entry.source !== 'planner' || !entry.definition || reopened.has(entry.id)) continue;
+      const blocked = state.outputs[entry.id]?.dependencyBlocked === true;
+      if (blocked && (entry.definition.dependsOn ?? []).some((id) => reopened.has(id))) {
+        reopened.add(entry.id);
+        grew = true;
+      }
+    }
+  }
+  for (const id of reopened) {
+    delete state.outputs[id];
+    const ledger = ledgerById.get(id);
+    if (ledger) {
+      ledger.status = 'pending';
+      delete ledger.why;
+      delete ledger.finishedAt;
+    }
+    runtime.emit('action.reopened', { actionId: id, reason: 'interrupted before completion' });
+  }
+  if (reopened.size) runtime.persist();
   const unfinishedAccepted = (state.plan?.actions ?? [])
     .filter((entry) => entry.source === 'planner' && entry.definition &&
       state.outputs[entry.id] == null)
@@ -1077,7 +1128,13 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
         .map((entry) => entry.id);
       const dynamicActions = (state.actionLedger ?? []).filter((action) => action.parentId === gate.id);
       const gaps = failing.length ? [] : completionEvidenceGaps(dynamicActions, state.orchestration?.completionPolicy, state.outputs);
-      if (!failing.length && !gaps.length) {
+      // Pending operator steering blocks self-completion: the documented
+      // contract is delivery at the next planner gate, so a clean program
+      // returns to the planner (which delivers the steer) instead of
+      // silently discarding it (defect observed on wf-mtds7tzx, 2026-08-29).
+      const pendingSteering = (failing.length || gaps.length) ? [] : readSteering(runtime.runDir).filter((entry) =>
+        !(state.steering ?? []).some((known) => known.id === entry.id));
+      if (!failing.length && !gaps.length && !pendingSteering.length) {
         const verifyIds = programActions.filter((entry) => entry.kind === 'verify').map((entry) => entry.id);
         const reason = proposal.completion.reason?.trim()
           || `Program completed: all ${programActions.length} actions finished ok, verified by ${verifyIds.join(', ')}.`;
@@ -1114,9 +1171,18 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
         runtime.persist();
         return { ok: true, why: reason, complete: true, decision: { decision: 'complete', reason, actions: [], completion: proposal.completion } };
       }
-      runtime.emit('decision.completion_predicate_unmet', {
-        gateId: gate.id, programSequence: decision.sequence, failing, gaps,
-      });
+      if (pendingSteering.length) {
+        runtime.emit('decision.completion_deferred', {
+          gateId: gate.id,
+          programSequence: decision.sequence,
+          reason: 'operator steering pending',
+          steeringIds: pendingSteering.map((entry) => entry.id),
+        });
+      } else {
+        runtime.emit('decision.completion_predicate_unmet', {
+          gateId: gate.id, programSequence: decision.sequence, failing, gaps,
+        });
+      }
     }
     // Loop intentionally returns to observation and invokes the planner again.
   }

package/src/workflow/runs-cli.js

@@ -14,6 +14,7 @@
 // resolver in short-id.js maps both to the run directory.
 
 import { existsSync, rmSync, readFileSync } from 'node:fs';
+import { readJsonSafe } from './fsjson.js';
 import { join } from 'node:path';
 import { listRuns, resolveRunId, isOngoing } from './short-id.js';
 import { BULLSWARM_DIR } from './cli.js';
@@ -161,8 +162,8 @@ function runsShow(idToken, opts) {
   const { runId, runDir } = resolved;
   const statePath = join(runDir, 'state.json');
   const reportPath = join(runDir, 'report.json');
-  const state = existsSync(statePath) ? JSON.parse(readFileSync(statePath, 'utf8')) : null;
-  const report = existsSync(reportPath) ? JSON.parse(readFileSync(reportPath, 'utf8')) : null;
+  const state = readJsonSafe(statePath);
+  const report = readJsonSafe(reportPath);
   const ongoing = isOngoing(runDir, state);
 
   if (opts.json) {
@@ -191,8 +192,8 @@ function runsResult(idToken, opts) {
   const { runId, runDir } = resolved;
   const statePath = join(runDir, 'state.json');
   const reportPath = join(runDir, 'report.json');
-  const state = existsSync(statePath) ? JSON.parse(readFileSync(statePath, 'utf8')) : null;
-  const report = existsSync(reportPath) ? JSON.parse(readFileSync(reportPath, 'utf8')) : null;
+  const state = readJsonSafe(statePath);
+  const report = readJsonSafe(reportPath);
   const ongoing = isOngoing(runDir, state);
   const result = buildWorkflowResult({
     state, report, runId, shortId: resolved.shortId, ongoing,
@@ -246,8 +247,15 @@ function runsDelete(idToken, opts, rest) {
   // Refuse to delete an ongoing run without --force. Half-finished
   // runs are usually a debugging target, not garbage.
   const statePath = join(runDir, 'state.json');
-  const state = existsSync(statePath) ? JSON.parse(readFileSync(statePath, 'utf8')) : null;
-  const ongoing = isOngoing(runDir, state);
+  // Delete guard: an unreadable (mid-write) state means the run may be live —
+  // treat it as ongoing rather than deleting a live run; --force still wins.
+  let state = null;
+  let stateUnreadable = false;
+  if (existsSync(statePath)) {
+    state = readJsonSafe(statePath, undefined);
+    if (state === undefined) { state = null; stateUnreadable = true; }
+  }
+  const ongoing = stateUnreadable ? true : isOngoing(runDir, state);
   if (ongoing && !opts.force) {
     return err(
       `refusing to delete ongoing run "${runId}" (shortId ${shortId ?? '?'}); ` +

package/src/workflow/runtime.js

@@ -22,6 +22,7 @@
 //       text always lives in the per-step outFile.
 
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { writeJsonAtomic } from './fsjson.js';
 import { join } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { pickPool, isQuarantined } from '../lib/route.js';
@@ -92,6 +93,24 @@ export function plannerBudgetContext(budget = {}) {
   };
 }
 
+/** Skeleton of a rejected planner proposal: shapes and ids, prompts elided. */
+export function compactRejectedProposal(proposal) {
+  if (!proposal || typeof proposal !== 'object') return proposal ?? null;
+  const elide = (text) => (typeof text === 'string' && text.length > 160 ? `${text.slice(0, 160)}…[${text.length} chars]` : text);
+  return {
+    ...proposal,
+    reason: elide(proposal.reason),
+    actions: Array.isArray(proposal.actions) ? proposal.actions.map((action) => {
+      if (!action || typeof action !== 'object') return action;
+      const out = { ...action };
+      if ('prompt' in out) out.prompt = elide(out.prompt);
+      if (out.repair && typeof out.repair === 'object') out.repair = { ...out.repair, prompt: elide(out.repair.prompt) };
+      if (out.stepTemplate && typeof out.stepTemplate === 'object') out.stepTemplate = { ...out.stepTemplate, prompt: elide(out.stepTemplate.prompt) };
+      return out;
+    }) : proposal.actions,
+  };
+}
+
 export class WorkflowRuntime {
   /**
    * @param {object} opts
@@ -184,7 +203,8 @@ export class WorkflowRuntime {
         if (disk.cancellingAt) this.state.cancellingAt = disk.cancellingAt;
       }
     } catch { /* a partial state file should not break the workflow */ }
-    writeFileSync(join(this.runDir, 'state.json'), `${JSON.stringify(this.state, null, 2)}\n`);
+    // Atomic: a 1s-interval TUI reads this file while we write it (F1).
+    writeJsonAtomic(join(this.runDir, 'state.json'), this.state);
   }
 
   refreshCancellation() {
@@ -1036,13 +1056,16 @@ export class WorkflowRuntime {
    */
   async runVerify(step, scope, opts = {}) {
     this.enforceRequiredInputs(step.id);
-    if (!step.review) {
+    if (!step.review && step.reviewScope !== 'repository') {
       throw new Error(
         `verify step "${step.id}" needs a "review" path ` +
         `(e.g. review: "outputs.<priorStep>.outFile")`,
       );
     }
     const reviewedText = (() => {
+      if (!step.review) {
+        return '(no artifact: this verify has no upstream action — audit the repository state directly with fresh commands)';
+      }
       try {
         // `review` is a dotted path into the scope, NOT a template
         // (matches the design of `fanout.itemsFrom`). Resolve it the
@@ -1297,8 +1320,14 @@ export class WorkflowRuntime {
         maxAttempts: opts.correction.maxAttempts,
         why: opts.correction.why,
         issues: opts.correction.issues ?? [],
-        rejectedProposal: opts.correction.rejectedProposal ?? null,
-        rejectedResponseExcerpt: opts.correction.rejectedResponse ?? null,
+        // The planner's own thread already holds the full rejected proposal
+        // (worker prompts included); resend only its skeleton so a corrective
+        // turn cannot re-inflate the compacted context (observed: 38k-char
+        // validationFeedback on run 4t6m5a, 37k of it the verbatim proposal).
+        rejectedProposal: compactRejectedProposal(opts.correction.rejectedProposal),
+        rejectedResponseExcerpt: typeof opts.correction.rejectedResponse === 'string'
+          ? opts.correction.rejectedResponse.slice(0, 2000)
+          : null,
       } : null,
       operatorSteering: (this.state.steering ?? []).map((entry) => ({
         id: entry.id,

package/src/workflow/short-id.js

@@ -16,7 +16,8 @@
 // not the generator.
 
 import { randomBytes } from 'node:crypto';
-import { readdirSync, readFileSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { writeJsonAtomic } from './fsjson.js';
 import { join } from 'node:path';
 import { appendEvent } from './events.js';
 import { aggregateUsage } from '../lib/usage.js';
@@ -235,7 +236,7 @@ export function reconcileInterruptedRun(runDir, state, {
   delete state.currentPhase;
   delete state.currentStep;
   appendEvent(runDir, state, 'run.interrupted_reconciled', { reason, resumable: true });
-  writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+  writeJsonAtomic(statePath, state);
   return state;
 }