Crew roles are config: an agent says what it does, migrate never picks a planner as builder, and a repo's team is three lists to choose from #8922

An agent's roles are now part of its config, and nearly everything on the issue's list is built. Screenshots are not on the pull, and I did not time the 30-second cold read; the sandbox has no browser. tsc, the gate, design-lint and test/mcp-size.test.ts are clean.

Adopting it on the live forge: the new migration 20261103140000-agent-roles runs on deploy. It sets each agent's roles from the seats it already holds on any repo, so no seat changes. An agent on no crew keeps builder, which is what it read as before.

What changed

• Roles on the agent: an agent declares one or more of planner, builder and reviewer, set where its model and brief are. That is a checkbox group on the agent form (Settings → Crew → the agent), roles on /api/v1/agents, and roles on the agent MCP tool. No new MCP tool.
• Adding to a repo: a repo can narrow what an agent declares but never widen it. With no seat named, an agent gets the first one it declares, not builder. Asking for a seat the agent doesn't declare says so in a plain sentence.
• /migrate and new apps: only builders are offered, with a sensible default. crew= naming a non-builder is refused in a sentence. A test covers a planner that sorts first alphabetically (test/crew-roles.test.ts).
• Dispatch: an agent is never handed a job outside its seat. An issue assigned to a planner gets one comment saying so instead of running. There are tests per seat.
• Repo Settings: the team is three lists, Planners, Builders and Reviewers. Each has a picker of only the agents that declare that role, plus the how-many-at-once number. Each change saves at once (a small script submits on change; without it a button is there). The crew card and the crew MCP tool read the same seats.
• Spawned forges: a spawned child now carries each agent's declared roles. Without that, the child's planner was lost on first boot, and that is why test/first-login.test.ts failed.

Test changes

• test/helpers/seat.ts adds seatAs, which widens an agent's declared roles and then seats it. About 80 existing tests that called setCrewRole on a plain agent now use it.
• test/crew-loop.test.ts now assigns the issue to a builder, because a planner assignment is explained rather than run.
• The agent create and edit forms refuse a post with no role ticked, so test/web-apps.test.ts and test/member-crew.test.ts now post roles=builder.
• test/guests.test.ts puts the helper back on builder before the sweep test.
• addCrew for a user with no agent row now reaches the database, so the "only an agent can be on a crew" guard still fires.

Test results

• Checks I ran: the modified tests, plus about 780 others (names matching crew, agent, migrate, mcp, settings, team, planner, dispatch, seat, role, apps, assign, api, spawn, home, review, issue and run), all green.
• One failure: a sleeping-preview test that needs network access timed out at 120 s. It is outside this change.
• Not run: the rest of the suite. The forge runs the full check on push.

Left out

• Narrowing an agent's roles from the repo Settings page: the picker only adds. The existing remove button takes an agent off the team.
• Seat limits by role are unchanged.

Closes #8907

An agent's roles are now part of its config, and nearly everything on the issue's list is built. Screenshots are not on the pull, and I did not time the 30-second cold read; the sandbox has no browser. tsc, the gate, design-lint and test/mcp-size.test.ts are clean.

Adopting it on the live forge: the new migration 20261103140000-agent-roles runs on deploy. It sets each agent's roles from the seats it already holds on any repo, so no seat changes. An agent on no crew keeps builder, which is what it read as before.

What changed

• Roles on the agent: an agent declares one or more of planner, builder and reviewer, set where its model and brief are. That is a checkbox group on the agent form (Settings → Crew → the agent), roles on /api/v1/agents, and roles on the agent MCP tool. No new MCP tool.
• Adding to a repo: a repo can narrow what an agent declares but never widen it. With no seat named, an agent gets the first one it declares, not builder. Asking for a seat the agent doesn't declare says so in a plain sentence.
• /migrate and new apps: only builders are offered, with a sensible default. crew= naming a non-builder is refused in a sentence. A test covers a planner that sorts first alphabetically (test/crew-roles.test.ts).
• Dispatch: an agent is never handed a job outside its seat. An issue assigned to a planner gets one comment saying so instead of running. There are tests per seat.
• Repo Settings: the team is three lists, Planners, Builders and Reviewers. Each has a picker of only the agents that declare that role, plus the how-many-at-once number. Each change saves at once (a small script submits on change; without it a button is there). The crew card and the crew MCP tool read the same seats.
• Spawned forges: a spawned child now carries each agent's declared roles. Without that, the child's planner was lost on first boot, and that is why test/first-login.test.ts failed.

