Swarm 0.10.0: out-of-band transport, telemetry, model discovery, one config parser

[gering]

Summary

Swarm reviews reproducibly lost an entire model family — three runs in a row, always grok × breakage at exactly 600 s. This PR removes the adjacent failure mode, measures away several wrong theories, and makes the remaining one legible. It does not raise the 600 s ceiling; that needs an async transport and is split out into tasks/async-poll-external-voices.md.

• The 120 KiB prompt wall is gone. The prompt no longer travels on argv, so exec's MAX_ARG_STRLEN is no longer the binding limit. Above the old cap the skill dropped every external voice — the same damage as a timeout, from a limit that was never inherent to the CLIs.
• What actually drives runtime was measured, and it is not what everyone assumed. Prompt size is ruled out; the lens cluster dominates.
• Timeouts now report themselves. Both timeouts derive from one value, so rc=124 survives; per-call telemetry exposes voices approaching the wall before they cross it; a lost model family is called out where it changes meaning — in the consensus line.
• The grok model is discovered, not pinned — a hard-coded id had already silently dropped grok from every review once.
• The numeric configuration has exactly one parser. Three review rounds found three instances of the same split-brain bug; the third answers the class instead of the instance.

Measurements (these drove the decisions)

Same 42 KB diff, one variable at a time:

Backend	Effort	Cluster	Duration	Findings
grok	high	breakage (3 lenses)	374 s	4
grok	low	breakage	161 s	4
grok	high	consistency	28 s	6
codex	high	breakage	104 s	2

Control: a 164 KiB prompt returned in 20 s (grok) / 8.6 s (codex) — 4× the bytes, 1/20th the time.

• Diff chunking: rejected. It targets the one variable measurement excludes.
• grok --max-turns: rejected. N=10 → 10 s but zero findings; N=20 → 279 s. The truncated run exits rc=0 with empty findings, so the pipeline reads a silenced voice as "reviewed cleanly, found nothing" — worse than a timeout, which at least reaches backendErrors.
• Effort is the largest untried runtime lever (2.3×, same findings) — but that axis belongs to add-swarm-review-profiles.

Changes

Transport (0.8.0) — codex reads the prompt from stdin (-- -), grok via --prompt-file; the adapter passes the file path through instead of reading it into a shell variable. Cap is now model context (SWARM_MAX_PROMPT_BYTES, 512 KiB), read by adapter and skill from the same knob so an override reaches both. Verified end-to-end at 164 KiB on both backends.

Telemetry (0.8.1) — agents.sh run --telemetry <file> --unit <name> records duration, effective effort/model, prompt bytes, backend rc, timed_out and the wall the call ran under, written from the EXIT trap so timeouts are captured. telemetry-report.py flags any surviving call at ≥60 % of its wall — the case backendErrors structurally cannot show.

Lens split (0.9.0) — cross-file-trace moves into its own reach cluster. The measured reason is lens crowd-out: the combined 3-lens call returned 3 of 4 findings from one lens; split, the other two found 4 issues it had missed entirely. Not a speed fix — the longest call drops only 374 → 313 s.

Diagnosis (0.9.1) — both timeouts derive from one value, with the adapter cap pinned below the Bash window so it wins the race and rc=124 survives (the old 600/600 tie is why raising SWARM_TIMEOUT looked counterproductive). The balance block now names a lost model family and states that consensus weakened — or became unreachable.

Model discovery (0.9.2) — the grok model is discovered from grok models instead of pinned: a canonical-id filter, component-wise version ordering (so grok-4.20 sorts above grok-4.6, which string comparison gets backwards), and a hard verification gate — a model must be schema-verified before the adapter will run it, because a CLI that merely accepts --json-schema and returns structuredOutput: null fails only after burning a full review. The remaining pin is a floor, deliberately the oldest verified id. This section exists because grok CLI 1.0.3 changed its listing format to mark only the default with *, and the old *-only matcher concluded the pinned model was not offered — dropping grok from every review, silently. test_grok_models.py now parses the shipped awk program out of agents.sh (never a retyped copy) and pins both listing formats against it.

One parser for the numeric knobs (0.10.0) — new verb agents.sh config prints the resolved, validated configuration (max_prompt_bytes, cap_headroom, oversize_threshold, timeout_seconds, probe_timeout_seconds); the skill's prep block reads those lines instead of re-deriving them. One _resolve_int enforces digits-only, 10# decimal forcing, a range check after conversion, a length guard against 64-bit wrap, and an explicit upper bound. Also: with_timeout escalates to SIGKILL (-k 3) — plain SIGTERM let a backend outlive the cap, so the outer Bash window killed the adapter instead and no telemetry survived; SWARM_PROBE_TIMEOUT is capped at 20 s and the coupling to the workflow's TIMEOUT_MARGIN_S is documented on both sides; grok's --prompt-file probe moved into readiness (a CLI without it now reports not-ready once, instead of every cluster failing identically); a --model override is validated against the offered list; _bounded_probe uses 126, not 127, as its "cannot bound this call" sentinel, since timeout itself exits 127 for a missing command.

