bullswarm 0.38.3 → 0.38.6

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 0.38.6 — no import cycles
+
+- internal: no module under `src/` imports itself back through its imports any more (13 import cycles removed by moving four small helpers into their own files; `reprice`'s command-line part is now `src/workflow/reprice-cli.js`). Behaviour is unchanged; a new test fails if a cycle comes back.
+
+## 0.38.5 — plan validate --try-checks (0.38.4 republished)
+
+- release: 0.38.4 was tagged but never published to npm (a test read only the `## Unreleased` changelog section, which the release empties); 0.38.5 ships 0.38.4's changes. The docs site builds again: three wrapped lines that began with a `<placeholder>` were read as HTML.
+
+## 0.38.4 — plan validate --try-checks
+
+- plan validate: `--try-checks` runs each step's command check once, now,
+  against the current tree, the way a step runs it (same shell, folder,
+  environment and timeout), and prints one `try` line per check with its exit
+  and last output line (or `timed out after <n>s`) and the names of any files
+  it changed, ignored files and folders outside git included. A check that
+  exits non-zero or times out also prints the last 20 lines of its output,
+  indented under the try line, so the error is visible. A check that reads the step's output is not tried, and the results never
+  change the exit code. Without the flag validate still runs nothing; when the
+  program has command checks it now says so (`checks   not run · add
+  --try-checks …`, and `checks: {tried: false, commands}` in `--json`). Use it
+  for checks that are safe to run now: a missing module or command on a `try`
+  line means the check itself is wrong.
+- docs: `workflow step accept` on a failed step inside a loop does not end the
+  loop; to stop a loop early let it run out of rounds, then
+  `workflow continue <run> <loop>` (recorded as condition not met).
+
 ## 0.38.3 — Blind reviews and a reorganized skill
 
 - steps: a v3 step may declare `"blindTo": ["<step id>", ...]`, naming steps

package/docs/guide/observing.md

@@ -264,8 +264,8 @@ A real run on grok, parked at its gate, on the Run page at 120 columns:
   continued without more rounds reads `→ continued by the caller after N of
   max rounds (condition not met)`: it never passed. Each attempt of a
   loop step says its round (`write · round 2`).
-- **A gate row** heads the phase of the steps behind it and reads `waits after
-  <steps>`, `waiting for you · <note>` with its `continue` command, `passed ·
+- **A gate row** heads the phase of the steps behind it and reads
+  `waits after <steps>`, `waiting for you · <note>` with its `continue` command, `passed ·
   continued by the caller`, or `skipped · <condition> does not hold` when its
   `when` condition did not hold.
 - **Answers.** `answer {…}` is the checked answer (it matched the step's schema);

package/docs/guide/routing.md

@@ -198,8 +198,8 @@ well: as `quota` when every reason is a usage limit, else as `unavailable`. Its
 spare: pool-a at its 5-hour limit until <time>; pool-b at its weekly limit
 until <time>`, and `back at` is the earliest known return among them. A retry
 the step was promised (after a crash, a sign-in failure or a failed gate) that
-finds no free pool keeps its own failure and ends its `why` with `· no retry:
-<pool> <reason>; …`. When another pool that can run the step is free, routing
+finds no free pool keeps its own failure and ends its `why` with
+`· no retry: <pool> <reason>; …`. When another pool that can run the step is free, routing
 picks it as usual.
 
 A run saved by 0.37.x may end with `the workflow planner stopped on a usage

package/docs/guide/workflows.md

@@ -108,6 +108,7 @@ bullswarm workflow plan validate "Make the acme tests pass" --cwd=/private/tmp/v
 ✓ program v3 valid: 2 steps, 0 gates, 1 loop (nothing launched)
   fix                      build/medium deliverable=files
   check                    analyze/medium evidence=command answer after fix
+  checks   not run · add --try-checks to run each command check once now against the current tree (it may take time and must not change files)
   loop until-green         steps fix, check · until check's evidence passed · at most 3 rounds
   launch   bullswarm workflow goal 'Make the acme tests pass' --cwd /private/tmp/v37fix/acme --program /private/tmp/v37fix/loop.json --json
 ```

package/docs/reference/cli.md

@@ -255,7 +255,7 @@ Trailing `<task text...>` is mutually exclusive with `--prompt` and `--task-file
 | `--avoid-provider <provider,...>` | never route to pools of these providers | unset |
 | `--dry-run` | print the kernel's routing pick, the forecast, and the exact command that would be spawned, without spawning, recording a run, registering an assignment, or writing the decision log | off (dispatches for real) |
 | `--no-caller` | accepted and ignored for one release: the calling agent is never a pool of its own run | removed in 0.37.0 |
-| `--json` | print the compact machine-readable verdict; top-level `pool` and `model` name who ran the last attempt (null when nothing was dispatched; `pick` keeps the same two beside the command); its last field, details, is the command for the full record and per-attempt cost (bullswarm workflow runs result <shortId> --json) | human-readable summary ending with the run id and that command |
+| `--json` | print the compact machine-readable verdict; top-level `pool` and `model` name who ran the last attempt (null when nothing was dispatched; `pick` keeps the same two beside the command); its last field, details, is the command for the full record and per-attempt cost (`bullswarm workflow runs result <shortId> --json`) | human-readable summary ending with the run id and that command |
 
 A run is a one-step workflow, recorded under `workflows/<id>/` (`bullswarm workflow runs --all`). It gets the step's one automatic retry unless `--no-retry`; a usage limit exits 1 with no retry, and the pool's meter is read again at once, so a window it shows at 100% keeps the pool out of later picks until that window resets. Nothing else about a failed pool is remembered. A build or chore run must change a file (else failure kind `not-produced`). The JSON shape is in [Result envelope](/reference/result).
 

package/docs/reference/program.md

@@ -367,7 +367,7 @@ Checks receive `BULLSWARM_EVIDENCE=1`, `BULLSWARM_STEP_ID`, `BULLSWARM_STEP_OUTP
 
 Checks must be read-only. Before the first item and after each one, Bullswarm hashes the deliverable: the step's `ownedFiles`, declared deliverable paths and saved response, plus every tracked file and HEAD in an isolated copy or for a build or chore step with no `ownedFiles` (it runs alone). A change fails the item with `changed the deliverable: …`, and the later items do not run. Untracked by-products there are recorded as `touched` rather than failed; declare a new file as a deliverable path when it must be protected. In an isolated copy, after the last item, Bullswarm removes the files the checks created and puts back untracked files they rewrote or deleted (up to 16 MB in total), so none of them is merged back. One it cannot put back is named in an attempt note, `check by-product not restored: <paths>`, and is left out of the ownership check and the merge-back. Elsewhere HEAD is not compared: when it moves while an item runs (another step may have committed), the item records `headMoved: true` as a fact and does not fail.
 
-Scope a command to its step. Put a whole-suite command on a step that runs alone or last, and pass `--run` or `CI=1` yourself when a test runner watches files. Run every check once by hand before launch and give it a generous timeout: changing a wrong check amends the step and reruns its worker. A suite that runs longer than 600 seconds cannot be one item: split it into several items or keep it in the step's prompt. To prove finished work without rerunning it, add a `check` step with its own `evidence`; it does not rerun the work. An old kernel refuses `evidence`; pause, revise, then resume.
+Scope a command to its step. Put a whole-suite command on a step that runs alone or last, and pass `--run` or `CI=1` yourself when a test runner watches files. Run every check once before launch (`workflow plan validate --try-checks` runs each command check once in the workspace, for checks that are safe to run now) and give it a generous timeout: changing a wrong check amends the step and reruns its worker. A suite that runs longer than 600 seconds cannot be one item: split it into several items or keep it in the step's prompt. To prove finished work without rerunning it, add a `check` step with its own `evidence`; it does not rerun the work. An old kernel refuses `evidence`; pause, revise, then resume.
 
 Each check's result is in the full `bullswarm workflow runs result <id> --json` envelope (not `--summary`) under `actions[].evidenceResults`: `status`, `exit`, `tail`, `why` and the log path. `bullswarm workflow action show <id> <step>` shows the same for each attempt under `attempts[].evidenceResults`. Each item's full output is in `evidence-<step>-attempt-<n>-<k>.log` in the run directory.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bullswarm",
-  "version": "0.38.3",
+  "version": "0.38.6",
   "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

@@ -90,6 +90,7 @@ validate:
 ✓ program v3 valid: 2 steps, 0 gates, 0 loops (nothing launched)
   build                    build/medium deliverable=files evidence=command
   review                   analyze/medium answer after build route: independent of build blind to build
+  checks   not run · add --try-checks to run each command check once now against the current tree (it may take time and must not change files)
 ```
 
 Keep the goal in a file and pass it as `"$(cat goal.txt)"` to both commands,
@@ -121,7 +122,11 @@ it a `--timeout` under your tool's time limit (`--until trouble --timeout 100`
 for 2 minutes). A restart without `--after` attaches at the newest event and
 skips wakes in between. Never end your turn while a run you own is still
 running. At a gate: `bullswarm workflow continue <shortId> <gate>`; a loop out
-of rounds takes `--rounds <1-5>`. `watch --until trouble` also wakes on
+of rounds takes `--rounds <1-5>`. `workflow step accept` on a failed step
+inside a loop does not end the loop (the next round still starts); to stop a
+loop early let it run out of rounds (`maxRounds`), then
+`workflow continue <shortId> <loop>`, recorded as condition not met.
+`watch --until trouble` also wakes on
 `steering received` (a person left guidance: decide what it means and add
 steps).
 
@@ -145,9 +150,12 @@ Lessons from real runs; each holds for this version.
    the other. Give each writer its own files and tell it to keep other
    workers' edits; keep a breaking rename in one step, not parallel with its
    consumers, which would build against the old name.
-5. **Checks are facts.** Put anything a machine can say in `evidence`, and
-   run each check by hand before launch: fixing a wrong check reruns the
-   worker. Workers share one tree, so a later step can undo what an earlier
+5. **Checks are facts.** Put anything a machine can say in `evidence`. When
+   the checks are safe to run now (not ones that write, deploy, call paid
+   services or take long), run `bullswarm workflow plan validate … --try-checks`
+   before launch and read each `try` line: an error such as a missing module
+   or command means the check itself is wrong, and fixing a wrong check later
+   reruns the worker. Workers share one tree, so a later step can undo what an earlier
    step's check proved; put the final check where nothing runs after it
    (after integration, or on the step a gate waits behind).
 6. **Reviews that hold.** State the contract as numbered checks, make any

package/skill/references/patterns.md

@@ -122,6 +122,7 @@ validate:
 ✓ program v3 valid: 2 steps, 0 gates, 1 loop (nothing launched)
   fix                      build/medium deliverable=files
   check                    analyze/medium evidence=command answer after fix
+  checks   not run · add --try-checks to run each command check once now against the current tree (it may take time and must not change files)
   loop until-green         steps fix, check · until check's evidence passed · at most 3 rounds
 ```
 
@@ -258,6 +259,7 @@ validate (plan and the added steps as one program):
   slice-writer             build/medium deliverable=files after pick-slices
   slice-command            build/medium deliverable=files after pick-slices
   check                    analyze/medium deliverable=report evidence=command after slice-writer, slice-command
+  checks   not run · add --try-checks to run each command check once now against the current tree (it may take time and must not change files)
   gate pick-slices         after plan · waits for you · Read the slices, add one build step per slice and a check, then continue
 ```
 

package/skill/references/program.md

@@ -318,8 +318,11 @@ Rules the fields above do not show on their own:
   tell it to keep other workers' edits.
 - **Evidence: checks Bullswarm runs.** Add a command or schema check for
   anything a machine can check (`"evidence": [{"type": "command", "cmd": "npm
-  test", "timeoutSec": 300}]`, at most 5 items). Run a check by hand before
-  launch, because fixing a wrong check reruns the worker.
+  test", "timeoutSec": 300}]`, at most 5 items). Try the checks before
+  launch with `bullswarm workflow plan validate … --try-checks` when they are
+  safe to run now (it runs each command check once in the workspace and
+  prints a `try` line; a check that reads `$output` is not tried), because
+  fixing a wrong check reruns the worker.
 - **Steps that must not repeat.** Sending or publishing is `"deliverable":
   "outward"` with `"retry": 0`; an outward step is never retried once its
   worker started.

package/skill/references/recovery.md

@@ -236,7 +236,11 @@ finishes: the handback").
 **An accept is a choice, never proof.** `step accept` lets the step's
 dependents run, and the step reads `accepted by choice` and is counted apart
 in the proof line (`N accepted by choice: <steps>`). Report it as your
-decision, never as verification.
+decision, never as verification. `step accept` on a failed step inside a
+loop does not end the loop (the next round still starts); to stop a loop
+early let it run out of rounds (`maxRounds`), then
+`bullswarm workflow continue <shortId> <loop>`, which is recorded as
+condition not met.
 
 ## Other stopping rules
 

package/src/help.js

@@ -1090,18 +1090,19 @@ const workflowPlanText = rich({
 });
 
 const workflowPlanValidateText = rich({
-  usage: 'bullswarm workflow plan validate "<goal>" --program <file.json> [--cwd <dir>] [--summary <text>] [--json]',
+  usage: 'bullswarm workflow plan validate "<goal>" --program <file.json> [--cwd <dir>] [--summary <text>] [--try-checks] [--json]',
   purpose: 'Check a program you authored against the exact contract a launch would enforce, without '
     + 'creating a run: the same validator and the same preview state as '
     + 'workflow goal --program. Exit 0 prints the accepted actions and the launch line; exit 2 prints '
     + 'every validator issue so you can fix the file and re-run. A bullswarm.workflow.program.v2 is refused '
-    + '(exit 2), as a launch refuses it.',
+    + '(exit 2), as a launch refuses it. Command checks are not run unless you add --try-checks.',
   args: [{ name: '"<goal>"', desc: 'the goal text exactly as it will be passed to workflow goal' }],
   options: [
     { flag: '--program <file.json>', desc: 'a bare bullswarm.workflow.program.v3 document, or one inside a planner response envelope', default: 'required' },
     { flag: '--cwd <dir>', desc: 'working directory the goal will execute in (must exist)', default: 'current directory' },
     { flag: '--summary <text>', desc: 'one-line summary recorded for a bare program document', default: 'derived from the action purposes' },
-    { flag: '--json', desc: 'print the acceptance document ({action: "plan-valid", requirements, program, next}) or the refusal ({error: "program-invalid", issues, next}) as JSON', default: 'human summary' },
+    { flag: '--try-checks', desc: 'run each step\'s command check once now, in --cwd, the way a step runs it, and print a try line per check (exit, last output line when it passes, and any files it changed; a check that fails or times out also shows the last 20 lines of its output); a check that reads the step\'s output is not tried. Only for checks that are safe to run now: it may take time, touch the network or cost money, and a check that writes changes your tree (nothing is restored). The results never change the exit code', default: 'off (checks are counted, not run)' },
+    { flag: '--json', desc: 'print the acceptance document ({action: "plan-valid", requirements, program, checks?, next}) or the refusal ({error: "program-invalid", issues, next}) as JSON', default: 'human summary' },
     { flag: '--isolation', desc: 'validate against strict per-worker worktree isolation', default: 'off (shared workspace)' },
     { flag: '--worker-pool <pool|auto>', desc: 'pin the worker pool the preview routes with', default: 'auto (routing decides per action)' },
     { flag: '--worker-model <model|auto>', desc: 'pin the worker model the preview routes with', default: 'auto' },
@@ -1112,8 +1113,14 @@ const workflowPlanValidateText = rich({
     { flag: '--concurrency <n>', desc: 'execution concurrency for the previewed run', default: '4' },
     { flag: '--retry-attempts <0..3>', desc: 'automatic retries per step before it comes back to you (process failures on another pool, gate failures on the same pool with the failure attached)', default: '1' },
   ],
-  safety: ['read-only — nothing is launched, dispatched, or written; the exit code is the verdict (0 valid, 2 invalid, 1 bad cwd)'],
-  examples: [{ cmd: 'bullswarm workflow plan validate "1. Fix the parser. 2. Update the docs." --cwd . --program plan.json --json' }],
+  safety: [
+    'read-only without --try-checks — nothing is launched, dispatched, or written; the exit code is the verdict (0 valid, 2 invalid, 1 bad cwd)',
+    'with --try-checks it runs your command checks in --cwd (never a worker, never in the run home); whatever they do, they do: use it only for checks that are safe to run now',
+  ],
+  examples: [
+    { cmd: 'bullswarm workflow plan validate "1. Fix the parser. 2. Update the docs." --cwd . --program plan.json --json' },
+    { cmd: 'bullswarm workflow plan validate "Fix the parser" --cwd . --program plan.json --try-checks', note: 'a missing module or command on a try line means the check itself is wrong' },
+  ],
   next: 'bullswarm workflow goal "<same goal>" --cwd <dir> --program plan.json once it validates.',
 });
 

package/src/lib/cli-flags.js

@@ -146,7 +146,7 @@ const TABLE = {
     'concurrency', 'retry-attempts',
   ],
   'workflow plan validate': [
-    'program', 'cwd', 'summary', 'json', 'isolation', 'worker-pool',
+    'program', 'cwd', 'summary', 'json', 'try-checks', 'isolation', 'worker-pool',
     'worker-model', 'worker-reasoning', 'max-agents', 'max-actions',
     'max-expansion-rounds', 'concurrency', 'retry-attempts',
   ],

package/src/workflow/cli-plan.js

@@ -20,6 +20,7 @@ import {
   goalNextCommands, refuseProgramInvalid, loadCallerProgram, previewValidateInitialProgram, printAdvisories,
   ProgramV2RefusedError, refuseProgramV2,
 } from './cli-program-checks.js';
+import { CHECKS_NOT_RUN_LINE, commandCheckCount, tryCommandChecks, tryLine } from './plan-try-checks.js';
 
 // Flags that only make sense on a launch have no meaning for the read-only
 // planning commands.
@@ -149,6 +150,11 @@ async function planValidate(opts) {
   }
   if (workspaceIssues.length) return refuseProgramInvalid(goal, opts, workspaceIssues, { message: 'program invalid against the contract (nothing launched)' });
   const next = goalNextCommands(goal, doc.intent.cwd, opts);
+  // Command checks run only when the caller asks (--try-checks): a check may
+  // be slow, cost money or touch the network. Their results never change the
+  // exit code.
+  const commands = commandCheckCount(accepted.program.actions);
+  const tried = commands && opts['try-checks'] ? await tryCommandChecks(accepted.program.actions, { cwd: doc.intent.cwd }) : null;
   const payload = {
     action: 'plan-valid',
     requirements: doc.intent.requirements,
@@ -173,6 +179,7 @@ async function planValidate(opts) {
     // valid program so a caller can read it without probing for the key.
     advisories: programAdvisories(accepted.program, { requirements: null })
       .map((item) => ({ ...item, message: v3IssueWording(item.message) })),
+    ...(commands ? { checks: tried ? { tried: true, results: tried } : { tried: false, commands } } : {}),
     next: { launch: next.launch },
   };
   if (opts.json) console.log(JSON.stringify(payload, null, 2));
@@ -180,7 +187,11 @@ async function planValidate(opts) {
     const control = programControl(accepted.program);
     const count = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
     console.log(`✓ program v3 valid: ${count(payload.program.actions.length, 'step')}, ${count(control.gates.length, 'gate')}, ${count(control.loops.length, 'loop')} (nothing launched)`);
-    for (const action of payload.program.actions) console.log(`  ${action.id.padEnd(24)} ${action.lane}/${action.effort}${action.deliverable ? ` deliverable=${action.deliverable.type}${action.deliverable.paths?.length ? `:${action.deliverable.paths.join(',')}` : ''}` : ''}${action.evidence ? ` evidence=${action.evidence.map((item) => item.type).join(',')}` : ''}${action.reasoning ? ` reasoning=${action.reasoning}` : ''}${action.answer ? ' answer' : ''}${action.dependsOn.length ? ` after ${action.dependsOn.join(', ')}` : ''}${action.route ? ` route: ${routeSummary(action.route)}` : ''}${action.blindTo?.length ? ` blind to ${action.blindTo.join(', ')}` : ''}`);
+    for (const action of payload.program.actions) {
+      console.log(`  ${action.id.padEnd(24)} ${action.lane}/${action.effort}${action.deliverable ? ` deliverable=${action.deliverable.type}${action.deliverable.paths?.length ? `:${action.deliverable.paths.join(',')}` : ''}` : ''}${action.evidence ? ` evidence=${action.evidence.map((item) => item.type).join(',')}` : ''}${action.reasoning ? ` reasoning=${action.reasoning}` : ''}${action.answer ? ' answer' : ''}${action.dependsOn.length ? ` after ${action.dependsOn.join(', ')}` : ''}${action.route ? ` route: ${routeSummary(action.route)}` : ''}${action.blindTo?.length ? ` blind to ${action.blindTo.join(', ')}` : ''}`);
+      for (const result of tried ?? []) if (result.step === action.id) console.log(tryLine(result));
+    }
+    if (commands && !tried) console.log(CHECKS_NOT_RUN_LINE);
     for (const line of controlSummaryLines(control)) console.log(line);
     printAdvisories(payload.advisories);
     console.log(`  launch   ${next.launch}`);

package/src/workflow/cli-steps.js

@@ -36,7 +36,7 @@ import { workspacePathIssues } from './v2-planner.js';
 import { acquireKernelLease } from './v2-process.js';
 import { reviseV2Program } from './run-control.js';
 import { deserializeV2DurableState, serializeV2DurableState } from './v2-state.js';
-import { formatDuration } from './watch-cli.js';
+import { formatDuration } from './format-duration.js';
 
 function readState(runDir) {
   return deserializeV2DurableState(readFileSync(join(runDir, 'state.json'), 'utf8'));

package/src/workflow/cli.js

@@ -7,7 +7,7 @@ import { runDashboard, dashboardJson, overviewSnapshot } from './dashboard.js';
 import { wfAdd, wfContinue, wfWait } from './cli-steps.js';
 import { helpText, usageLine } from '../help.js';
 import { flagName, unknownFlagExit } from '../lib/cli-flags.js';
-import { cmdReprice } from './reprice.js';
+import { cmdReprice } from './reprice-cli.js';
 import { resolvePoolId } from '../lib/pool-labels.js';
 import { workflowHelpPath, parseFlags, flagErrors } from './workflow-flags.js';
 import { BULLSWARM_DIR, legacyRunRefusal, legacyRunSummary, legacySummaryLines } from './cli-run-lookup.js';

package/src/workflow/contract-v3.js

@@ -123,7 +123,7 @@ export function buildV3Contract({ goal, cwd, next, workerReasoning = null }) {
         timeoutSec: { default: EVIDENCE_DEFAULT_TIMEOUT_SEC, max: EVIDENCE_MAX_TIMEOUT_SEC },
         schemaKeywords: [...SCHEMA_ASSERTED_KEYWORDS], schemaIgnored: [...SCHEMA_IGNORED_KEYWORDS],
         schemaFormats: ['json', 'jsonl'], outputFile: '$output', env: [...EVIDENCE_ENV_KEYS], checker: CHECKER_PATH,
-        note: 'checks are read-only: a check that changes the deliverable fails; the answer schema and a schema check accept the same keywords',
+        note: 'checks are read-only: a check that changes the deliverable fails; the answer schema and a schema check accept the same keywords; workflow plan validate --try-checks runs each command check once against the current tree before launch (only for checks safe to run now; a check that reads $output is not tried)',
       },
       notV3: 'purpose, affects, evidenceFor, kind, role, inputs, produces and defaults.verifyRounds belong to v2 programs; a check is an ordinary step with an answer and/or evidence',
     },

package/src/workflow/control-nodes.js

@@ -0,0 +1,47 @@
+// A v3 run's control nodes: the gates and loops its program declares, and
+// the record of each (stored, or the initial one before the kernel's first
+// pass). gates-loops.js moves them; the revision walk reads them too.
+
+import { PROGRAM_V3_SCHEMA_VERSION } from './program-v3.js';
+
+/** The run's gates and loops ({gates, loops}), or null for a v2 run or a v3 run with none. */
+export function controlOf(state) {
+  const program = state?.program;
+  if (program?.schemaVersion !== PROGRAM_V3_SCHEMA_VERSION) return null;
+  const gates = program.control?.gates ?? [];
+  const loops = program.control?.loops ?? [];
+  return gates.length || loops.length ? { gates, loops } : null;
+}
+
+function defaultRecord(node, type) {
+  return type === 'loop'
+    ? { id: node.id, type, status: 'pending', at: null, round: 1, maxRounds: node.maxRounds }
+    : { id: node.id, type, status: 'pending', at: null };
+}
+
+/** Every control node's record, stored or (before the kernel's first pass) the initial one. */
+export function controlRecords(state) {
+  const control = controlOf(state);
+  if (!control) return [];
+  const stored = new Map((state.controlNodes ?? []).map((record) => [record.id, record]));
+  return [
+    ...control.loops.map((loop) => stored.get(loop.id) ?? defaultRecord(loop, 'loop')),
+    ...control.gates.map((gate) => stored.get(gate.id) ?? defaultRecord(gate, 'gate')),
+  ];
+}
+
+/**
+ * The revision walk's edges through the run's gates and loops ([from, to]): a
+ * gate's dependencies lead to the gate, a loop's steps to the loop, so a step
+ * rerun or accepted before one reaches the steps behind it. A node that has
+ * passed is left out: the steps behind it would start before the rerun step.
+ */
+export function controlReachEdges(state) {
+  const control = controlOf(state);
+  if (!control) return [];
+  const status = new Map(controlRecords(state).map((record) => [record.id, record.status]));
+  const edges = [];
+  for (const loop of control.loops) if (status.get(loop.id) !== 'passed') for (const id of loop.steps) edges.push([id, loop.id]);
+  for (const gate of control.gates) if (status.get(gate.id) !== 'passed') for (const id of gate.dependsOn) edges.push([id, gate.id]);
+  return edges;
+}

package/src/workflow/dashboard.js

@@ -24,12 +24,7 @@ import { readRollups, rollupIndexPath } from './rollup.js';
 import { loadState } from '../lib/state.js';
 import { listTasks, taskKey } from '../lib/tasks.js';
 import { filterDashboardRows } from './runs-view.js';
-import {
-  workflowPanelModel,
-  planProgress,
-  planStripParts,
-  runEconomics,
-} from './run-model.js';
+import { workflowPanelModel } from './run-model.js';
 import {
   renderWorkflowOverviewPanel,
   workflowTimelineLines,
@@ -55,18 +50,9 @@ import { requestCancel } from './dashboard-cancel.js';
 import { dashboardRows, activeDashboardRows, detailRow } from './dashboard-rows.js';
 import { renderDetails } from './dashboard-details.js';
 import { renderDashboardPage } from './dashboard-render.js';
-export { dimText, tint, truncate, visibleLength, meterAnsi, blank, strong, inverseText } from './dashboard-ansi.js';
-export { clamp } from './dashboard-clamp.js';
-export { reasoningText, clockText, formatBytes, durationText, moneyText, minutesText, compactUsage, tokenText, ageText, clockAt } from './dashboard-value-text.js';
-export { stateStatus, stateStartedAt, stateFinishedAt, TERMINAL_ACTIONS, workflowRunLabel } from './dashboard-run-state.js';
-export { statusIcon, workflowStatusIcon } from './dashboard-status.js';
-export { SIDEBAR_WIDTH, renderPanel, joinPanels, panelWindow, panelCell, dimLine, selectLine, timelineText } from './dashboard-panels.js';
-export { pushView, pushColumns } from './dashboard-frame.js';
-export { PERIOD_ITEMS } from './dashboard-pages.js';
 export { requestCancel } from './dashboard-cancel.js';
 export { dashboardRows } from './dashboard-rows.js';
 export { readLicencePerDay, writeClipboard, activeDashboardRows, renderDetails };
-export { agentDetailLines, taskPreview, outcomePreview, wrapLines } from './dashboard-agent-detail.js';
 export { renderDashboardPage } from './dashboard-render.js';
 
 /** The operating-system-command introducer and its terminator, for OSC 52. */
@@ -1991,12 +1977,8 @@ export function dashboardJson(bullswarmDir, { all = false, token = null, cancel
   return { action: 'list', count: runs.length, runs };
 }
 
-// Home and Runs view modules consume these shell-owned primitives. Keeping the
-// compatibility exports here lets existing Step/CLI callers retain their
-// dashboard import path while page-specific functions move out of this file.
+// Callers that read the run panel through the dashboard keep this import
+// path; the page modules import it from run-model.js, the module that owns it.
 export {
   workflowPanelModel,
-  runEconomics,
-  planProgress,
-  planStripParts,
 };

package/src/workflow/format-duration.js

@@ -0,0 +1,12 @@
+// A duration in seconds as the watch lines print it: `42s`, `3m05s`, `1h07m`.
+
+export function formatDuration(seconds) {
+  if (!Number.isFinite(seconds)) return '?';
+  const total = Math.max(0, Math.round(seconds));
+  const hours = Math.floor(total / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const secs = total % 60;
+  if (hours) return `${hours}h${String(minutes).padStart(2, '0')}m`;
+  if (minutes) return `${minutes}m${String(secs).padStart(2, '0')}s`;
+  return `${secs}s`;
+}

package/src/workflow/gates-loops.js

@@ -30,6 +30,7 @@ import { randomUUID } from 'node:crypto';
 import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { appendEvent } from './events.js';
+import { controlOf, controlRecords } from './control-nodes.js';
 import { PROGRAM_V3_SCHEMA_VERSION } from './program-v3.js';
 import {
   commitV2Revision, exportV2Plan, planV2Revision, rejectedRevisionRecord, removeStaleReceipts, revisionEventPayload,
@@ -46,6 +47,8 @@ const ANSWER_SHOWN_CHARS = 4000;
 const TAIL_SHOWN_LINES = 20;
 const LINE_SHOWN_CHARS = 200;
 
+export { controlOf, controlRecords };
+
 // --- the program's control nodes ---------------------------------------------
 
 /**
@@ -77,32 +80,6 @@ export function continuedLoopText(id, rounds, maxRounds, { by = true } = {}) {
   return `loop ${id} continued${by ? ' by the caller' : ''} after ${rounds} of ${maxRounds} rounds (condition not met)`;
 }
 
-/** The run's gates and loops ({gates, loops}), or null for a v2 run or a v3 run with none. */
-export function controlOf(state) {
-  const program = state?.program;
-  if (program?.schemaVersion !== PROGRAM_V3_SCHEMA_VERSION) return null;
-  const gates = program.control?.gates ?? [];
-  const loops = program.control?.loops ?? [];
-  return gates.length || loops.length ? { gates, loops } : null;
-}
-
-function defaultRecord(node, type) {
-  return type === 'loop'
-    ? { id: node.id, type, status: 'pending', at: null, round: 1, maxRounds: node.maxRounds }
-    : { id: node.id, type, status: 'pending', at: null };
-}
-
-/** Every control node's record, stored or (before the kernel's first pass) the initial one. */
-export function controlRecords(state) {
-  const control = controlOf(state);
-  if (!control) return [];
-  const stored = new Map((state.controlNodes ?? []).map((record) => [record.id, record]));
-  return [
-    ...control.loops.map((loop) => stored.get(loop.id) ?? defaultRecord(loop, 'loop')),
-    ...control.gates.map((gate) => stored.get(gate.id) ?? defaultRecord(gate, 'gate')),
-  ];
-}
-
 function ensureRecords(state) {
   state.controlNodes = controlRecords(state);
   return new Map(state.controlNodes.map((record) => [record.id, record]));
@@ -350,22 +327,6 @@ export function unblockControlNodes(state, { at }) {
   }
 }
 
-/**
- * The revision walk's edges through the run's gates and loops ([from, to]): a
- * gate's dependencies lead to the gate, a loop's steps to the loop, so a step
- * rerun or accepted before one reaches the steps behind it. A node that has
- * passed is left out: the steps behind it would start before the rerun step.
- */
-export function controlReachEdges(state) {
-  const control = controlOf(state);
-  if (!control) return [];
-  const status = new Map(controlRecords(state).map((record) => [record.id, record.status]));
-  const edges = [];
-  for (const loop of control.loops) if (status.get(loop.id) !== 'passed') for (const id of loop.steps) edges.push([id, loop.id]);
-  for (const gate of control.gates) if (status.get(gate.id) !== 'passed') for (const id of gate.dependsOn) edges.push([id, gate.id]);
-  return edges;
-}
-
 /**
  * The kernel's control-node pass: apply the caller's continue intents, then
  * move every gate and loop as far as its dependencies allow. Emits

package/src/workflow/home-view.js

@@ -39,25 +39,13 @@ import {
   todayRows,
   verifyRoundLabel,
 } from './home-model.js';
-import {
-  ageText,
-  blank,
-  dimText,
-  meterAnsi,
-  minutesText,
-  moneyText,
-  planProgress,
-  planStripParts,
-  PERIOD_ITEMS,
-  pushColumns,
-  runEconomics,
-  stateStartedAt,
-  strong,
-  tint,
-  visibleLength,
-  workflowRunLabel,
-  wrapLines,
-} from './dashboard.js';
+import { ageText, minutesText, moneyText } from './dashboard-value-text.js';
+import { blank, dimText, meterAnsi, strong, tint, visibleLength } from './dashboard-ansi.js';
+import { planProgress, planStripParts, runEconomics } from './run-model.js';
+import { PERIOD_ITEMS } from './dashboard-pages.js';
+import { pushColumns } from './dashboard-frame.js';
+import { stateStartedAt, workflowRunLabel } from './dashboard-run-state.js';
+import { wrapLines } from './dashboard-agent-detail.js';
 import { attemptMetric, tokenSourceOf } from './metrics.js';
 import { taskAttempt } from './metrics-legacy.js';
 import { apiMoney, formatMoney } from '../lib/usage-basis.js';

package/src/workflow/legacy-run-state.js

@@ -0,0 +1,7 @@
+// The one predicate every reader uses to tell an authored-graph run from a V2
+// one. 0.27.0 removed the authored-graph executor, so a run directory whose
+// state.json lacks the V2 schemaVersion — or that has no state.json at all —
+// is history: readable, listable, deletable, never driven.
+export function isLegacyRunState(state) {
+  return state?.schemaVersion !== 'bullswarm.workflow.state.v2';
+}

package/src/workflow/needs-you.js

@@ -10,7 +10,7 @@
 import { glyphs } from '../lib/glyphs.js';
 import { countRetries, declaredEvidence, NEEDS_YOU_LABELS, roleOf } from './step-vocabulary.js';
 import { readRunFeatures, runFeatureFlags } from './run-features.js';
-import { formatDuration } from './watch-cli.js';
+import { formatDuration } from './format-duration.js';
 import { isProgramV3 } from './program-v3.js';
 
 const LINE_CHARS = 160;