bullswarm 0.38.3 → 0.38.5

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 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.5",
   "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/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/plan-try-checks.js

@@ -0,0 +1,160 @@
+// `workflow plan validate --try-checks` (0.38.4): run each step's command
+// checks once against the current tree, the way the evidence runner runs
+// them during a step (same shell, working folder, environment and timeout,
+// the same tail of output), without dispatching a worker or writing into the
+// run home. The results are information: validate's exit code never follows
+// them, because a check that fails before the work exists is often expected.
+
+import { lstatSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative, resolve, sep } from 'node:path';
+import { evidenceEnv, evidenceItemLabel, evidenceItemTimeoutSec, runEvidenceItem, stripAnsi } from './evidence-runner.js';
+
+const MAX_LISTED = 10;
+const SHOW_ALL_LINES = 30;
+// 14 first lines, not 12: for `node --test <folder>` the line with MODULE_NOT_FOUND is line 13.
+const SHOW_HEAD_LINES = 14;
+const SHOW_TAIL_LINES = 12;
+const TAIL_INDENT = ' '.repeat(11);
+
+/** A command check that reads the step's final response, which does not exist before the step runs. */
+export const readsStepOutput = (item) => /\$output\b|BULLSWARM_STEP_OUTPUT/.test(String(item?.cmd ?? ''));
+
+/** How many command checks the program declares. */
+export function commandCheckCount(actions) {
+  return (actions ?? []).reduce((n, action) => n + (action.evidence ?? []).filter((item) => item?.type === 'command').length, 0);
+}
+
+function realPath(path) {
+  try { return realpathSync(path); } catch { return resolve(path); }
+}
+
+// Every file under the workspace (git's own folder aside) → size, change
+// times and inode, ignored and untracked files included, inside or outside a
+// git repository. A check that writes, deletes or renames a file changes its
+// entry. Paths are relative to the workspace.
+function fileSnapshot(root) {
+  const snapshot = new Map();
+  const walk = (directory) => {
+    let entries;
+    try { entries = readdirSync(directory, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.name === '.git') continue;
+      const absolute = join(directory, entry.name);
+      if (entry.isDirectory()) { walk(absolute); continue; }
+      let stat;
+      try { stat = lstatSync(absolute, { bigint: true }); } catch { continue; }
+      snapshot.set(relative(root, absolute).split(sep).join('/'), `${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}:${stat.ino}`);
+    }
+  };
+  walk(root);
+  return snapshot;
+}
+
+function changedBetween(before, after) {
+  const paths = new Set([...before.keys(), ...after.keys()]);
+  return [...paths].filter((path) => before.get(path) !== after.get(path)).sort();
+}
+
+function lastLine(tail) {
+  const lines = String(tail ?? '').split('\n').map((line) => line.trim()).filter(Boolean);
+  if (!lines.length) return null;
+  return lines[lines.length - 1];
+}
+
+/**
+ * Run every command check of `actions` once, one after the other, in `cwd`.
+ * Resolves to `[{ step, index, cmd, exit, timedOut, tail, changedFiles }]`
+ * (index is the item's 1-based place in the step's evidence); a check that
+ * reads the step's output is listed with `notTried` and never runs.
+ */
+export async function tryCommandChecks(actions, { cwd, env = process.env } = {}) {
+  const root = realPath(cwd);
+  const results = [];
+  // BULLSWARM_STEP_OUTPUT and BULLSWARM_RUN_DIR point into a scratch folder
+  // outside the run home, removed afterwards.
+  const scratch = mkdtempSync(join(tmpdir(), 'bullswarm-try-'));
+  // The full output of every check is kept here, for the caller to read.
+  const logs = mkdtempSync(join(tmpdir(), 'bullswarm-try-logs-'));
+  try {
+    for (const action of actions ?? []) {
+      const items = Array.isArray(action.evidence) ? action.evidence : [];
+      for (let index = 0; index < items.length; index += 1) {
+        const item = items[index];
+        if (item?.type !== 'command') continue;
+        const base = { step: action.id, index: index + 1, cmd: item.cmd };
+        if (readsStepOutput(item)) {
+          results.push({ ...base, exit: null, timedOut: false, tail: '', changedFiles: [], notTried: 'it reads the step\'s output' });
+          continue;
+        }
+        const before = fileSnapshot(root);
+        const run = await runEvidenceItem(item, {
+          cwd: root,
+          env: evidenceEnv(env, { cwd: root, stepId: action.id, outFile: join(scratch, 'output.md'), runDir: scratch }),
+          outFile: join(scratch, 'output.md'),
+          logFile: join(logs, `${results.length + 1}-${action.id.replace(/[^A-Za-z0-9._-]/g, '_')}-${index + 1}.log`),
+        });
+        const changedFiles = changedBetween(before, fileSnapshot(root));
+        results.push({
+          ...base,
+          exit: run.exit,
+          timedOut: Boolean(run.timedOut),
+          ...(run.timedOut ? { timeoutSec: evidenceItemTimeoutSec(item) } : {}),
+          ...(run.exit == null && !run.timedOut && run.why ? { why: run.why } : {}),
+          tail: run.tail,
+          ...(run.log ? { log: run.log } : {}),
+          changedFiles,
+        });
+      }
+    }
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+  return results;
+}
+
+// The command's own output from its log file (the file holds a header of
+// `$ cmd`, `cwd:` and `timeout:` lines before it and a one-line footer after).
+function logOutputLines(result) {
+  let text;
+  try { text = readFileSync(result.log, 'utf8'); } catch { return null; }
+  const marker = text.search(/\ncwd: .*\ntimeout: \d+s\n/);
+  if (marker < 0) return null;
+  let body = text.slice(text.indexOf('\n', text.indexOf('\ntimeout: ', marker) + 1) + 1);
+  const end = body.lastIndexOf('\n', body.length - 2);
+  body = end < 0 ? '' : body.slice(0, end + 1);
+  return stripAnsi(body).replace(/\s+$/, '').split('\n');
+}
+
+function failedOutput(result) {
+  const lines = result.log ? logOutputLines(result) : null;
+  const all = lines ?? String(result.tail ?? '').split('\n');
+  const shown = !all.some((line) => line.trim()) ? [] : all.length <= SHOW_ALL_LINES
+    ? all
+    : [...all.slice(0, SHOW_HEAD_LINES), `… ${all.length - SHOW_HEAD_LINES - SHOW_TAIL_LINES} more lines …`, ...all.slice(-SHOW_TAIL_LINES)];
+  const out = shown.map((line) => `${TAIL_INDENT}${line}`);
+  if (result.log) out.push(`${TAIL_INDENT}full output: ${result.log}`);
+  return out;
+}
+
+/** The `try` line for one result; a check that failed or timed out is followed by its output (all of it when short, else its first and last lines) and the log file path. */
+export function tryLine(result) {
+  const label = evidenceItemLabel({ type: 'command', cmd: result.cmd });
+  let outcome;
+  if (result.notTried) outcome = `not tried: ${result.notTried}`;
+  else if (result.timedOut) outcome = `timed out after ${result.timeoutSec}s`;
+  else if (result.exit == null) outcome = result.why ?? 'did not run';
+  else if (result.exit === 0) {
+    const line = lastLine(result.tail);
+    outcome = `exit 0${line ? ` · ${line}` : ''}`;
+  } else outcome = `exit ${result.exit}`;
+  const changed = result.changedFiles?.length
+    ? ` · changed files: ${result.changedFiles.slice(0, MAX_LISTED).join(', ')}${result.changedFiles.length > MAX_LISTED ? ` (+${result.changedFiles.length - MAX_LISTED} more)` : ''}`
+    : '';
+  const head = `  try      ${label} → ${outcome}${changed}`;
+  const failed = !result.notTried && (result.timedOut || (result.exit != null && result.exit !== 0));
+  const output = failed ? failedOutput(result) : [];
+  return output.length ? [head, ...output].join('\n') : head;
+}
+
+export const CHECKS_NOT_RUN_LINE = '  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)';