v5.1.2 — swarm artifact archive

Documentation only. No runtime, agent, hook, or skill changes from 5.1.1.

If you're upgrading from 5.1.0 or earlier, the release you actually care about is v5.1.1 — it restores agent dispatch, which was completely non-functional. Everything functional in this line shipped there.

Added

Archived the dispatch-restoration swarm artifacts under docs/swarm-reports/2026-08-04-1804-dispatch-restoration/ — validation report, review report, scout report, and PR body.

The scout report is the part worth keeping. It records that both fatal dispatch bugs shipped through a fully green test suite, why no self-consistency check could have caught either — the violated contract was Claude Code's, not PDS's, so PDS was internally coherent and completely non-functional at the same time — and six patterns that generalize:

1. An empty list in an error message is a filter signal, not an absence. Available agents: with nothing after it meant "your filter matched zero things, so I discarded the whole set," not "nothing is installed."
2. Differential probing beats re-reading code. Both root causes were pinned by building minimal variants and comparing outcomes, not by inspection.
3. Never accept a model's account of a tool result over the raw tool result.
4. A changed error message is progress, and often a second bug. Treating it as "still broken" would have shipped one of the two defects.
5. Verify the premise, not just the conclusion. The previous fix rested on an assumption nobody tested; one instrumented hook falsified it immediately.
6. Registering a hook can silently take ownership you didn't intend to accept.

Upgrading

Nothing to do if you're already on 5.1.1. Otherwise:

claude plugin update pds@pds-marketplace

Then restart Claude Code.

v5.1.1 — dispatch restoration

Agent dispatch was completely dead. If you ran /pds:swarm on 5.1.0 or earlier, the orchestrator could not spawn a single agent — not a worker, not a researcher, not even general-purpose. This release fixes that.

Tagged retroactively: 5.1.1 shipped to the marketplace but was never cut as a release.

What was broken

#181 — the orchestrator could not spawn any agent

agents/orchestrator.md declared its spawn allowlist with bare names:

- Task(researcher, worker, validator, reviewer, documenter, scout, auditor)

PDS ships its agents inside a plugin, and plugin-provided agents register as pds:<name>. The allowlist matched zero agents — and Claude Code's response to a zero-match allowlist is to empty the spawn roster entirely:

Agent type 'researcher' not found. Available agents:

Nothing after the colon. general-purpose gone too. That empty list is why this survived two releases: it reads as "the plugin didn't load," not "the allowlist is misnamed."

pds:shepherd was also missing from the allowlist outright, despite being spawned in swarm Phase 1.

#182 — pds:worker still unspawnable

Registering a WorktreeCreate hook replaces Claude Code's native git worktree creation. The hook is not notified that a worktree was made — it is the thing that makes it. PDS's hook only symlinked a settings file, and by existing at all it took creation away from Claude Code and then created nothing.

The v5.0.0 fix for #170 rested on an unverified premise ("Claude Code already switched into the worktree before firing this hook"). It doesn't — CWD is the main repo. One instrumented hook falsified it in a single spawn.

Two more instances of the same root cause

• hooks/scripts/roster-check.sh matched bare names too, so it warned on every legitimate spawn and stayed silent on genuinely unknown ones — exactly inverted. Noise rather than breakage, since it never blocks.
• Five doc files stated a roster of 8 for a 9-agent roster. Not cosmetic: the omitted agent was the shepherd — the same one missing from the allowlist and the hook. A wrong count is how a whole agent goes unnoticed.

Verified

scripts/smoke-dispatch.sh --all against the published plugin: 8/8 agent types spawn — researcher, worker, validator, reviewer, documenter, scout, auditor, shepherd.

Verification parsed raw stream-json tool results throughout. An early probe reported a spawn as successful whose underlying tool result was an error, so model narration was discarded as evidence.

Preventing recurrence

Both fatal bugs shipped through a fully green test suite, twice. Neither was reachable by any self-consistency check — the violated contract belonged to Claude Code, not PDS. PDS was internally coherent and totally non-functional at the same time.

Three layers now, and every static guard was verified by reintroducing its defect. A guard that has never failed is not known to be a guard.

Layer	Runs
scripts/check-agent-roster.py — allowlist namespaced, complete, cross-checked against docs and the roster hook	CI
hooks/tests/test-worktree-hooks.sh (12 cases)	CI
hooks/tests/test-roster-check.sh (20 cases)	CI
scripts/check-workflows.py	CI
scripts/smoke-dispatch.sh — live spawn against a real headless orchestrator	human, pre-ship

The live layer needs an authenticated claude and cannot run in CI. /pds:finish and /pds:contribute now require a human to run it whenever a branch touches agents/, hooks/, or spawn syntax. That human step is the weakest link, and is documented as such.

Upgrading

claude plugin update pds@pds-marketplace

Then restart Claude Code. A stale ~/.claude/plugins/cache/ copy will keep masking the fix.

Note on #171

#171 diagnosed this same symptom one layer too high — concluded named-teammate nesting was the blocker and removed name= from spawn calls. Spawns were failing before ever reaching that check. Its change remains correct on its own terms; it simply never restored dispatch. The generalizable error was reading the platform's error text as an explanation rather than as one more claim to verify.

Full detail: PR #183 · issues #181, #182 · docs/swarm-reports/2026-08-04-1804-dispatch-restoration/