Prompt heredoc (0.10.1) — cat <<HDR is unquoted on purpose ($NONCE/$CAP_RULES must expand), which also evaluates backticks in the body. The rule listing the allowed finding prefixes was written with markdown backticks around `[lens]`, so bash ran it as a command: every review since 0.7.0 printed [lens]: command not found and shipped a prompt whose rule had lost the very tag it describes. Found by executing the prep block rather than reading it — the three self-reviews below could not see it for exactly that reason. test_lens_sync.py now rejects any backtick or $( inside an unquoted heredoc there.

Review of 0.10.x (0.10.2) — the first run on this branch's own adapter, all three families live, 190 KiB prompt (the size that would have dropped every external voice before 0.8.0). 21 findings, 13 applied. The critical one closed the loop on 0.10.0: TIMEOUT_MARGIN_S was a hand-derived literal restating the adapter's probe constants in a comment, and 0.10.0's third bounded probe pushed the worst case to 3 × 23 = 69 s against a 60 s margin — the outer window would win the race again and destroy the rc=124 + telemetry evidence. agents.sh config reports probe_budget_seconds now, the skill passes it, the workflow derives its margin from it, and the --help probe is memoized. Also: rc=137 counts as a timeout everywhere (-k SIGKILLs a SIGTERM-ignoring backend — which grok is documented as being — and every consumer keyed on 124 alone); a malformed SWARM_TIMEOUT no longer exits 2 from --help/jail/list; the oversize message quotes the cap that actually fired instead of a hard-coded 512 KiB.

What three self-reviews found

The branch reviewed itself three times (/swarm:review --fix). Round 1 found real defects in the feature code — the skill's oversize guard read SWARM_MAX_PROMPT_BYTES without the adapter's validation, so a malformed value made the threshold negative and dropped every external voice silently; the grok capability probe ran grok --help unbounded outside with_timeout.

Rounds 2 and 3 then found only defects introduced by the previous round's fixes, and always in the same shape: a value two places must agree on, corrected in one of them.

Round	Critical	Shape
1	cap unvalidated in the skill	one side validates, the other does not
2	cap decimal-forced in the skill, not the adapter	one side normalizes, the other does not
3	timeout decimal-forced in the skill, not the adapter	the same bug, one knob over

Patching the reported instance never ended the class, so 0.10.0 removes the second parser rather than fixing it a fourth time. test_lens_sync.py guards the design directly — it requires the single parser and the config dispatch, and negatively asserts that no second parse reappears in the skill.

Readiness

• ✅ Tests — 6 swarm test files pass (3 new on this branch: test_telemetry_report.py, test_grok_models.py, plus transport + coupling guards in the existing suites); check-structure.py clean
• ✅ Changelog — entries for 0.8.0 → 0.10.2, each naming what it declined and why
• ✅ Knowledge — swarm-backend-adapter.md + swarm-review-pipeline.md carry the measurement matrix, the rejected alternatives, the discovery design and the one-parser rationale
• ✅ README / CLAUDE.md / marketplace — cluster count, transport and version (0.10.x) in sync
• ✅ Rebased onto main
• ✅ Reviewed on its own code — the 0.10.x ensemble ran against this branch (35 agents, ~16 min); the 13 agreed findings are applied in 0.10.2, the 8 declined ones are listed in the changelog with reasons

Test plan

• /swarm:review on a normal diff — three full rounds run on this branch; externals participate, Voices: timing section appears under the balance block
• Oversize transport — verified on both paths: 164 KiB end-to-end through the adapter, and the skill-side prep block reporting EXTERNALS_OVERSIZE=0 at 190 KiB against the adapter-reported threshold (the old 118 784-byte constant would have skipped every external voice)
• SWARM_MAX_PROMPT_BYTES=abc → agents.sh config exits 2 with one message, so the skill stops instead of silently reducing the ensemble to Claude-only. Also verified: 0100000 resolves to 100000 (not octal 32768), a cap at/below the 4096-byte headroom is refused, and SWARM_PROBE_TIMEOUT=300 is refused against the 20 s ceiling
• Force a backend timeout — SWARM_TIMEOUT=5 against grok returned grok timed out after 5s in 6.7 s wall (cap + probe overhead), adapter_rc=1, and the telemetry record {"backend_rc":124,"timed_out":true,"timeout_seconds":5,"model":"grok-4.6"} — i.e. the inner cap wins the race, the EXIT trap still fires, and discovery picked the newest verified model. The consensus-line wording downstream of this is workflow-side and unchanged by this branch

🤖 Generated with Claude Code

https://claude.ai/code/session_01JHKreruna9RfZHcEq6YPub