bullswarm 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # bullswarm changelog
 
+## 0.30.0 — a run never waits: it finishes and hands back what is left
+
+- workflow: a run no longer waits for anyone. Every point where a
+  caller-planned run used to hold now finishes it and hands the decision
+  back: a `--scout` run with no program, a launch program the kernel could not
+  accept, requirements still open with nothing left to run, and steering still
+  unread when the last step ended. In a study of 41 caller runs on a real
+  project (2026-09-14), one run sat 197 minutes waiting for a caller that had
+  moved on.
+- result: a new optional `handback` field lists every unfinished step with its
+  failure kind, its reason, whether a plain resume runs it again, and
+  `retryAfter` when every pool that could run it was paused; every open
+  requirement with its latest reason; and steering nobody acted on.
+  `runs result --summary` adds `handback.options`, one command each to
+  continue (plan revise), retry (resume), take over, or restart. Results
+  written before 0.30.0 still validate, and their summaries derive the same
+  view.
+- result: the reason line says what happened. "all program actions finished
+  successfully; consult evidence for verification" read as success on runs
+  whose check had failed the work. It now reads, for example, "all 4 steps
+  succeeded, but not verified: requirement-2 failed — requirement-2: …" or "2
+  of 5 steps did not succeed: build-api failed (stalled), …". A long finding
+  quoted there is cut between words and ends in `…`; the full text is in the
+  requirement's `why`.
+- summary: an open requirement's `why` is no longer blanked to fit the 4 KB
+  budget. Concerns, per-step detail and output names shrink first, and a
+  passed requirement carries no `why`. The same study found `why` blank in 6
+  of 10 unverified runs.
+- watch: a finished run prints `outcome: <status> · verified|not verified`,
+  `reason:`, one line per unfinished step and open requirement, unread
+  steering, and `your call:` with the command for each option. A `--jsonl`
+  `finished` object carries `verified`, `reason` and `handback`.
+- resume: `workflow resume` on a finished run is a retry. It reopens the run
+  for pending and cancelled steps, failed steps whose kind a retry fixes
+  (`provider`, `quota`, `auth`, `process`, `unavailable`, `interrupted`,
+  `runtime`, `schema`, `stalled`) and the steps blocked behind them, moves the
+  result to `result-before-resume-<n>.json`, and relaunches. With nothing
+  retryable it prints `nothing to retry`, starts nothing, and exits 1.
+- dispatch: with no pool able to run a step, the step fails at once and says
+  which case it is: every capable pool is paused until a time (recorded as
+  `retryAfter`), the pinned pool cannot run that lane and effort, or no enabled
+  pool has a model on that tier.
+- workers: a worker that writes nothing for 60 minutes is stopped and fails as
+  `stalled`, a mechanical failure retried once. The clock restarts on every
+  byte, so a long step that keeps working is never cut off.
+  `BULLSWARM_WORKER_SILENCE_SEC` sets the limit.
+- kernel: a kernel that throws marks its run `interrupted` with `kernel
+  stopped on an error: <message>` instead of leaving it claiming to run, and
+  `runs show` reports a run whose kernel died as `interrupted`, with the
+  reason and the resume command.
+- validate: an `ownedFiles` entry naming a directory (`src/`, or an existing
+  `src`) or a glob is refused by `plan validate`, `workflow goal` and
+  `plan revise`; it used to pass and then stop the kernel right after launch.
+  A pinned worker pool that cannot run a step's lane and effort is refused
+  before launch. A new advisory, `requirement-unchecked`, names requirements
+  no step checks.
+- legacy: runs an older version left waiting still accept `plan show` and
+  `plan submit`; `workflow resume` now finishes them with a handback instead
+  of pausing again.
+
+## 0.29.1 — a revised cancelled run runs its cancelled steps again
+
+- workflow: revising a cancelled run reopened it but left every step the
+  cancellation had stopped as `cancelled`, so the kernel finalized `partial`
+  in the same second and nothing ran. Found on a real claude-code run
+  (`pxkr7s`, revision 7). Reopening now returns those steps to pending, lists
+  them as `reopened.requeued` in the revise output and the `workflow.reopened`
+  event, and never counts their earlier attempts as completion. Failed steps
+  still wait for an explicit `--rerun`.
+- watch: a run waiting for its caller planner now also prints the
+  `plan export` / `plan revise` commands next to `plan show`.
+- workflow: an attempt stopped by a plan revision or a pause now records
+  `failureKind: superseded` or `paused` on the attempt and in
+  `attempt.finished`, the same kind `action.finished` already carried. It was
+  recorded as a plain `cancelled`, which made deliberate steering look like
+  worker failures.
+- strategy: `strategy rungs` no longer counts a stopped dispatch against a
+  pool's "% ok". On 2026-09-14 all 11 claude-code dispatches recorded as not
+  ok were workflow cancellations, plan revisions or pauses, none a worker
+  failure. Dispatch records now carry `failureKind`. The share was display
+  only; routing never read it.
+
 ## 0.29.0 — steer a running workflow, providers become directories, a declared reset date
 
 - workflow: the plan of a caller-planned program run can be changed at any

