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/