bullswarm 0.25.2 → 0.25.4

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # bullswarm changelog
 
+## 0.25.4 — reasoning levels
+
+- A connector now declares how its own CLI expresses a thinking level, and
+  every dispatch resolves exactly one level per attempt. The block is
+  `reasoning: { flag | args, levels, defaults, skipModels? }` — `flag` for a
+  CLI that takes `--effort <level>`, `args` for one whose control is a config
+  override (`-c model_reasoning_effort={level}`). The packaged `claude-code`,
+  `codex`, `grok`, and `command-code` templates carry the block read from
+  their installed CLIs or an official source (Claude Code and Command Code from
+  `--help`, Codex from its config reference, Grok from the binary's own
+  validation message); Command Code's model-dependent set stays marked
+  UNVERIFIED rather than invented. One shared resolver applies the precedence
+  chain — the action's own `reasoning` field, the run-wide override, the
+  configured `strategy.reasoning` level for that pool and tier, the same for
+  the tier globally, then the connector's default for the effort tier — so
+  the first layer that sets a level wins, not the strongest. The level is
+  appended to the spawned command exactly as `--model` is appended today;
+  nothing is appended for a connector with no block, for the literal level
+  `default`, or for a model the connector marks under `skipModels`. A level
+  the connector does not accept is clamped to the nearest one it does, never
+  dropped and never invented. `{ requested, applied, source, clamped }` is
+  recorded on every attempt, in the decision log, in `bullswarm run --json`,
+  in the V2 result envelope, and in the new `bullswarm run --dry-run` command
+  preview — which builds its argv through the same builder that spawns, so
+  preview and dispatch cannot drift.
+
+- `bullswarm setup` asks one reasoning level per effort tier (suggesting
+  high=xhigh, medium=high, low=medium, with `default` always offered to leave
+  a worker CLI's own setting untouched) and stores the answers under
+  `state.strategy.reasoning`. Agents configure the same thing without a
+  terminal: `bullswarm strategy set-reasoning --tier <high|medium|low> --level
+  <low|medium|high|xhigh|max|default> [--pool <name>] --yes`, `bullswarm
+  strategy reset-reasoning [--tier ..] [--pool ..] --yes`, and a `reasoning`
+  section in `strategy configure --file <json> --yes` whose invalidity rejects
+  the whole document. `bullswarm strategy inventory --json` reports the
+  configured levels and, through the resolver dispatch itself uses, the
+  effective level and its source for every pool and tier. Installed home
+  connectors receive the packaged `reasoning` block additively on upgrade, and
+  a block the user has customized is never overwritten.
+
+- A V2 program action accepts an optional `reasoning` field
+  (`low|medium|high|xhigh|max|default`) that the calling agent or the
+  Workflow Planner can set and that outranks every configured level for that
+  one action; `workflow plan contract` documents the field and echoes the
+  run-wide levels a launch would apply. `workflow goal` takes
+  `--worker-reasoning <level>` for every non-planner dispatch and
+  `--planner-reasoning <level>` for a dispatched Workflow Planner, and
+  `bullswarm run` takes `--reasoning <level>`; a level off the scale is a
+  usage error that launches nothing. The applied level appears next to the
+  model in `workflow runs show` (text and `--json`), `workflow runs result
+  --json`, the TUI attempt rows and agent pane, so a run that thought more
+  cheaply than asked is visible rather than inferred.
+
+## 0.25.3 — usage-limit recovery and headroom-aware routing
+
+- A provider that reports a usage limit is now its own mechanical failure kind,
+  `quota` — never `process`, `semantic`, or `auth`. The attempt is killed at
+  once instead of waiting out a CLI that printed its limit and then hung, and
+  the pool is quarantined until the reset the message named, falling back to
+  that pool's cached 5-hour `resets_at` and then to 30 minutes rather than the
+  flat 10. The quarantine record carries `kind: 'quota'` and excludes the pool
+  from every later dispatch, in that run and in others, until it expires; the
+  action moves to another pool with quota and is never retried on the one that
+  hit the limit. `bullswarm run`, the V1 runtime, and V2 dispatch all apply the
+  same deadline. Detection is shape-gated: an agent report that discusses usage
+  limits, or tool output quoting them, is not a limit, and phrases that other
+  services also emit (`rate limited`, `too many requests`, `quota exceeded`)
+  count only as a bare notice, never as narration about someone else's quota
+  ("rate limited by the GitHub API, retrying"). Connectors declare their
+  own phrases under `quotaSignatures`; installed connectors receive new ones on
+  upgrade.
+
+- Routing avoids pools that are close to their 5-hour limit. A pool at or above
+  `FIVE_HOUR_NEAR_LIMIT_PCT` (75) is chosen only when no eligible pool below it
+  exists for the lane, ahead of pace, an approved assignment, and incumbency;
+  pools at or above 90 stay excluded outright, and a pool with no 5-hour
+  reading counts as having headroom. Routing reasons and candidate lists name
+  the utilization that decided the pick, and `bullswarm pools` shows it as
+  `5h=<n>%` with a `NEAR-5H-LIMIT` label. Meters and quarantines are re-read
+  from the meter cache and core state before every action dispatch and before
+  every retry inside one — forced live right after a usage limit — so a long
+  run no longer dispatches from the pool snapshot frozen at launch.
+
+- `workflow watch` reports a usage-limit retry as a notable event in both
+  modes' vocabulary: `⚠ <action> usage limit on <pool> · paused until
+  <deadline> · retrying on another pool`, then `↺ <action> now on <pool> ·
+  <model>` once the retry lands. Both print without `--verbose`, wake `--next`,
+  and appear in `--jsonl` as `attempt.quota` and `attempt.moved`. The new
+  `--classic` flag forces the older heartbeat-based watcher (transition-on-change
+  snapshots plus a periodic heartbeat, 60 seconds unless `--heartbeat <seconds>`
+  is given) for a V2 run; it is a no-op for legacy runs and cannot combine with
+  `--next`.
+
 ## 0.25.2 — event-based watch
 
 - `workflow watch <run> --next` is safe to relaunch after every wake-up: each

package/README.md

@@ -37,12 +37,17 @@ detaches safely.
    passing verification.
 2. **Pace by meter.** The scheduling resource is the subscription window:
    elapsed% minus used%, most-behind pool wins. Pace may only promote a
-   *cheaper* pool. Lanes are work-nature, never hard-coded to pools.
+   *cheaper* pool. Lanes are work-nature, never hard-coded to pools. The
+   5-hour window never paces — it gates: a pool at or above 75% of it is
+   chosen only when no eligible pool below that line exists, and one at or
+   above 90% is not dispatched at all.
 3. **Delegate output is evidence, never authority.** The Workflow Planner may
    propose actions, but only the deterministic kernel validates the program,
    accepts requirement-scoped evidence, and computes completion.
 4. **Quarantine re-probes.** A benched pool must be able to return to service
-   automatically; a lane is never allowed to silently go down.
+   automatically; a lane is never allowed to silently go down. A pool benched
+   for a usage limit waits for the reset the provider named, not a flat
+   guess — and never longer.
 
 ## Install
 
@@ -94,7 +99,7 @@ bullswarm health   # re-judge saved outputs; catch gate failures
 | `delegate` | Explain and execute the smallest reliable shape: one content-verified agent, or the planning contract for an autonomous workflow you author (`--orchestrator` dispatches a planner agent instead). |
 | `run` | route → dispatch → watch → verify → one JSON verdict |
 | `health` | Re-judge saved outputs against their verdicts; surface verify-gate failures and quarantine clusters |
-| `pools` | Show each pool's meter state, pace position, quarantine status |
+| `pools` | Show each pool's meter state, pace position, 5-hour utilization (`5h=<n>%`, flagged `NEAR-5H-LIMIT` at or above 75%), quarantine status |
 | `strategy` | Interactive provider/model control center with live high/medium/low route previews and an agent-facing JSON API |
 | `doctor` | Machine-readable readiness report; self-heals on first call |
 | `workflow` | Start an autonomous goal, or run / validate / draft / inspect explicit workflows and their live instances. |
@@ -144,6 +149,9 @@ bullswarm strategy set-model opencode2 kaihk/gpt-5.6-luna \
   --tiers high,medium,low --yes
 bullswarm strategy configure --file strategy.json --yes  # atomic agent-authored policy
 bullswarm strategy reset-tier low --yes     # restore one tier to automatic
+bullswarm strategy set-reasoning --tier high --level xhigh --yes
+bullswarm strategy set-reasoning --tier high --level high --pool codex --yes
+bullswarm strategy reset-reasoning --tier high --yes  # back to connector defaults
 bullswarm strategy refresh
 bullswarm strategy show --json
 bullswarm strategy apply --yes --refresh-hours 24
@@ -209,8 +217,15 @@ best eligible models on its configured interval. Disable it with
 `strategy auto off --yes`. Discovery commands, model argument syntax, pricing,
 and benchmark declarations remain connector-owned. Unknown license value,
 prices, and benchmarks stay `null` rather than being guessed. An assignment is
-only a preference: quarantine, exhaustion, burst gates, and capability checks
-still win.
+only a preference: quarantine, exhaustion, burst gates, 5-hour headroom, and
+capability checks still win. Routing prefers pools below
+`FIVE_HOUR_NEAR_LIMIT_PCT` (75) of their 5-hour window over pools at or above
+it, ahead of pace, an approved assignment, and incumbency; a near-limit pool is
+still picked when it is the only eligible one, and a pool with no 5-hour
+reading counts as having headroom. The routing reason and every candidate row
+name the utilization that decided the pick, and meters and quarantines are
+re-read before each dispatch — and again, live, right after a usage limit —
+so a long run never routes off the snapshot it launched with.
 
 Model exclusions are hard routing policy. An excluded model is removed from
 recommendations and assignments, and Bullswarm pins a same-tier allowed model
@@ -290,6 +305,16 @@ adversarial acceptance judgment. Merely being an analysis/evidence action or
 part of a difficult goal never promotes an action to high. The selected effort
 then resolves through the High/Medium/Low routes configured by `bullswarm setup`.
 
+Reasoning depth is a third, independent decision. An action may carry an
+optional `reasoning` field — `low`, `medium`, `high`, `xhigh`, `max`, or
+`default` — that sets how hard the picked model thinks on that one action and
+outranks every configured level for it. `default` passes nothing and lets the
+worker CLI's own setting decide. Omitting the field keeps the configured level.
+It never changes the pool, model, or effort tier, so a `low`-effort mechanical
+step can still be given `xhigh` thinking and a `high`-effort action can be told
+to think cheaply. A connector that does not accept the requested level gets the
+nearest level it supports.
+
 The planner does not author phases or declare success/failure. The kernel
 derives stable presentation stages for the TUI and computes the final V2
 result. Saved V2 runs retain their original execution and workspace policy on
@@ -340,6 +365,30 @@ The worker lock covers scout, work actions, and evidence actions. A pool that ca
 the requested model is ineligible rather than silently substituting another
 model.
 
+Reasoning depth can be pinned for a whole run the same way, without touching
+global strategy:
+
+```bash
+bullswarm workflow goal "Implement and verify the change" --cwd . \
+  --program plan.json --worker-reasoning high --json
+bullswarm run --lane build --reasoning xhigh --prompt '<task>' --json
+```
+
+`--worker-reasoning` covers scout, work actions, and evidence actions;
+`--planner-reasoning` covers a dispatched Workflow Planner and applies only
+with `--orchestrator`. Exactly one level is resolved per attempt, and the
+first layer that sets one wins — not the strongest: the action's own
+`reasoning` field, then the run-wide flag (`--worker-reasoning`,
+`--planner-reasoning`, `bullswarm run --reasoning`), then the configured
+`strategy.reasoning` level for that pool and tier, then the same for the tier
+globally, then the connector's own default for the effort tier, and otherwise
+nothing is appended. So an action asking for `low` beats a run-wide `max`.
+`default` at any layer stops there and passes nothing, letting the worker
+CLI's own setting decide; a connector with no `reasoning` block, or a model it
+marks as skipped, never receives a flag. The applied level is recorded on
+every attempt with the layer that set it and displayed next to the model, so a
+run that thought more cheaply than requested is visible rather than inferred.
+
 The `opencode2` connector itself does not require a KaiHK provider: its base
 spawn command carries no hardcoded model, so a plain OpenCode installation
 dispatches with OpenCode's own configured default. When
@@ -490,9 +539,18 @@ prints one attach line, then one line per notable event as it happens
 planner turn, stall/recovery, cancellation, and the existing pause and
 terminal `outcome:` / `next:` lines) and stays silent while work is merely
 in progress. Agent starts, mechanical retries, and steering delivery print
-only with `--verbose`. The periodic heartbeat is off unless you pass
-`--heartbeat <seconds>`; `--stall-after <seconds>` (default 300) reports a
-running agent that has gone silent. `--next` prints no attach line and
+only with `--verbose`. A usage-limit failure (`failureKind: 'quota'`) always
+prints, verbose or not: `⚠ <actionId> usage limit on <pool> · paused until
+<deadline> · retrying on another pool`, followed once the mechanical retry
+lands on another pool by `↺ <actionId> now on <pool> · <model>`. The
+periodic heartbeat is off unless you pass `--heartbeat <seconds>`;
+`--stall-after <seconds>` (default 300) reports a running agent that has
+gone silent. Pass `--classic` to force the older heartbeat-based watcher
+instead (the transition-on-change snapshot stream plus a periodic
+heartbeat, every 60 seconds unless `--heartbeat <seconds>` is given) —
+legacy (non-V2) runs already behave this way and `--classic` is a no-op for
+them; `--classic` cannot combine with `--next`, which exists only for event
+mode. `--next` prints no attach line and
 exits after the first notable event so a background terminal can wake the
 caller; relaunch until the outcome line reports a pause or a terminal
 status (exit 0 while the run continues or delivered, 1 when it ended
@@ -507,12 +565,14 @@ reported does not produce a duplicate stall line (its recovery still
 prints). `--jsonl` emits one JSON object per notable event with a stable
 `type` (`attach`, `action.finished`,
 `evidence.recorded`, `stage.completed`, `planner.finished`, `agent.stalled`,
-`agent.recovered`, `cancellation.requested`, `paused`, `finished`,
+`agent.recovered`, `cancellation.requested`, `attempt.quota`,
+`attempt.moved`, `paused`, `finished`,
 `interrupted`, and with `--verbose` `action.started`, `attempt.retrying`,
 `steering.delivered`); in that mode the relaunch line is not printed and
 every object instead carries the `sequence` it was emitted at, which is the
 value to pass as `--after`. `--once` still prints one current snapshot. Legacy
-(non-V2) runs keep the compact transition-plus-heartbeat stream unchanged.
+(non-V2) runs keep the compact transition-plus-heartbeat stream unchanged,
+the same stream `--classic` opts a V2 run into.
 
 ```bash
 bullswarm workflow watch <shortId>
@@ -523,6 +583,7 @@ bullswarm workflow watch <shortId> --jsonl       # one JSON object per event
 bullswarm workflow watch <shortId> --once        # one current/terminal snapshot
 bullswarm workflow watch <shortId> --verbose     # started / retry / steering too
 bullswarm workflow watch <shortId> --stall-after 120 --heartbeat 30
+bullswarm workflow watch <shortId> --classic     # older heartbeat-based watcher instead of event mode
 ```
 
 `workflow tui` is the interactive, Claude-style `/workflows` view. For an
@@ -611,6 +672,20 @@ channel, so reading source text such as an auth-signature matcher cannot falsely
 quarantine Grok or Command Code. Error-shaped semantic results and stderr
 diagnostics still trigger the auth/quota guard.
 
+A provider that reports a usage limit — `You've hit your session limit ·
+resets 8:20pm (Asia/Hong_Kong)`, `usage_credits_required`, `rate limit
+exceeded`, `quota exceeded` — is its own mechanical failure kind, `quota`,
+never `process`, `semantic`, or `auth`. The attempt is killed immediately
+even if the CLI would otherwise hang, and the pool is quarantined until the
+reset time parsed from the message, falling back to that pool's cached 5-hour
+`resets_at` and then to 30 minutes. The quarantine record carries
+`kind: 'quota'` and excludes the pool from every later dispatch, in this run
+and in others, until it expires; the action is immediately re-dispatched on
+another pool with quota and never retried on the one that hit the limit. An
+agent report that merely discusses usage limits, or tool output that quotes
+them, is not a limit: detection is shape-gated to lines that look like a
+provider notice.
+
 After ten minutes without transport, parsed-event, or semantic-action evidence,
 an active child is labeled `suspected_stalled`. This is an inspection signal,
 not a death verdict and never an automatic kill: buffered CLIs can be silent
@@ -618,8 +693,9 @@ while working. Process exit, a fatal auth/quota signature, explicit operator
 cancellation, or an opt-in timeout remain the terminal signals.
 
 Each attempt records the phase/action, selected pool and model, effort tier,
-routing reason, all eligible candidates with quota surplus, timestamps,
-artifact paths, outcome, and reported-or-estimated token/cost/quota usage.
+the applied reasoning level with the layer that set it, routing reason, all
+eligible candidates with quota surplus, timestamps, artifact paths, outcome,
+and reported-or-estimated token/cost/quota usage.
 `workflow tui <id>` renders this breakdown for completed runs as well as live
 ones; `workflow tui --json <id>` exposes the durable audit document.
 When a provider event stream reports the actual model, Bullswarm records that

package/connectors/_schema.json

@@ -10,6 +10,8 @@
     "$comment-cwd": "cwdMode documents how the CLI resolves its project: 'pwd' means the CLI resolves from $PWD so the watcher MUST set PWD and spawn inside --add-dir"
   },
   "authSignatures": ["strings in output that mean auth/throttle failure"],
+  "quotaSignatures": ["strings in output that mean this credential is out of quota RIGHT NOW (usage/rate limit hit)"],
+  "$comment-quotaSignatures": "Optional. Merged on top of DEFAULT_QUOTA_SIGNATURES (src/lib/quota.js), matched case-insensitively, and only honored when the matched line is quota-shaped (<=300 chars and the phrase starts in the first 40 chars or the line is error-shaped) so agent prose and tool output that merely discuss limits are never killed. A hit is classified as the mechanical failure kind `quota` (checked before authSignatures), kills the attempt, and quarantines the pool until the reset time parsed from the message, else the pool's cached five_hour.resets_at, else 30 minutes.",
   "outputExtraction": {
     "$comment": "how to get the real answer out of stdout+stderr+files",
     "strategy": "stdout|stdout-tail|json-field|file|event-stream",
@@ -72,6 +74,19 @@
     "free": false
   }],
   "modelSelection": {"flag": "--model", "mode": "replace-or-append"},
+  "reasoning": {
+    "$comment": "Optional. How THIS CLI expresses a thinking level. Omit the block entirely when the CLI has no such control: core then appends nothing and reports source 'unsupported'. Declare exactly one of flag/args.",
+    "flag": "--effort",
+    "args": ["-c", "model_reasoning_effort={level}"],
+    "$comment-form": "flag: appended as `<flag> <level>` with replace-or-append semantics, so a level already pinned in spawn.cmd is replaced rather than duplicated. args: appended verbatim with {level} substituted, for CLIs whose control is a config override rather than a flag.",
+    "levels": ["low", "medium", "high", "xhigh", "max"],
+    "$comment-levels": "the subset of the common scale (low, medium, high, xhigh, max — weakest to strongest, src/lib/reasoning.js) that this CLI accepts, weakest first. A requested level outside the subset is clamped to the strongest supported level not above it, or to the weakest supported level when the request is below all of them, and the clamp is recorded.",
+    "defaults": {"high": "xhigh", "medium": "high", "low": "medium"},
+    "$comment-defaults": "the level to use for each effort tier when nothing else asked. Last layer of the precedence chain: action override > run override > strategy per-pool > strategy per-tier > THESE > nothing appended. The literal 'default' at any layer means 'append nothing, let the CLI's own configuration decide'.",
+    "skipModels": ["^model-id-regex-that-rejects-the-flag"],
+    "$comment-skipModels": "Optional connector-owned regexes. A selected model matching one gets no level appended (source 'skipped-model'), for CLIs whose flag is only valid on some models."
+  },
+  "$comment-reasoning": "Optional prose companion. Say which command's output the block was read from, and mark anything the CLI does not actually print as UNVERIFIED — never invent an accepted value.",
   "subscription": {"plan": null, "monthlyPriceUsd": null, "includedValueUsd": null, "quotaWindow": "weekly"},
   "flags": {
     "stealth": false,

package/connectors/claude-code.json

@@ -23,6 +23,12 @@
     "not logged in",
     "please run /login"
   ],
+  "$comment-quotaSignatures": "usage-limit phrases: classified `quota`, quarantined until the reset the message names. DEFAULT_QUOTA_SIGNATURES (src/lib/quota.js) apply on top of these.",
+  "quotaSignatures": [
+    "hit your session limit",
+    "hit your limit",
+    "hit your usage limit"
+  ],
   "outputExtraction": {
     "strategy": "event-stream"
   },
@@ -54,6 +60,13 @@
   "capabilities": ["strong-analysis", "code-reading", "file-editing", "workflow-planning"],
   "knownModels": ["claude-fable-5", "claude-opus-5", "claude-sonnet-5", "claude-haiku-4-5"],
   "modelSelection": { "flag": "--model", "mode": "replace-or-append" },
+  "$comment-reasoning": "verified from `claude --help` (Claude Code 2.1.263): `--effort <level>  Effort level for the current session (low, medium, high, xhigh, max)`. skipModels: `--help` does not state per-model support, so Haiku is excluded conservatively — re-verify before removing the exclusion. With no `reasoning` override anywhere, workers inherit whatever effortLevel the home settings.json sets.",
+  "reasoning": {
+    "flag": "--effort",
+    "levels": ["low", "medium", "high", "xhigh", "max"],
+    "defaults": { "high": "xhigh", "medium": "high", "low": "medium" },
+    "skipModels": ["^claude-haiku-"]
+  },
   "conversation": {
     "newArgs": ["--session-id", "{sessionId}"],
     "resumeArgs": ["--resume", "{sessionId}"]

package/connectors/codex.json

@@ -21,19 +21,71 @@
     "unauthorized",
     "invalid api key"
   ],
+  "$comment-quotaSignatures": "usage_credits_required is a spent window, not a broken credential: it classifies `quota` (checked before authSignatures) so the pool is quarantined until its reset instead of re-probed in 10 minutes.",
+  "quotaSignatures": [
+    "usage_credits_required",
+    "usage limit"
+  ],
   "outputExtraction": {
     "strategy": "event-stream"
   },
   "eventStream": {
     "format": "jsonl",
-    "args": ["--json"],
+    "args": [
+      "--json"
+    ],
     "silenceThresholdSec": 600,
     "rules": [
-      { "rootMatch": { "path": "type", "equals": "item.started" }, "idPaths": ["item.id"], "kindPaths": ["item.type"], "kindMap": { "agent_message": "response" }, "summaryPaths": ["item.command", "item.text"], "status": "running" },
-      { "rootMatch": { "path": "type", "equals": "item.completed" }, "idPaths": ["item.id"], "kindPaths": ["item.type"], "kindMap": { "agent_message": "response" }, "summaryPaths": ["item.command", "item.text"], "status": "completed" }
+      {
+        "rootMatch": {
+          "path": "type",
+          "equals": "item.started"
+        },
+        "idPaths": [
+          "item.id"
+        ],
+        "kindPaths": [
+          "item.type"
+        ],
+        "kindMap": {
+          "agent_message": "response"
+        },
+        "summaryPaths": [
+          "item.command",
+          "item.text"
+        ],
+        "status": "running"
+      },
+      {
+        "rootMatch": {
+          "path": "type",
+          "equals": "item.completed"
+        },
+        "idPaths": [
+          "item.id"
+        ],
+        "kindPaths": [
+          "item.type"
+        ],
+        "kindMap": {
+          "agent_message": "response"
+        },
+        "summaryPaths": [
+          "item.command",
+          "item.text"
+        ],
+        "status": "completed"
+      }
     ],
     "output": [
-      { "match": { "path": "type", "equals": "item.completed" }, "path": "item.text", "mode": "last" }
+      {
+        "match": {
+          "path": "type",
+          "equals": "item.completed"
+        },
+        "path": "item.text",
+        "mode": "last"
+      }
     ]
   },
   "meter": {
@@ -46,18 +98,109 @@
     "build",
     "chore"
   ],
-  "capabilities": ["strong-analysis", "code-reading", "file-editing", "workflow-planning"],
-  "knownModels": ["gpt-5.6-sol", "gpt-5.6-terra", "gpt-5.6-luna", "gpt-5.5", "gpt-5.4", "gpt-5.4-mini", "gpt-5.3-codex"],
-  "modelSelection": { "flag": "--model", "mode": "replace-or-append" },
+  "capabilities": [
+    "strong-analysis",
+    "code-reading",
+    "file-editing",
+    "workflow-planning"
+  ],
+  "knownModels": [
+    "gpt-5.6-sol",
+    "gpt-5.6-terra",
+    "gpt-5.6-luna",
+    "gpt-5.5",
+    "gpt-5.4",
+    "gpt-5.4-mini",
+    "gpt-5.3-codex"
+  ],
+  "modelSelection": {
+    "flag": "--model",
+    "mode": "replace-or-append"
+  },
+  "$comment-reasoning": "Codex has no reasoning flag; the control is the config key `model_reasoning_effort`, overridden per invocation with the escape hatch verified from `codex exec --help` (codex-cli 0.153.4): `-c, --config <key=value>  Override a configuration value that would otherwise be loaded from ~/.codex/config.toml`. Accepted values verified from the official Codex config reference (https://learn.chatgpt.com/docs/config-file/config-reference, read 2026-09-09): `minimal | low | medium | high | xhigh` — \"Adjust reasoning effort for supported models (Responses API only; xhigh is model-dependent)\". `minimal` sits below bullswarm's common scale, so a request below `low` clamps up to `low`. Tier defaults stay at high/medium/low because `xhigh` is model-dependent; an explicit `xhigh` request passes through. Without this block Codex workers think at whatever config.toml sets (this machine: low).",
+  "reasoning": {
+    "args": [
+      "-c",
+      "model_reasoning_effort={level}"
+    ],
+    "levels": [
+      "low",
+      "medium",
+      "high",
+      "xhigh"
+    ],
+    "defaults": {
+      "high": "high",
+      "medium": "medium",
+      "low": "low"
+    }
+  },
   "modelProfiles": [
-    { "match": "^gpt-5\\.6-sol$", "tier": "high", "qualityRank": 6, "pricing": { "inputUsdPerMillion": 4, "cacheReadUsdPerMillion": 0.4, "outputUsdPerMillion": 20 }, "pricingSource": "https://help.openai.com/en/articles/20001415-chatgpt-rate-card-enterprise-token-based-pricing", "pricingUpdatedAt": "2026-08-27" },
-    { "match": "^gpt-5\\.(5|4)$", "tier": "high", "qualityRank": 5 },
-    { "match": "^gpt-5\\.6-terra$", "tier": "medium", "qualityRank": 4, "pricing": { "inputUsdPerMillion": 2, "cacheReadUsdPerMillion": 0.2, "outputUsdPerMillion": 12 }, "pricingSource": "https://developers.openai.com/api/docs/models/gpt-5.6-terra", "pricingUpdatedAt": "2026-08-27" },
-    { "match": "^gpt-5\\.3-codex$", "tier": "medium", "qualityRank": 4, "pricing": { "inputUsdPerMillion": 1.75, "cacheReadUsdPerMillion": 0.175, "outputUsdPerMillion": 14 }, "pricingSource": "https://help.openai.com/en/articles/20001415-chatgpt-rate-card-enterprise-token-based-pricing", "pricingUpdatedAt": "2026-08-27" },
-    { "match": "^gpt-5\\.6-luna$", "tier": "low", "qualityRank": 3, "pricing": { "inputUsdPerMillion": 0.2, "cacheReadUsdPerMillion": 0.02, "outputUsdPerMillion": 1.2 }, "pricingSource": "https://developers.openai.com/api/docs/models", "pricingUpdatedAt": "2026-08-27" },
-    { "match": "mini", "tier": "low", "qualityRank": 2 }
+    {
+      "match": "^gpt-5\\.6-sol$",
+      "tier": "high",
+      "qualityRank": 6,
+      "pricing": {
+        "inputUsdPerMillion": 4,
+        "cacheReadUsdPerMillion": 0.4,
+        "outputUsdPerMillion": 20
+      },
+      "pricingSource": "https://help.openai.com/en/articles/20001415-chatgpt-rate-card-enterprise-token-based-pricing",
+      "pricingUpdatedAt": "2026-08-27"
+    },
+    {
+      "match": "^gpt-5\\.(5|4)$",
+      "tier": "high",
+      "qualityRank": 5
+    },
+    {
+      "match": "^gpt-5\\.6-terra$",
+      "tier": "medium",
+      "qualityRank": 4,
+      "pricing": {
+        "inputUsdPerMillion": 2,
+        "cacheReadUsdPerMillion": 0.2,
+        "outputUsdPerMillion": 12
+      },
+      "pricingSource": "https://developers.openai.com/api/docs/models/gpt-5.6-terra",
+      "pricingUpdatedAt": "2026-08-27"
+    },
+    {
+      "match": "^gpt-5\\.3-codex$",
+      "tier": "medium",
+      "qualityRank": 4,
+      "pricing": {
+        "inputUsdPerMillion": 1.75,
+        "cacheReadUsdPerMillion": 0.175,
+        "outputUsdPerMillion": 14
+      },
+      "pricingSource": "https://help.openai.com/en/articles/20001415-chatgpt-rate-card-enterprise-token-based-pricing",
+      "pricingUpdatedAt": "2026-08-27"
+    },
+    {
+      "match": "^gpt-5\\.6-luna$",
+      "tier": "low",
+      "qualityRank": 3,
+      "pricing": {
+        "inputUsdPerMillion": 0.2,
+        "cacheReadUsdPerMillion": 0.02,
+        "outputUsdPerMillion": 1.2
+      },
+      "pricingSource": "https://developers.openai.com/api/docs/models",
+      "pricingUpdatedAt": "2026-08-27"
+    },
+    {
+      "match": "mini",
+      "tier": "low",
+      "qualityRank": 2
+    }
   ],
-  "subscription": { "plan": null, "monthlyPriceUsd": null, "includedValueUsd": null, "quotaWindow": "weekly" },
+  "subscription": {
+    "plan": null,
+    "monthlyPriceUsd": null,
+    "includedValueUsd": null,
+    "quotaWindow": "weekly"
+  },
   "flags": {
     "stealth": false
   },

package/connectors/command-code.json

@@ -21,6 +21,8 @@
     "not authenticated",
     "cmd login"
   ],
+  "$comment-quotaSignatures": "empty on purpose: no cmd-specific usage-limit wording has been observed yet; DEFAULT_QUOTA_SIGNATURES in src/lib/quota.js covers the generic provider phrasings.",
+  "quotaSignatures": [],
   "outputExtraction": {
     "strategy": "event-stream"
   },
@@ -53,6 +55,12 @@
   "capabilities": ["code-reading", "file-editing", "strong-analysis", "workflow-planning"],
   "modelDiscovery": { "cmd": ["command-code", "--list-models"], "parse": "columns", "ignorePattern": "^(Available|Open Source$|Anthropic$|OpenAI$|Google$|Sakana$|Meta$|xAI$|Pass|cmd|Docs)", "timeoutMs": 20000, "maxModels": 150 },
   "modelSelection": { "flag": "--model", "mode": "replace-or-append" },
+  "$comment-reasoning": "verified from `command-code --help` (1.44.0): `--effort <level>  Set reasoning effort for the session (e.g. low, medium, high) — depends on the model`. UNVERIFIED: the CLI says \"e.g.\" and \"depends on the model\", so the accepted set is neither closed nor uniform across this pool's many providers; low/medium/high is declared conservatively and a stronger request clamps down to high.",
+  "reasoning": {
+    "flag": "--effort",
+    "levels": ["low", "medium", "high"],
+    "defaults": { "high": "high", "medium": "medium", "low": "low" }
+  },
   "modelProfiles": [
     { "match": "^meta/muse-spark-1\\.3-contributor$", "tier": "high", "qualityRank": 5, "pricing": { "inputUsdPerMillion": 0.1, "cacheReadUsdPerMillion": 0.002, "outputUsdPerMillion": 0.2 }, "pricingSource": "https://commandcode.ai/docs/resources/pricing-limits", "pricingUpdatedAt": "2026-09-03" },
     { "match": "^meta/muse-spark-", "tier": "high", "qualityRank": 5, "pricing": { "inputUsdPerMillion": 1.25, "cacheReadUsdPerMillion": 0.15, "outputUsdPerMillion": 4.25 }, "pricingSource": "https://commandcode.ai/docs/resources/pricing-limits", "pricingUpdatedAt": "2026-09-03" },

package/connectors/echo-worker.mjs

@@ -1,6 +1,7 @@
 // echo-worker.mjs — deterministic test delegate for bullswarm.
 // Reads a task file; behavior is driven by directives in the task text.
 //   FAIL:auth   -> prints an auth failure, exits 0 (the lying-exit trap)
+//   FAIL:quota  -> prints a provider usage limit naming its reset, exits 0
 //   FAIL:exit   -> prints a complete answer, exits 1 (exit-1-after-success)
 //   INTENT:     -> prints only an announcement, exits 0
 //   otherwise   -> echoes the task as a completed answer, exit 0
@@ -11,6 +12,11 @@ const task = readFileSync(process.argv[2], 'utf8');
 const sleepMatch = task.match(/SLEEP_MS:(\d+)/);
 if (sleepMatch) await new Promise((resolve) => setTimeout(resolve, Number(sleepMatch[1])));
 
+if (task.includes('FAIL:quota')) {
+  // A usage limit is not a broken credential: it names when it resets.
+  console.log('Error: usage limit reached · resets in 45 minutes');
+  process.exit(0);
+}
 if (task.includes('FAIL:auth-hang')) {
   console.log('Authentication failed: quota exhausted; waiting process should be terminated.');
   await new Promise((resolve) => setTimeout(resolve, 5000));

package/connectors/echo.json

@@ -7,6 +7,7 @@
     "cwdMode": "task-file-dir"
   },
   "authSignatures": ["Authentication failed", "unauthorized"],
+  "quotaSignatures": [],
   "outputExtraction": { "strategy": "stdout" },
   "meter": { "type": "none" },
   "costRank": 5,