package/docs/guide/dashboard.md

@@ -142,8 +142,9 @@ durable instruction that is delivered only to the next not-yet-started
 `decide` checkpoint; the active worker continues unchanged. In a caller-planned
 program run it never halts work: watchers print `steering received`, and the
 caller acts on it with `workflow plan revise`, which can stop, amend, add,
-remove, or rerun steps while the run continues; only a run about to finish with
-the guidance still unread pauses for it. Steering remains
+remove, or rerun steps while the run continues. A run that finishes before
+anyone acts on the guidance lists it as `steering not acted on`, and revising
+the finished run delivers it and reopens the run. Steering remains
 inside the original goal and authorization boundary and cannot bypass runtime
 validation or required verification. Static workflows and terminal runs reject
 steering because they have no future orchestration checkpoint.

package/docs/guide/workflows.md

@@ -161,7 +161,7 @@ Manage a run with first-class verbs:
 bullswarm workflow plan export <shortId> --out plan.json      # the live plan, editable
 bullswarm workflow plan revise <shortId> --program plan.json  # change the plan while it runs
 bullswarm workflow pause  <shortId> [--now]                   # start nothing new; resume continues
-bullswarm workflow resume <shortId> --watch                   # lift a pause; verb form of goal --resume
+bullswarm workflow resume <shortId> --watch                   # lift a pause, or retry a finished run's retryable steps
 bullswarm workflow steer  <shortId> --message "<guidance>"    # guidance for whoever plans the run
 bullswarm workflow cancel <shortId> --json                    # a run with no kernel is finalized here
 ```
@@ -198,6 +198,33 @@ lets running agents finish and starts nothing new (`--now` stops them and runs
 those steps again after resume); revisions apply while paused, and only
 `workflow resume` continues the run.
 
+### A run never waits: it finishes and hands back
+
+No run waits for its caller. When nothing more can run on its own (every step
+has finished, failed, or is blocked behind a failure; no pool can take a step;
+a `--scout` run has no program yet; steering arrived after the last step), the
+run finishes `completed` or `partial`, and its result carries a `handback`:
+each unfinished step with its failure kind, reason, whether a plain resume runs
+it again, and `retryAfter` when every pool that could run it was paused; each
+open requirement with its reason; and steering nobody acted on.
+`watch` prints the same as `step …`, `requirement …` and `steering not acted
+on:` lines, then `your call:` with one command per option:
+
+- **continue**: export, edit and revise the plan (a failed check needs a fix
+  step added to the check's `dependsOn`);
+- **retry**: `workflow resume <shortId>` reruns steps that failed for a reason
+  a retry fixes (`provider`, `quota`, `auth`, `process`, `unavailable`,
+  `interrupted`, `runtime`, `schema`, `stalled`), plus pending and cancelled
+  steps and the steps blocked behind them; with none it prints `nothing to
+  retry` and exits 1;
+- **take over**: do the rest yourself from `runs result <shortId> --json`;
+- **restart**: start a new `workflow goal`.
+
+A step no pool can take fails at once instead of waiting for a pool to come
+back, and a worker that writes nothing for 60 minutes is stopped as `stalled`
+(`BULLSWARM_WORKER_SILENCE_SEC` changes the limit). The only stop that holds a
+run is `workflow pause`, which you choose.
+
 
 `--orchestrator <pool>` expresses a preference and immediately falls back to
 another eligible pool if that provider is quota-gated or unavailable; plain
@@ -279,33 +306,31 @@ bullswarm workflow plan validate "1. Fix the parser. 2. Update the docs." --cwd
 #   → dry run against that contract; exit 0 valid, exit 2 with the issues; nothing launches
 bullswarm workflow goal "1. Fix the parser. 2. Update the docs." --cwd . --program plan.json --watch
 #   → validated before launch; executes with zero planner/scout dispatches
-bullswarm workflow plan show <shortId> --json      # initial scout or explicit steering pause
-bullswarm workflow plan submit <shortId> --program plan-2.json --watch
+bullswarm workflow runs result <shortId> --json --summary   # outcome, reason, handback
 ```
 
-Exit codes are a contract: **0** done or paused durably for you (nothing is
-running), **1** the run ended without completing, **2** usage or validation
-error with nothing launched. Every refusal names the commands that come next.
+Exit codes are a contract: **0** completed, or stopped by `workflow pause`
+(nothing is running), **1** the run finished without completing, **2** usage or
+validation error with nothing launched. Every refusal names the commands that
+come next.
 
-For foreground execution, exit 0 means the graph ran successfully or paused
-durably; it does not imply independent verification. An independent launch
+For foreground execution, exit 0 means the graph ran successfully or was
+paused; it does not imply independent verification. An independent launch
 also returns 0 before the workers finish. Consume its eventual result.
 
 `--program` accepts the planner response envelope or a bare
 `bullswarm.workflow.program.v2` document. An invalid program exits 2 with the
-validator's issues and nothing is launched. When the kernel reaches a planning
-boundary (an initial plan, or a run about to finish with queued steering still
-unread), it writes `planner-request-turn-N.json`, sets the run to `waiting`,
-exits, and `watch` prints the `plan show` command. A submitted program contains
-only new actions and is validated against the exact durable state at that
-boundary. Steering queued while work is still running does not stop it: watch
-prints `steering received` and the caller answers with `plan revise` (see
-[Changing the plan of a live run](#changing-the-plan-of-a-live-run)). Older saved V2
-runs still support their original gap boundaries and `--exhausted` submissions.
-`--scout` without
-`--program` runs the kernel scout first and pauses at the initial boundary so
-the caller plans against a real survey; scout units are advisory for a caller
-planner.
+validator's issues and nothing is launched. Validate also refuses an
+`ownedFiles` entry that is a directory or a glob, and a pinned pool that cannot
+run a step. Steering queued while work is still running does not stop it:
+watch prints `steering received` and the caller answers with `plan revise` (see
+[Changing the plan of a live run](#changing-the-plan-of-a-live-run)). A run
+an older version left waiting for its caller (`planner-request-turn-N.json`,
+status `waiting`) still accepts `plan show` and `plan submit`, including
+`--exhausted` at a gaps boundary; `workflow resume` finishes it with a handback
+instead. `--scout` without `--program` runs the kernel scout and finishes
+partial with the report, which the caller plans from and adds with `plan
+revise`; scout units are advisory for a caller planner.
 
 An action's result envelope is covered in [Operations](./operations.md#result-envelope);
 the JSON example program shape (writers, a digest, and one integrator) is in

package/package.json

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

@@ -91,12 +91,17 @@ bullswarm workflow plan validate "$(cat goal.txt)" --cwd=<abs-dir> --program=<ab
 ```
 
 Exit 2 means the program is invalid: the JSON lists `issues`; fix them and
-validate again. Exit 0 always carries an `advisories` array. Each entry names
-an action whose effort is above what its work warrants (`all-writers-high`,
-`docs-at-high`): lower that action's kind and validate again, or write the
-reason it needs high into its `purpose`. An empty array means launch now, with
-the same goal, `--cwd` and absolute `--program` (validate's `next.launch` line
-is this command):
+validate again. Validate also refuses what would only fail after launch: an
+`ownedFiles` entry that is a directory or a glob (name exact files), and, with
+a pinned pool, a step that pool cannot run. Exit 0 always carries an
+`advisories` array. `all-writers-high` and `docs-at-high` name an action whose
+effort is above what its work warrants: lower that action's kind, or write the
+reason it needs high into its `purpose`. `requirement-unchecked` names a
+requirement no step lists in `evidenceFor`: the run can finish but never
+verify it, so add it to an `adversarial-acceptance` step, or launch knowing the
+result will be unverified. An empty array means launch now, with the same
+goal, `--cwd` and absolute `--program` (validate's `next.launch` line is this
+command):
 
 ```bash
 bullswarm workflow goal "$(cat goal.txt)" --cwd=<abs-dir> --program=<abs-dir>/plan.json --json
@@ -106,28 +111,60 @@ The launch detaches and returns `shortId`; report it.
 
 ## 3. Observe and judge
 
+A run never waits for you. It runs until nothing more can happen on its own,
+then finishes, and its result hands back whatever is left with your options.
+What happens next is your decision.
+
 ```bash
 bullswarm workflow watch <shortId> --next
 bullswarm workflow runs result <shortId> --json --summary
 ```
 
-Run `watch --next` in a background terminal. When it exits, act on the printed
-event and relaunch with the exact `next: bullswarm workflow watch <shortId>
---next --after <sequence> --since <iso>` line it printed, until the outcome
-line reports a pause or a terminal status. A pause is not completion.
+Run `watch --next` in a background terminal and wait for it to exit. Do not
+poll in a loop and do not read files in the run directory. When it exits on an
+event, act on it and relaunch with the exact `next: bullswarm workflow watch
+<shortId> --next --after <sequence> --since <iso>` line it printed. When it
+exits on an `outcome:` line, the run has finished, paused, or been
+interrupted, and the output already holds what you need to decide.
 
-Each wake-up is a decision point: read the output of the step that just
+Each event is a decision point: read the output of the step that just
 finished (`bullswarm workflow action show <shortId> <actionId>` names its
 `outputFile`) and decide whether the rest of the plan still fits. If it does,
 relaunch the watcher. If it does not, revise the plan (section 4) before
 relaunching.
 
+### When it finishes
+
+`outcome:` gives `completed`, `partial` or `cancelled` and whether the run is
+verified; `reason:` says why in one line. `completed` means every step
+succeeded. `verified` means every mandatory requirement passed its check,
+which can still miss bugs. Anything short of verified is followed by what is
+left: `step <id>: <status> (<kind>) — <why>` for each unfinished step,
+`requirement <id>: <status> — <why>` for each open requirement, and `steering
+not acted on:` for guidance that arrived too late. Then `your call:` gives one
+command per option:
+
+| Option | When | What to do |
+|---|---|---|
+| continue | the plan needs a fix, a new step, or a step redone | export, edit, and revise the plan (section 4) |
+| retry | a step stopped for a reason a retry fixes: no pool, a paused pool, a crashed or silent worker | `bullswarm workflow resume <shortId>` |
+| take over | the rest is small, or needs something only you have (a logged-in browser, a credential, a decision for the user) | do it yourself; `runs result <shortId> --json` names every step's output |
+| restart | the goal or the approach was wrong | start a new `workflow goal` run |
+
+`retry` appears only when a step is retryable. `resume` on a finished run
+reruns exactly those steps and the steps blocked behind them. When nothing is
+retryable it prints `nothing to retry`, starts nothing, and exits 1. A step
+whose pools were all paused shows `its pool is back at <time>`; resuming
+before then fails it again at once.
+
+A failed check is a plan problem, not a retry. When the check step reports a
+requirement failed, keep the same run: export the plan, add a step that fixes
+what the evidence names, and add that step's id to the check's `dependsOn`.
+The changed check runs again after the fix, and the run finishes again.
+
 Then read the real outputs and artifacts and probe the important edge cases
-yourself. `completed` means the graph ran. `verified` means evidence passed,
-which can still miss bugs. `partial` exposes failed or skipped branches; revise
-the plan to repair them (a revision reopens a finished run). Shared files
-remain after failure or cancellation. Exit 0 can mean launched, paused, or
-completed, so always inspect the returned status.
+yourself. Shared files remain after failure or cancellation. Exit 0 can mean
+launched, paused, or completed, so always inspect the returned status.
 
 ## 4. Steer a running workflow
 
@@ -174,7 +211,9 @@ Rules that matter when you edit:
   must not remain, give a new or amended step the job of reverting or repairing
   them.
 - Revising a finished run (`completed`, `partial`, `cancelled`) reopens it: the
-  new plan runs and the run finishes again with a new result.
+  new plan runs and the run finishes again with a new result. Steps a
+  cancellation stopped run again; failed steps run again only when named in
+  `rerun`.
 - To think without new work starting, pause first: `bullswarm workflow pause
   <shortId>` starts nothing new and lets running agents finish (`--now` stops
   them; they run again after resume). Export and revise while paused, then
@@ -183,7 +222,9 @@ Rules that matter when you edit:
   and `steering received`. Steering a person queued never halts work: decide
   what it means for the plan and revise. The exported file lists pending
   steering in `steeringIds`, and a revision from that file marks it delivered.
-  A run about to finish with unread steering pauses for it instead.
+  A run that finishes before you act on steering lists it as `steering not
+  acted on`; revising the finished run from a fresh export delivers it and
+  reopens the run.
 
 [operations.md](references/operations.md) covers the revision details, pause
 and resume, cancellation, scouting, a dispatched planner, isolation, watch

package/skill/references/operations.md

@@ -17,7 +17,7 @@ unless it asks for a dispatched one. The three ways to start:
 
 ```bash
 bullswarm workflow goal '<goal>' --cwd=<abs-dir> --program plan.json --json  # you plan (see below)
-bullswarm workflow goal '<goal>' --cwd=<abs-dir> --scout                     # kernel surveys, then pauses for your program
+bullswarm workflow goal '<goal>' --cwd=<abs-dir> --scout                     # kernel surveys, then finishes and hands you the report
 bullswarm workflow goal '<goal>' --cwd=<abs-dir> --orchestrator auto \
   --suggested-plan='<conceptual plan>' --json                                # dispatch a planner agent
 ```
@@ -69,7 +69,11 @@ heartbeat) instead of event mode; it applies only to V2 runs. A legacy
 authored-graph run cannot be watched at all: the watcher prints the legacy
 line and exits 2 before polling. `--classic` cannot combine with `--next`.
 The result command is the stable delivery/verification envelope; do not scrape
-task files or assume the last provider response is the deliverable.
+task files or assume the last provider response is the deliverable. A finished
+run's watch output ends with `outcome: <status> · verified|not verified`,
+`reason:`, the handback lines and `your call:` options (see "When a run
+finishes" below); under `--jsonl` the `finished` object carries `verified`,
+`reason` and `handback`.
 
 Manage a live run:
 
@@ -77,14 +81,14 @@ Manage a live run:
 bullswarm workflow plan export <shortId> --out plan.json           # the live plan as an editable revision document
 bullswarm workflow plan revise <shortId> --program plan.json --json # replace the plan at any time (see below)
 bullswarm workflow pause   <shortId> [--now]                       # start nothing new; --now also stops running agents
-bullswarm workflow resume  <shortId> [--foreground|--watch]        # lift a pause; verb form of goal --resume
+bullswarm workflow resume  <shortId> [--foreground|--watch]        # lift a pause, continue an interrupted run, or retry a finished one
 bullswarm workflow steer   <shortId> --message '<guidance>'        # guidance for whoever plans the run
 bullswarm workflow cancel  <shortId> --json                        # cooperative; a run with no kernel is finalized here
 ```
 
 Resume keeps the run's durable planner mode, routing pins, and settings;
 `--program`, `--orchestrator`, `--scout`, and `--suggested-plan` are rejected
-there (use `workflow plan submit` for a caller program). Autonomous resume is
+there (change the plan with `plan revise`). Autonomous resume is
 V2-only. An old autonomous run ID fails before dispatch; there is no migration
 or fallback executor. `bullswarm workflow goal --resume <shortId>` and
 `bullswarm workflow tui --cancel <shortId>` remain as aliases.
@@ -147,10 +151,11 @@ digest gets the digest entry in its `Dependency artifacts` list plus a
 `digestOf` array naming each digested source, so it can still open the
 originals.
 
-Two advisories report effort smells and never reject anything.
-`all-writers-high` fires when three or more `build`/`chore` actions run and none
-is below high effort; `docs-at-high` fires when a `build`/`chore` action owns
-only `*.md` files at high effort. `plan validate --json` carries them under
+Three advisories, none of which rejects anything. `all-writers-high` fires
+when three or more `build`/`chore` actions run and none is below high effort;
+`docs-at-high` fires when a `build`/`chore` action owns only `*.md` files at
+high effort; `requirement-unchecked` fires when a requirement is in no action's
+`evidenceFor`, so the run can finish but never verify it. `plan validate --json` carries them under
 `advisories` and its human output prints `advisory:` lines; `workflow goal`
 prints the same lines at launch. Exit codes are unchanged, and the kernel stores
 them on the run, so `workflow runs show` lists them afterwards. `runs result`,
@@ -159,8 +164,8 @@ them on the run, so `workflow runs show` lists them afterwards. `runs result`,
 ## Revising a live plan
 
 `plan revise` replaces the plan of a caller-planned program run at any moment:
-while agents run, while it is paused, while it waits at a planning boundary, or
-after it finished. Start from the export so kept actions compare equal:
+while agents run, while it is paused, or after it finished. Start from the
+export so kept actions compare equal:
 
 ```bash
 bullswarm workflow plan export <shortId> --out plan.json         # or --json for status + document
@@ -209,8 +214,10 @@ being replaced is stopped before the new plan is committed
 CLI applies the revision itself under the kernel lease and relaunches the
 kernel detached, unless the run is paused. A finished run is reopened: its
 `result.json` moves to `result-before-revision-<n>.json`, a
-`workflow.reopened` event is written, and the new plan runs to a new result. A
-revision also clears a caller-planner wait, so it can replace `plan submit`.
+`workflow.reopened` event is written, and the new plan runs to a new result.
+Steps a cancellation stopped return to pending (`reopened.requeued`); failed
+steps stay failed unless the revision names them in `rerun`. A revision also
+answers a run an older version left waiting for its caller.
 
 Stopping a process does not undo its edits in the shared tree. When a stopped
 or removed step's partial changes must go, amend it or add a step whose prompt
@@ -239,57 +246,76 @@ refused.
 `steering received`; the caller decides what the message means and revises.
 `plan export` lists undelivered steering under `pendingSteering` (with `--json`)
 and puts its ids in the document's `steeringIds`, so a revision from the export
-marks it delivered (`steering.delivered`, `source: revision`). When the graph
-would otherwise finish with steering still unread, the run pauses at a
-`steering` boundary instead; answer it with a revision (an acknowledgement-only
-revision is enough when the guidance needs no plan change) or with `plan
-submit`.
-
-## Submitting work at a planning pause
-
-Use these commands when `watch` reports a caller-planner pause:
-
-```bash
-bullswarm workflow plan show <shortId> --json
-bullswarm workflow plan submit <shortId> --program plan-2.json --watch
-```
-
-Read the current request and author only new actions; existing action IDs can
-be dependencies. `plan revise` is accepted at the same pause when the answer
-also changes, removes, or reruns existing actions. New shared programs pause
-for opt-in scouting or, in a run about to finish, unread steering, not negative
-evidence. A submission is validated before modifying the run. Resuming without
-a submission preserves the pause.
-
-Older saved runs can also pause for requirement gaps and accept
-`plan submit <shortId> --exhausted --reason '<why>'` there. Do not use
-`--exhausted` for a new program or a steering request.
-
-Pause hygiene, all kernel-enforced:
-
-- The pause is authoritative. A resume keeps the recorded boundary and turn
-  even when steering was queued meanwhile; the request is refreshed to list the
-  pending steering (`pendingSteering`, also merged into `context.steering`).
-  `plan show` performs the same refresh (`requestRefreshed: true`) without
-  changing run state. A submission marks exactly the listed steering
-  delivered (`steering.delivered` events tagged `source: caller`); steering
-  queued after the request was shown stays pending and opens a `steering`
-  boundary after the resume. A steering boundary needs at least one new action
-  (`--exhausted` is valid only at a `gaps` boundary and is only advertised
-  there).
-- `workflow cancel <id>` on a paused run finalizes it inline: no kernel is
-  alive to honor a cooperative request, so the cancelled result envelope is
-  written and the pause record cleared in that one command. If cancellation was
-  recorded some other way (`tui --cancel`), `plan submit` refuses every
-  submission and `plan show`/`watch` print `bullswarm workflow cancel <id>
-  --json`. Finalizing always clears `planner.awaiting`; a terminal state that
-  still claims to be waiting is rejected by the state validator.
-- A `--program` supplied at launch is kept as `initial-planner-response.json`
-  in the run directory until applied, so an interruption during an opt-in
-  `--scout` does not lose it.
-- Bare value flags (`--program` with no file, `--orchestrator` with no pool)
-  are usage errors (exit 2); nothing launches in a different mode. `plan submit`
-  checks the goal directory before touching state.
+marks it delivered (`steering.delivered`, `source: revision`). A run never
+waits for steering: if the graph finishes first, the result lists it under
+`handback.unreadSteering` and watch prints `steering not acted on`. Revise the
+finished run from a fresh export to deliver it; that reopens the run.
+
+## When a run finishes: the handback
+
+A run never waits: not for its caller, not for a paused pool, not for a silent
+worker. It finishes as soon as nothing more can happen on its own. The result
+carries a `handback` whenever it is not verified or has steering nobody acted
+on:
+
+- `handback.unfinished[]`: `{id, status, failureKind, why, retryAfter?,
+  retryable}` for every step that did not succeed. `retryable` says whether
+  `workflow resume` would run it again. `retryAfter` is set when every pool
+  able to run the step was paused: the earliest time one is back.
+- `handback.unresolvedRequirements[]`: `{id, status, why}` with the latest
+  evidence line, or `no evidence recorded for the current work`.
+- `handback.unreadSteering[]`: `{id, message, queuedAt}`.
+
+`runs result --summary` adds `handback.options`, one command per choice
+(`continue`, `retry` when a step is retryable, `takeOver`, `restart`). An open
+requirement keeps its `why` for as long as the 4 KB budget allows; concerns and
+per-step detail shrink first. The `workflow.finished` event carries
+`unfinished` and `unreadSteering` counts. The reason line says what happened:
+`all 4 steps succeeded, but no step checked the requirements, so the result is
+not verified`, or `2 of 5 steps did not succeed: build-api failed (stalled), …`.
+
+Where a run used to wait, it now finishes:
+
+| Situation | What happens |
+|---|---|
+| `--scout` with no program | `partial`: `no program to run (the scout report is at …)`; add steps with `plan revise` |
+| a launch program the kernel cannot accept | `partial`: the reason lists the issues; nothing ran |
+| requirements open with nothing left to run (older verified-mode runs) | `partial` with gaps |
+| steering unread when the last step ends | the run finishes; `unreadSteering` lists it |
+| every pool able to run a step is paused | the step fails at once (`unavailable` or `quota`) with `retryAfter` |
+| a worker writes nothing for 60 minutes | stopped as `stalled`, retried once mechanically, then handed back |
+| the kernel throws | the run is marked `interrupted` with `kernel stopped on an error: …`; `resume` continues it |
+
+Resume on a finished run is a retry. It reopens the run for pending and
+cancelled steps, failed steps whose kind a retry fixes (`provider`, `quota`,
+`auth`, `process`, `unavailable`, `interrupted`, `runtime`, `schema`,
+`stalled`), and the steps blocked behind them; moves `result.json` to
+`result-before-resume-<n>.json`; writes `workflow.reopened` with `source:
+resume`; and relaunches the kernel. A step that failed for any other reason
+(the worker reported failure, `ownership`) stays failed: change the plan with
+`plan revise`. With nothing retryable, resume prints `nothing to retry`, lists
+the steps that need you, starts nothing, and exits 1.
+
+The silence cutoff is `BULLSWARM_WORKER_SILENCE_SEC` (default 3600). It
+measures silence, not run time: every byte a worker writes restarts it.
+
+A `--program` supplied at launch is kept as `initial-planner-response.json` in
+the run directory until applied, so an interruption during an opt-in `--scout`
+does not lose it. Bare value flags (`--program` with no file, `--orchestrator`
+with no pool) are usage errors (exit 2); nothing launches in a different mode.
+
+### Runs an older version left waiting
+
+Runs started before 0.30.0 may still sit at a planning boundary; `watch`
+prints `waiting for the caller planner`. Either answer it (`plan show
+<shortId> --json`, then `plan submit <shortId> --program plan-2.json`, or
+`--exhausted --reason '<why>'` at a `gaps` boundary; a `plan revise` also
+answers it), or run `workflow resume <shortId>`, which finishes it and hands
+back what is left. `plan show` refreshes the request with steering queued
+since, and a submission marks exactly the listed steering delivered.
+`workflow cancel <id>` finalizes a waiting run inline; once cancellation is
+recorded, `plan submit` refuses every submission. `plan submit` checks the goal
+directory before touching state.
 
 ## Workspace and concurrency options
 
@@ -458,11 +484,17 @@ document and writes nothing.
   killed at once, the pool is quarantined until the reset the message named
   (else its cached 5-hour `resets_at`, else 30 minutes), and the action moves
   to a pool that still has quota. The quarantine holds across runs until it
-  expires. Discussing usage limits in a report is not a usage limit.
+  expires. When no pool able to run the step is left, the step fails at once
+  with `retryAfter` and the run hands it back; nothing waits for the reset.
+  Discussing usage limits in a report is not a usage limit.
 - A quota-gated preferred orchestrator falls back unless it was strictly pinned
   for QA.
-- Silence is evidence to inspect, not automatic proof of a hang. Check the TUI
-  or JSON activity and stall fields before cancellation.
+- A worker silent for `BULLSWARM_WORKER_SILENCE_SEC` (default 60 minutes) is
+  stopped as `stalled`. Shorter silence is evidence to inspect, not proof of a
+  hang: check the TUI or JSON activity and stall fields before cancelling.
+- `ownedFiles` naming a directory or a glob is refused at `plan validate` and
+  at launch, and so is a pinned pool that cannot run a step's lane and effort.
+  Both used to fail only after launch.
 - A malformed V2 planner program receives one compact deterministic correction
   request. Repeated invalidity ends planning before worker budget is spent.
 - Schema-invalid evidence receives a bounded correction in the same physical