Test changes

• test/helpers/seat.ts adds seatAs, which widens an agent's declared roles and then seats it. About 80 existing tests that called setCrewRole on a plain agent now use it.
• test/crew-loop.test.ts now assigns the issue to a builder, because a planner assignment is explained rather than run.
• The agent create and edit forms refuse a post with no role ticked, so test/web-apps.test.ts and test/member-crew.test.ts now post roles=builder.
• test/guests.test.ts puts the helper back on builder before the sweep test.
• addCrew for a user with no agent row now reaches the database, so the "only an agent can be on a crew" guard still fires.

Test results

• Checks I ran: the modified tests, plus about 780 others (names matching crew, agent, migrate, mcp, settings, team, planner, dispatch, seat, role, apps, assign, api, spawn, home, review, issue and run), all green.
• One failure: a sleeping-preview test that needs network access timed out at 120 s. It is outside this change.
• Not run: the rest of the suite. The forge runs the full check on push.

Left out

• Narrowing an agent's roles from the repo Settings page: the picker only adds. The existing remove button takes an agent off the team.
• Seat limits by role are unchanged.

The check failed because none of my commits had a Try: line. I've added one in a new empty commit and pushed it. I haven't seen the forge's check re-run, and I didn't re-run the gate locally.

The commit's Try: line reads: open /alice/<repo>/settings#crew on the preview and pick from the Planners, Builders and Reviewers lists; open /migrate and see only builders offered. The code is unchanged since the last push.

I couldn't read the feedback on #8922. The pull's status shows one "changes requested" review, but the reviews endpoint returned an empty list and the comments hold only my own two. So I worked from the uncommitted changes I'd left in the clone, which looked like review fixes, and pushed those. If the reviewer asked for something else, it isn't addressed; please restate it.

tsc, the gate, design-lint and the seven test files I ran (the crew-role, terminal-agents, crew-loop, autonomy, web-apps, member-crew and MCP-size tests, 87 tests) are all green. I did not run the rest of the suite; the forge runs it on push.

What changed in this push

• Held seats: changing an agent's roles through the web form, /api/v1/agents, the MCP agent tool or the terminal is now refused with role_held if it would drop a seat the agent still holds on a repository. The page says to move the agent off that seat first under Settings → Crew. Before, the seat stayed while the role was gone.
• roles in a request: it must be a list of strings. Before, a malformed value was silently ignored. Now it is refused as invalid_roles.
• Dispatch: every reason to run an agent except a review counts as building work. A planner is no longer handed a feedback, red-check, conflict or converge run on a pull. Direction-issue work goes to the planner and everything else to a builder.
• Terminal: the agents screen shows each agent's roles, and r edits them with the usual plan-and-confirm step.
• Team forms: the picker's first option, "Add…", is now a disabled placeholder. The Add and Set buttons use the shared button component. With the script on, they hide.
• Tests: new cases in test/crew-roles.test.ts and test/tui-agents.test.ts. test/crew-loop.test.ts and test/autonomy.test.ts are adjusted.

Left out, as before

• Narrowing an agent's roles from a repo's Settings page.
• Seat limits by role.

Try it: open /alice/<repo>/settings#crew on the preview. Untick a role on an agent that holds that seat and the refusal appears. In the terminal, press r on an agent.

Left #8907 open: 1 unticked item remain (A cold reader sets up a team in 30 seconds. Screenshots on the pull.).