bullswarm 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # bullswarm changelog
 
+## 0.13.0 — programs can complete themselves
+
+- A planner may attach `completion: { when: "all-actions-ok", reason }` to a
+  program (a `needs_more_work` decision that includes at least one verify).
+  When every action of that program — repairs included — finishes ok and the
+  completion policy is satisfied, the runtime records the `complete` decision
+  itself (`source: "program-completion"`, event `decision.auto_completed`) and
+  the run ends without another planner turn. Anything failing emits
+  `decision.completion_predicate_unmet` (with the failing action ids) and the
+  boundary returns to the planner as before. Measured motivation: in the goal-2
+  comparison every clean bullswarm run still paid a final 110–250 s planner
+  turn just to say "complete"; Claude's script ends when its code says so.
+
+## 0.12.1 — a burst-gated provider is waited for, never failed on the spot
+
+- `workflow` runs no longer die with `no eligible pool` when every candidate
+  pool is burst-gated (provider 5-hour window ≥ 90 % used). The runtime parks
+  the dispatch in a new `waiting_for_quota` stage (`state.quotaWait` names the
+  pool, its 5h usage and reset time; events `dispatch.waiting_for_quota`,
+  `dispatch.quota_available`, `dispatch.quota_wait_expired`), re-reads the
+  provider meter every 60 s, and continues the moment the gate lifts. It gives
+  up — with the pool, usage and reset time in the failure reason — only after
+  the known reset time plus 10 min of grace (5 h when no reset time is known).
+  The planner's context is composed after the wait, so it never sees an empty
+  pool list. Observed 2026-08-28 19:09 Z: the first 0.12.0 comparison run
+  failed in 4 s because the account's Claude 5h window read 91 % (reset
+  22:30 Z); Claude Code in the same situation waits on the rate limit.
+  Options for embedding callers/tests: `quotaPollMs`, `quotaWaitGraceMs`,
+  `quotaWaitUnknownResetMs` on `runWorkflow`; `readMeter` injection.
+
 ## 0.12.0 — one decision is a whole program
 
 Completes the convergence on Claude Code's dynamic-workflow mechanics

package/docs/claude-dynamic-workflow-mechanics.md

@@ -316,6 +316,19 @@ author and the `Workflow` runtime.
    sees `outputs.scout.ok=false` with the reason, and a run where only the
    scout succeeded is `blocked`, never "delivered".
 
+8. **Program-level completion** (0.13.0, unreleased at the time of writing) —
+   `completion: { when: "all-actions-ok", reason }` on a program. Claude's
+   script simply returns when its code is done; bullswarm still spent a final
+   planner turn (110–250 s measured) to say `complete` after a clean run. Now
+   the runtime records that decision itself (`source: "program-completion"`,
+   never below the completion policy) and consults the planner only when
+   something failed. With 0.12.0's repair-in-program this makes a clean run
+   **one planner turn**: compile, execute, done — Claude's "0 orchestrator turns
+   during execution" for the passing case.
+9. **Rate limits are waited for** (0.12.1): a burst-gated provider parks the
+   dispatch in `waiting_for_quota` until the window resets instead of failing
+   the run in 4 s, which is what the first 0.12.0 comparison launch did.
+
 **Honest limitation.** `itemsFrom` removes the planner *turn*, not the stage
 *barrier*: a verify depending on a data-driven fan-out waits for all items,
 whereas Claude's `pipeline()` overlaps verify-B with fix-C for discovered items

package/docs/experiments/2026-08-29-ultracode-vs-bullswarm.md

@@ -327,15 +327,94 @@ three fixes on "non-blocking" nits from verifiers that had returned
 
 ### bullswarm 0.12.0 (installed binary) — same goal, fresh copy `g2-bs-v3`
 
-(pending — after the 0.12.0 release)
+**First launch, 19:09:48 Z, installed 0.12.0 — failed in 4 s.** Both the
+scout and the orchestrator were `failed_terminal` with `no eligible pool`
+before any process was spawned. Cause: the account's Claude 5-hour window read
+**91 %** (live meter at 19:09:49 Z, reset 22:30 Z) after the two long Opus
+runs, so the pace gate excluded the only pool. Not a 0.12.0 regression (the
+gate pre-dates it) but exactly the class of difference this comparison is
+for: Claude Code, rate-limited mid-workflow, waits and retries; bullswarm
+failed the run with no reset time in the reason. Fixed as **0.12.1** (`beeed94`):
+the runtime parks the dispatch in `waiting_for_quota`, re-reads the meter
+every 60 s, continues when the window resets, and only fails — naming pool,
+usage and reset time — after reset + 10 min grace.
+
+(re-run on 0.12.1 pending — it starts as soon as the 5h window resets at 22:30 Z)
 
 The originally planned 0.10.9 goal-2 run was dropped at the user's request
 (2026-08-29): the installed latest is the only baseline that matters.
 
 ## Behaviour differences observed
 
-(pending)
+Same goal, same fixture, same model (Opus for every worker and for bullswarm's
+planner; the Claude session's author was Opus too). Read left to right: what
+Claude did, what bullswarm 0.11.1 did on the identical run, and what 0.12.x
+now does about it (built and unit-tested; the live re-run below is the
+confirmation).
+
+| Dimension | Claude Code `Workflow` (ultracode) — observed | bullswarm 0.11.1 — observed | bullswarm 0.12.0 / 0.12.1 — built |
+| --- | --- | --- | --- |
+| Who plans, and when | The session author read every file and ran the tests inline (4 min), then wrote **one script** (23 k chars, 5 `agent()` sites). **0 orchestrator turns during the 48 min 51 s of execution.** | The planner compiled the **whole 14-action graph in one decision** (253 s) — but blind: goal text + cwd only, no repo survey, no worker output text in its context. Consulted **3 times** (253 s, 304 s, 110 s) = **27 % of wall**. | Read-only `scout` action before the planner; `outputExcerpt` of every finished action in the planner context; prompt reframed as "compile the goal into a PROGRAM"; planner told it is consulted only at the program boundary. |
+| Item discovery | `pipeline(MODULES, probe, author, verify, fix-loop)` over a known list; when a list is unknown Claude discovers it inline *before* writing the script. | Goal named the six modules → inlined them. Nothing to discover here. | `fanout.itemsFrom: "outputs.<discovery>.outFile"` resolved at run time (+ one bounded read-only extraction retry), so an unknown item count never costs a planner turn. |
+| Parallel width and overlap | **6 concurrent** (= six items, cap 8), mean parallelism 3.1. Per-item pipeline: author-B starts the second probe-B ends; no barriers. | **6 concurrent**, mean parallelism 2.74. Ready-set scheduler: each `verify-<m>` started the second its own `module-<m>` finished; `docs-index` waited for all six by design. | Unchanged for known items. Limitation stays: a verify on a *discovered* fan-out waits for all items (no per-item chain inside a fan-out yet). |
+| Verify → fix | Fix loops **pre-authored in code** (`while (!verdict.ok && rounds < N)`): slugify ×2, intervals ×1, all inside the script; 9 verifies, 3 fixes, 0 planner involvement. | A failed/blocked verify came back to the **planner** (turn 2, 304 s), which authored `slugify-recheck` + `verify-slugify-2`. Round trip ≈ 5 min before the fix even started. | `verify.repair { prompt, maxRounds 1–3 }` — the executor runs `<verify>-repair-<n>` with the concerns verbatim and re-runs the same verify; only still-failing verifies return to the planner. |
+| Passing verifies with nits | Schema-forced `{ok, issues}`; the script fixes only when `!ok`. Nits on passing modules were ignored. | Planner spent **2 of 3 remediation fixes** (`polish-semver`, `polish-lru`) on "non-blocking" notes from verifiers that had returned `ok:true` — an extra ~10 min program round. | Doctrine line: an `ok:true` verify is accepted; its concerns are informational. |
+| Robustness to content | Prompts are JS strings; the runtime substitutes nothing. A parse error in the *script* was caught by the harness and corrected inline in 94 s. | The template renderer parsed **any** `{{…}}` — in a planner prompt *and* in the review artifact it appended. `verify-slugify` died at render time with **0 attempts**, blocked `verify-suite`, cost a planner round, and the fix **rewrote fixture source** (JSDoc) to dodge the bug. | Only a known root + dotted identifiers is a template ref; other double braces are text. `verify` appends the reviewed artifact verbatim, never rendered. |
+| Provider rate limits | Agents retry on API errors; a terminal error resolves the agent to `null`, the script keeps going. The session waits. | Pool burst-gated (5h window 91 %) → the whole run **failed in 4 s** with `no eligible pool`, no reset time named (first 0.12.0 launch, 19:09 Z). | 0.12.1: `waiting_for_quota` stage, meter re-read every 60 s, continue when the window resets; fail only after reset + 10 min grace, naming pool / usage / reset time. |
+| Structured worker output | `schema:` forces a `StructuredOutput` tool call; mismatches retry at the tool layer, so the script never parses prose. | Prose "content gate" (`looksLikeWork`); a bare JSON array answer was rejected as an "announcement"; the verify verdict is the only structured channel. | Content gate accepts JSON; `parseJsonArray` prefers the trailing array; one extraction action when discovery output has no array. A general `outputSchema` on run actions is still open. |
+| Failure semantics | In code: `parallel()` never rejects, a throwing stage drops its item to `null`, `.filter(Boolean)`. | Runtime `onError: continue` per step; failed dependencies block dependents; blocked graph → planner. | Same, plus: a failed scout is non-fatal; fan-out `ok` is a boolean so dependents can wait on a whole fan-out. |
+| Outcome quality (audits, read-only) | 168/168 tests (52 + 116 new); existing tests byte-identical; `src` comment-only; every deliverable present. | 130/130 tests (52 + 78 new); existing tests byte-identical; `src` comment-only; every deliverable present. | — (re-run below) |
+| Time and agents | 58 min end to end; 24 agents. | 41 min end to end; 22 dispatches. Faster because it wrote fewer tests per module (11–15 vs 16–24) and skipped Claude's probe stage — not because it orchestrated better. | — |
+
+The short version: after 0.11.x the *shape* already matched (one decision =
+whole graph, six in parallel, per-item verify overlap). What still separated
+the two was everything Claude keeps **inside the program** — reading the repo
+before planning, data-driven fan-out, repair loops, tolerating passing-with-
+nits, tolerating rate limits — which bullswarm was still paying a 2–5 minute
+planner round trip for, or failing on. 0.12.0/0.12.1 move each of those into
+the runtime.
 
 ## What to change in bullswarm
 
-(pending)
+**Shipped in this cycle** (0.12.0 `c1b71a8`, 0.12.1 `beeed94`; all covered by
+unit tests, 295/295):
+
+1. Orchestrator as **compiler**: prompt reframed; planner consulted only at the
+   program boundary; `programFeatures: ['itemsFrom', 'repair']` advertised.
+2. `fanout.itemsFrom` — data-driven fan-out resolved at execution time, one
+   bounded read-only extraction retry, `maxItemsPerExpansion` default 24.
+3. `verify.repair { prompt, maxRounds }` — pre-authored fix loops run by the
+   executor.
+4. Fan-out summary artifact; fan-out `ok` is a boolean (count in `succeeded`).
+5. `scout` step before the first program (`--no-scout`), non-fatal.
+6. `outputExcerpt` for every output in the planner context.
+7. Content gate accepts structured JSON; `parseJsonArray` prefers the
+   trailing array.
+8. Template refs are grammar-checked; review artifacts are never rendered.
+9. Doctrine: `ok:true` verifies are accepted; concerns are informational.
+10. Burst-gated providers are waited for (`waiting_for_quota`), not failed.
+11. **Program-level completion predicate** (`0bcfd21`, 0.13.0 unreleased while
+    the 0.12.1 observation run is in flight): `completion: { when:
+    "all-actions-ok", reason }` lets a clean program record its own `complete`
+    decision — no final planner turn (110 s here) just to say so. Anything
+    failing still returns to the planner.
+
+**Still open, in priority order** (each is a measured gap, not a guess):
+
+1. **Per-item chains for discovered items.** `itemsFrom` removes the planner
+   turn but not the stage barrier; a fan-out whose `stepTemplate` is itself a
+   chain (`run → verify(repair)` per item) would give Claude's `pipeline()`
+   overlap for unknown item lists too.
+2. **General `outputSchema` on run actions** (Claude's `StructuredOutput`):
+   validate a worker's JSON at the dispatch layer and retry once, instead of
+   the prose gate plus an extraction action.
+3. **Planner latency.** Every planner turn is a fresh `claude -p --resume`
+   process reading a large durable context (253–304 s here vs Claude's ~4 min
+   *once*). With repair-in-program and self-completion a clean run is one turn;
+   the remaining lever is a smaller planner context (excerpts already budgeted
+   at 36 k chars).
+4. **Adversarial verification by default.** Claude's script verified every
+   module with a reviewer told to *refute*; bullswarm's verify prompt is
+   whatever the planner wrote. A default skeptic framing in the verify wrapper
+   is cheap and would have caught nothing extra here — listed for parity, not
+   urgency.

package/package.json

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

@@ -355,6 +355,12 @@ that expressible without extra turns:
   `ok:false`, the executor runs `<verifyId>-repair-<n>` (`source:
   "repair-policy"`) with the verifier's concerns verbatim and re-runs the same
   verify, up to `maxRounds` (1–3), without a planner turn.
+- `completion: { when: "all-actions-ok", reason }` (top level of a program) —
+  when every action of the program, repairs included, finishes ok and the
+  completion policy is met, the runtime records the `complete` decision itself
+  (`source: "program-completion"`, event `decision.auto_completed`) and the run
+  ends without another planner turn; a failing action emits
+  `decision.completion_predicate_unmet` and the boundary returns to the planner.
 
 Every fan-out records a summary artifact as `outputs.<id>.outFile` and a
 boolean `ok` (item count in `succeeded`), so a verify may depend on a fan-out
@@ -363,6 +369,12 @@ finished action reported), and `workflow goal` runs a read-only `scout` action
 first (`--no-scout` to skip) so the first program is compiled from a real
 survey of the repository rather than from the goal text alone.
 
+A burst-gated provider (5-hour window ≥ 90 % used) is a *wait*, not a
+failure: the run parks in stage `waiting_for_quota` (`state.quotaWait` shows
+the pool, usage and reset time), re-reads the meter every 60 s, and continues
+when the window resets. Only after the reset time plus 10 min of grace does the
+action fail, with the gate named in `why`.
+
 Allowed planner decisions are `proceed`, `complete`, `needs_more_work`,
 `retry`, `escalate`, `wait_for_approval`, and `stop`. Expansion decisions must
 contain bounded actions; malformed or over-budget output executes nothing.

package/src/workflow/decision.js

@@ -42,6 +42,9 @@ export const REVIEW_PATH_RE = /^outputs\.([A-Za-z0-9_-]+(?:\[\d+\])?)\.outFile$/
 // action whose output ends with a JSON array of items.
 export const ITEMS_FROM_RE = /^outputs\.([A-Za-z0-9_-]+)(?:\.outFile)?$/;
 export const REPAIR_MAX_ROUNDS = 3;
+// Program-level completion predicates a planner may attach to a program so the
+// runtime can record completion itself when every action finishes ok.
+export const COMPLETION_PREDICATES = new Set(['all-actions-ok']);
 
 export function looksLikeItemsFromPath(value) {
   return typeof value === 'string' && ITEMS_FROM_RE.test(value.trim());
@@ -117,6 +120,27 @@ export function validateDecisionProposal(proposal, {
   if (currentActionCount + safeActions.length > maxActions) {
     issues.push(`proposal would exceed maxActions=${maxActions}`);
   }
+  if (proposal.completion !== undefined) {
+    const completion = proposal.completion;
+    if (!completion || typeof completion !== 'object' || Array.isArray(completion)) {
+      issues.push('completion must be an object {"when":"all-actions-ok","reason":"…"}');
+    } else {
+      if (!COMPLETION_PREDICATES.has(completion.when)) {
+        issues.push(`completion.when must be one of: ${[...COMPLETION_PREDICATES].join(', ')}`);
+      }
+      if (completion.reason !== undefined && (typeof completion.reason !== 'string' || !completion.reason.trim())) {
+        issues.push('completion.reason must be a non-empty string when present');
+      }
+      for (const key of Object.keys(completion)) {
+        if (!['when', 'reason'].includes(key)) issues.push(`completion.${key} is not a planner field`);
+      }
+      if (proposal.decision !== 'needs_more_work') {
+        issues.push('completion is only meaningful on a needs_more_work decision (a program)');
+      } else if (!safeActions.some((action) => action?.type === 'verify')) {
+        issues.push('a self-completing program must include at least one verify action');
+      }
+    }
+  }
 
   const known = new Set(knownActionIds);
   const proposedIds = new Set(safeActions.map((action) => action?.id).filter((id) => typeof id === 'string'));
@@ -246,5 +270,8 @@ export function validateDecisionProposal(proposal, {
     decision: proposal.decision,
     reason: proposal.reason.trim(),
     actions: safeActions.map((action) => ({ ...action, dependsOn: [...(action.dependsOn ?? [])] })),
+    ...(proposal.completion
+      ? { completion: { when: proposal.completion.when, ...(proposal.completion.reason ? { reason: proposal.completion.reason.trim() } : {}) } }
+      : {}),
   };
 }

package/src/workflow/goal.js

@@ -20,7 +20,7 @@ export const AUTONOMOUS_ORCHESTRATOR_PROMPT = [
   '3. Give workers self-contained prompts with the exact goal, absolute working directory, the files they may edit (and that they must not touch others), the expected artifact, and the exact acceptance command. A worker sees only its own prompt.',
   '4. Assign every action a short kebab-case phase name such as discover, fix, verify-items, or verify-suite. Phases are forward-only: never append new work to a phase that already finished.',
   '5. Use dependsOn only for real data or same-file ordering dependencies. For N known items propose N fix actions and N verify actions (each verify depending only on its own fix) plus one final verify depending on all of them; use fanout with inline items when every item needs the identical prompt. When the item count is unknown, propose a discovery run whose prompt ends with "RETURN ONLY a JSON array of <items>" and a fanout with itemsFrom "outputs.<discovery-id>.outFile", so the runtime fans out the moment discovery finishes.',
-  '   A verify action with exactly one dependency automatically reviews that dependency artifact (a fan-out artifact summarises every item); you do not need to supply a review path. Give every verify a repair policy {"prompt": "<how to fix what the verifier rejects>", "maxRounds": 1-3} so a rejected verdict is fixed and re-checked inside the program instead of costing another checkpoint.',
+  '   A verify action with exactly one dependency automatically reviews that dependency artifact (a fan-out artifact summarises every item); you do not need to supply a review path. Give every verify a repair policy {"prompt": "<how to fix what the verifier rejects>", "maxRounds": 1-3} so a rejected verdict is fixed and re-checked inside the program instead of costing another checkpoint. When the program ends with verification that would satisfy the goal, add a top-level "completion": {"when": "all-actions-ok", "reason": "<what a clean run proves>"} so a clean run is recorded as complete without another checkpoint.',
   '6. Recover from a failed action with a new bounded action in a new phase when useful; do not repeat an identical failed plan.',
   '7. Require concrete verification of changed behavior. For code changes, obtain relevant test or inspection evidence before completion.',
   '8. Return complete only when durable outputs prove the original goal and its acceptance checks are satisfied.',

package/src/workflow/runner.js

@@ -258,6 +258,10 @@ export async function runWorkflow(opts) {
     runDir,
     onEvent: opts.onEvent,
     env: opts.env,
+    readMeter: opts.readMeter,
+    quotaPollMs: opts.quotaPollMs,
+    quotaWaitGraceMs: opts.quotaWaitGraceMs,
+    quotaWaitUnknownResetMs: opts.quotaWaitUnknownResetMs,
   });
   state.runner = {
     pid: process.pid,
@@ -1038,6 +1042,59 @@ async function runDecisionLoop({ runtime, gate, phase, state, retryAttempts }) {
     runtime.emit('kernel.checkpointed', { stage: 'executing', gateId: gate.id });
     const executed = await executeActions(proposal.actions);
     if (!executed.ok) return executed;
+
+    // Program-level completion: the planner said "if every action of this
+    // program (repairs included) finishes ok, that IS completion". Judge it
+    // by data — no planner turn — but never below the completion policy.
+    if (proposal.completion?.when === 'all-actions-ok') {
+      const programActions = (state.plan.actions ?? []).filter((entry) => entry.decisionSequence === decision.sequence);
+      const ledgerById = new Map((state.actionLedger ?? []).map((entry) => [entry.id, entry]));
+      const failing = programActions
+        .filter((entry) => !ledgerById.has(entry.id) || !actionOutputOk(ledgerById.get(entry.id), state.outputs))
+        .map((entry) => entry.id);
+      const dynamicActions = (state.actionLedger ?? []).filter((action) => action.parentId === gate.id);
+      const gaps = failing.length ? [] : completionEvidenceGaps(dynamicActions, state.orchestration?.completionPolicy, state.outputs);
+      if (!failing.length && !gaps.length) {
+        const verifyIds = programActions.filter((entry) => entry.kind === 'verify').map((entry) => entry.id);
+        const reason = proposal.completion.reason?.trim()
+          || `Program completed: all ${programActions.length} actions finished ok, verified by ${verifyIds.join(', ')}.`;
+        const auto = {
+          sequence: (state.decisions?.length ?? 0) + 1,
+          gateId: gate.id,
+          decision: 'complete',
+          reason,
+          actions: [],
+          artifact: null,
+          createdAt: new Date().toISOString(),
+          accepted: true,
+          source: 'program-completion',
+          predicate: 'all-actions-ok',
+          programSequence: decision.sequence,
+        };
+        state.decisions.push(auto);
+        runtime.emit('decision.created', auto);
+        runtime.emit('decision.auto_completed', {
+          gateId: gate.id, sequence: auto.sequence, programSequence: decision.sequence,
+          actions: programActions.map((entry) => entry.id), reason,
+        });
+        state.outcome = {
+          status: 'completed',
+          verified: true,
+          bestEffort: false,
+          reason,
+          concerns: [],
+          deliveryActionId: dynamicActions.filter((action) =>
+            action.kind !== 'verify' && actionOutputOk(action, state.outputs)).at(-1)?.id ?? null,
+          source: 'program-completion',
+        };
+        state.outputs[gate.id] = { ...state.outputs[gate.id], ok: true, why: reason, autoCompleted: true };
+        runtime.persist();
+        return { ok: true, why: reason, complete: true, decision: { decision: 'complete', reason, actions: [], completion: proposal.completion } };
+      }
+      runtime.emit('decision.completion_predicate_unmet', {
+        gateId: gate.id, programSequence: decision.sequence, failing, gaps,
+      });
+    }
     // Loop intentionally returns to observation and invokes the planner again.
   }
 }

package/src/workflow/runtime.js

@@ -35,6 +35,7 @@ import { aggregateUsage } from '../lib/usage.js';
 import { classifyAgentProgress, recordAgentAction } from '../lib/agent-events.js';
 import { deliverSteering } from './steering.js';
 import { resolveDispatchModel } from '../lib/strategy.js';
+import { getMeterReading } from '../meters/registry.js';
 
 // Cap how much of each step's output we keep inline in state.json.
 // Persisting full transcripts bloat state.json on long workflows. The
@@ -45,6 +46,12 @@ const FANOUT_ITEM_EXCERPT_BYTES = 6_000;
 // What the planner sees of each action's output (per output / all outputs).
 const PLANNER_EXCERPT_CHARS = 3_000;
 const PLANNER_EXCERPT_TOTAL_CHARS = 36_000;
+// A burst gate (provider 5h window >= 90 % used) is a WAIT, never a hard stop:
+// the runtime parks the dispatch until the window resets (+ grace), re-reading
+// the meter every QUOTA_POLL_MS, and only then fails with the reset time named.
+export const BURST_WAIT_GRACE_MS = 10 * 60_000;
+export const BURST_WAIT_UNKNOWN_RESET_MS = 5 * 3600_000;
+export const QUOTA_POLL_MS = 60_000;
 
 export function plannerBudgetContext(budget = {}) {
   const dispatchesUsedBeforePlanner = Number(budget.dispatchesUsed ?? 0);
@@ -110,6 +117,11 @@ export class WorkflowRuntime {
       );
     this.limiter = concap;
     this.parentEnv = opts.env ?? process.env;
+    // Meter refresh used while waiting on a burst gate; tests inject a fake.
+    this.readMeter = opts.readMeter ?? ((name) => getMeterReading(name, { force: true }));
+    this.quotaPollMs = Math.max(10, Number(opts.quotaPollMs ?? this.state?.settings?.quotaPollMs ?? QUOTA_POLL_MS));
+    this.quotaWaitGraceMs = Math.max(0, Number(opts.quotaWaitGraceMs ?? BURST_WAIT_GRACE_MS));
+    this.quotaWaitUnknownResetMs = Math.max(0, Number(opts.quotaWaitUnknownResetMs ?? BURST_WAIT_UNKNOWN_RESET_MS));
     // Counters used for planner-visible advisory budgeting.
     this.state.attempts ??= [];
     this.state.actionLedger ??= [];
@@ -244,9 +256,13 @@ export class WorkflowRuntime {
    * before selection (R8).
    */
   async dispatch(step, taskText, targetDir, paths, opts = {}) {
+    if (this.state.cancelRequested) return { ok: false, keepOnClaude: false, why: 'workflow cancellation requested', pick: { pool: null }, meta: {} };
+    const effortTier = step.effort ?? ({ analyze: 'high', build: 'medium', chore: 'low' }[step.lane ?? 'chore']);
+    // A burst-gated provider is waited for (outside the concurrency permit),
+    // never failed on the spot.
+    await this.awaitBurstRoom(step, effortTier, this.actionId(step, opts));
     if (this.state.cancelRequested) return { ok: false, keepOnClaude: false, why: 'workflow cancellation requested', pick: { pool: null }, meta: {} };
     return this.limiter.runWith(async () => {
-      const effortTier = step.effort ?? ({ analyze: 'high', build: 'medium', chore: 'low' }[step.lane ?? 'chore']);
       const attemptPools = this.preparePools(step, effortTier);
       let lastVerdict = null;
       const retryAllowance = Math.max(0, Math.min(Number(opts.retryAttempts ?? 1), 3));
@@ -269,10 +285,13 @@ export class WorkflowRuntime {
         });
         if (!route.pick) {
           if (lastVerdict) return lastVerdict;
+          const stillGated = attemptPools.length ? [] : this.burstGatedPoolsFor(step, effortTier);
           const refused = {
             ok: false,
             keepOnClaude: false,
-            why: `no eligible pool (${route.why})`,
+            why: stillGated.length
+              ? `no eligible pool: every candidate is burst-gated (${WorkflowRuntime.describeBurstGate(stillGated)}) and the wait for the window expired`
+              : `no eligible pool (${route.why})`,
             pick: { pool: null },
             meta: { exitCode: null },
           };
@@ -656,7 +675,7 @@ export class WorkflowRuntime {
     });
   }
 
-  preparePools(step, effortTier = step.effort ?? ({ analyze: 'high', build: 'medium', chore: 'low' }[step.lane ?? 'chore'])) {
+  preparePools(step, effortTier = step.effort ?? ({ analyze: 'high', build: 'medium', chore: 'low' }[step.lane ?? 'chore']), { ignoreBurstGate = false } = {}) {
     // Fresh eligible list per dispatch: enabled, not quarantined, and
     // not currently burst-gated (R8). Quarantine has been applied to
     // pool.quarantine by the live buildPools pass; if a previous
@@ -667,7 +686,7 @@ export class WorkflowRuntime {
       if (pool.quarantine && !isQuarantined(pool, now)) pool.quarantine = null;
     }
     return this.pools.filter(
-      (p) => p.enabled !== false && !isQuarantined(p, now) && p.burstGate !== true &&
+      (p) => p.enabled !== false && !isQuarantined(p, now) && (ignoreBurstGate || p.burstGate !== true) &&
         (step.pool == null || p.name === step.pool) &&
         !(step.avoidPools ?? []).includes(p.name) &&
         (step.requiresCapabilities ?? []).every((capability) =>
@@ -682,6 +701,92 @@ export class WorkflowRuntime {
     }).filter((pool) => pool.modelPolicy.eligible);
   }
 
+  /** Pools that would serve this step if they were not burst-gated. */
+  burstGatedPoolsFor(step, effortTier) {
+    return this.preparePools(step, effortTier, { ignoreBurstGate: true }).filter((p) => p.burstGate === true);
+  }
+
+  static describeBurstGate(pools) {
+    return pools.map((p) => {
+      const w = p.meterSnapshot?.five_hour ?? {};
+      const used = Number.isFinite(w.utilization) ? `${Math.round(w.utilization)}% used` : 'usage unknown';
+      const resets = w.resets_at ? `resets ${new Date(w.resets_at).toISOString().replace(/\.\d{3}Z$/, 'Z')}` : 'reset time unknown';
+      return `${p.name} 5h window ${used}, ${resets}`;
+    }).join('; ');
+  }
+
+  /**
+   * If every pool that could serve `step` is burst-gated, wait for the gate
+   * to lift instead of failing the action: the provider window resets at a
+   * known time, the run is durable, and a failed run costs more than a late
+   * one. Re-reads the meters every quotaPollMs; gives up (so the caller fails
+   * with a clear reason) only after the latest known reset + grace, or after
+   * BURST_WAIT_UNKNOWN_RESET_MS when no reset time is known.
+   */
+  async awaitBurstRoom(step, effortTier, actionId = step.id) {
+    const gatedOnly = () => {
+      if (this.preparePools(step, effortTier).length) return null;
+      const gated = this.burstGatedPoolsFor(step, effortTier);
+      return gated.length ? gated : null;
+    };
+    let gated = gatedOnly();
+    if (!gated) return { waited: false };
+    const resetTimes = gated.map((p) => Date.parse(p.meterSnapshot?.five_hour?.resets_at ?? '')).filter(Number.isFinite);
+    const startedAt = Date.now();
+    const deadline = resetTimes.length
+      ? Math.max(...resetTimes) + this.quotaWaitGraceMs
+      : startedAt + this.quotaWaitUnknownResetMs;
+    const previousStage = this.state.stage;
+    this.state.stage = 'waiting_for_quota';
+    this.state.quotaWait = {
+      actionId,
+      since: new Date(startedAt).toISOString(),
+      until: new Date(deadline).toISOString(),
+      pools: gated.map((p) => ({
+        name: p.name,
+        fiveHourUsedPct: p.meterSnapshot?.five_hour?.utilization ?? null,
+        resetsAt: p.meterSnapshot?.five_hour?.resets_at ?? null,
+      })),
+    };
+    this.emit('dispatch.waiting_for_quota', { actionId, ...this.state.quotaWait, detail: WorkflowRuntime.describeBurstGate(gated) });
+    const cancelled = () => {
+      if (this.state.cancelRequested) return true;
+      try { return JSON.parse(readFileSync(join(this.runDir, 'state.json'), 'utf8')).cancelRequested === true; } catch { return false; }
+    };
+    let lifted = false;
+    while (Date.now() < deadline && !cancelled()) {
+      await new Promise((resolve) => setTimeout(resolve, Math.min(this.quotaPollMs, Math.max(1, deadline - Date.now()))));
+      for (const gatedView of gated) {
+        // preparePools hands out copies; the gate lives on the pool itself.
+        const pool = this.pools.find((p) => p.name === gatedView.name) ?? gatedView;
+        let reading = null;
+        try { reading = await this.readMeter(pool.name); } catch { reading = null; }
+        // Only a real provider snapshot may open or keep the gate; a pool
+        // without a meter reader ('none') leaves the gate as it was.
+        if (!reading?.snapshot) continue;
+        pool.burstGate = reading.burstGate === true;
+        pool.meterSnapshot = reading.snapshot;
+        if (reading.pacing) {
+          pool.usedPct = reading.pacing.usedPct ?? pool.usedPct;
+          pool.elapsedPct = reading.pacing.elapsedPct ?? pool.elapsedPct;
+          pool.pace = reading.pacing.surplus ?? pool.pace;
+        }
+      }
+      gated = gatedOnly();
+      if (!gated) { lifted = true; break; }
+    }
+    const waitedMs = Date.now() - startedAt;
+    delete this.state.quotaWait;
+    this.state.stage = previousStage;
+    if (lifted) {
+      this.emit('dispatch.quota_available', { actionId, waitedMs });
+    } else {
+      this.emit('dispatch.quota_wait_expired', { actionId, waitedMs, detail: gated ? WorkflowRuntime.describeBurstGate(gated) : null, cancelled: cancelled() });
+    }
+    this.persist();
+    return { waited: true, lifted, waitedMs, gated };
+  }
+
   appendDecision(step, poolName, verdict, paths, routing = null) {
     try {
       const coreState = loadState(this.bullswarmDir);
@@ -934,6 +1039,7 @@ export class WorkflowRuntime {
 
   async runDecision(step, scope, opts = {}) {
     this.enforceRequiredInputs(step.id);
+    await this.awaitBurstRoom(step, step.effort ?? 'high', step.id);
     const deliveredSteering = deliverSteering(this.state, this.runDir);
     for (const steering of deliveredSteering) {
       this.emit('steering.delivered', {
@@ -1016,7 +1122,7 @@ export class WorkflowRuntime {
       executionConstraints: {
         concurrency: Number(this.state.settings?.concurrency ?? 1) || 1,
         readySiblingsRunConcurrently: true,
-        programFeatures: ['itemsFrom', 'repair'],
+        programFeatures: ['itemsFrom', 'repair', 'completion'],
         plannerConsultedOnlyAtProgramBoundary: true,
         actionTimeoutSec: Number(step.actionDefaults?.timeoutSec ?? step.timeoutSec) || null,
         actionTimeoutIsExplicitOptIn: step.actionDefaults?.timeoutSec != null || step.timeoutSec != null,
@@ -1073,6 +1179,7 @@ export class WorkflowRuntime {
       '- Unknown item count: never spend a decision to learn how many items there are. Propose a discovery run action whose prompt ends with "RETURN ONLY a JSON array of <items>", plus a fanout with "itemsFrom":"outputs.<discovery-id>.outFile" whose stepTemplate.prompt uses {{item}}. The runtime resolves the list when discovery finishes (with one bounded read-only extraction retry if the output is not a clean array) and fans out immediately.',
       '- Verification failures: give each verify a "repair" policy {"prompt":"<how to fix what the verifier rejects>","maxRounds":1-3}. When the verifier returns ok:false, the runtime runs a fix action carrying the verifier concerns verbatim and re-runs the same verify, inside the program. Only verifies still failing after their rounds come back to you.',
       '- A verify that returned ok:true is accepted. Its concerns are informational (overlaps, wording nits, "non-blocking" notes): do not spend a program round polishing them unless the goal text itself demands it. Only ok:false verifies are work.',
+      '- Self-completing programs: when the program you propose ends with verification that would satisfy the goal, add a top-level "completion": {"when":"all-actions-ok","reason":"<what a clean run proves>"}. If every action of the program (repairs included) finishes ok and the completion policy is met, the runtime records the completion itself and does not consult you again; anything failing brings the boundary back to you. Use it on every program whose clean run would be the finished goal.',
       '- Per-item chains: for N known items propose N focused run actions plus N verify actions, each verify depending only on its own run, so verifying one item overlaps with fixing another; add one final verify depending on all of them. For items discovered at run time use the discovery → fanout → verify shape above.',
       '- File ownership: every action prompt must name exactly which files it may edit and state that it must not touch any other file. Two actions that must edit the same file MUST be ordered with dependsOn; never let concurrent actions write the same file.',
       '- Self-contained prompts: a worker sees only its own prompt, never this context. Each prompt must state the absolute working directory, what to read, what to change, the exact command that proves success, and what to report back. Prefer many small parallel actions over one large serial one.',