Skip to content

squad cast is not atomic: a failed AgentProvenanceError cast leaves an orphan member in team.md, routing.md and .squad/agents/ #2525

Open

Description

@bradygaster

Version: CLI built from release/prepare-2.0.0-preview.5 @ 38d45d02 (package version 2.0.0-preview.6), macOS, Node.

What happens

squad cast --name <name> --role <role> writes the member's charter, history, team.md row and routing.md row before it updates the casting registry. When the registry update throws AgentProvenanceError, nothing is rolled back. The command exits 1 with a raw stack trace. The project is left with a member that is on the roster and in routing but not in .squad/casting/registry.json.

Retrying doesn't help. Without --force, it stops at "already exists". With --force, it hits the same AgentProvenanceError. The next squad upgrade then projects the orphan into .claude/agents/<id>.md, and squad doctor reports all checks passing.

Repro

D=$(mktemp -d); cd "$D"; git init -q
node <squad-cli>/dist/cli-entry.js init --roles --client copilot,claude
git add -A && git commit -qm init
node <squad-cli>/dist/cli-entry.js cast --name Alpha --role "Test Engineer"   # ok
git add -A && git commit -qm alpha
node <squad-cli>/dist/cli-entry.js cast --name Beta --role "Test Engineer"    # fails (see #2524)
echo $?          # 1
git status --short

Output of the failing cast (stack trace printed verbatim to the user):

AgentProvenanceError: New agent id "beta" ambiguously resembles existing role owner(s) alpha; supply the existing stable id for a rename
    at reconcileAgentProvenanceRegistry (.../squad-sdk/dist/casting/agent-provenance.js:963:23)
    at updateCastingStateWithAgent (.../squad-cli/dist/cli/commands/cast.js:273:26)
    at async runCastAdd (.../squad-cli/dist/cli/commands/cast.js:341:5)
    ...

git status after the failure:

 M .squad/routing.md        # + | Test Engineer | Beta | — |
 M .squad/team.md           # + | Beta | Test Engineer | `.squad/agents/beta/charter.md` | ✅ Active |
?? .squad/agents/beta/      # charter.md, history.md

.squad/casting/registry.json has no beta entry, and .squad/config.json is not updated either, because addAgentToConfig runs after the throw.

Then:

node <squad-cli>/dist/cli-entry.js cast --name Beta --role "Test Engineer"          # ✗ Agent "Beta" already exists ... (use --force)
node <squad-cli>/dist/cli-entry.js cast --name Beta --role "Test Engineer" --force  # same AgentProvenanceError
node <squad-cli>/dist/cli-entry.js upgrade     # ✓ created .claude/agents/beta.md
node <squad-cli>/dist/cli-entry.js doctor      # Summary: 13 passed, 0 failed, 0 warnings

Expected

  • The cast either completes or changes nothing. Validate against the casting registry first (or stage everything and commit last), so a provenance rejection leaves team.md, routing.md, .squad/agents/ and .claude/agents/ untouched.
  • AgentProvenanceError is shown as a one-line ✗ error with a hint, not an uncaught stack trace.
  • squad doctor flags roster members (team.md rows or .squad/agents/*/charter.md) that are missing from the casting registry.

Source

  • packages/squad-cli/src/cli/commands/cast.ts, runCastAdd (line 362). The order is: charter and history written (line 407), updateTeamMdWithAgent (412), ensureBuiltinRoster, updateRoutingMdWithAgent, and only then updateCastingStateWithAgent (415), which calls reconcileAgentProvenanceRegistry (line 319).
  • packages/squad-sdk/src/casting/agent-provenance.ts, line 1194–1203: the throw site.
  • The CLI caller in packages/squad-cli/src/cli-entry.ts (line ~922) doesn't catch AgentProvenanceError.

Related: #2524 (root cause of this particular rejection: two members can't share a role).

🤖 Generated with Claude Code

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions