fix(claude-relay-plugin): fix the pipeline deadlock and finish the workspace-key removal

.claude-plugin/marketplace.json

@@ -18,7 +18,7 @@
         "path": "plugins/claude-relay-plugin"
       },
       "description": "Lets your Claude Code sub-agents communicate with each other in real time - send messages, coordinate in shared channels, and work as a team instead of in isolation",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "author": {
         "name": "Agent Relay",
         "email": "hello@agent-relay.com"

plugins/claude-relay-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-relay-plugin",
   "description": "Lets your Claude Code sub-agents communicate with each other in real time - send messages, coordinate in shared channels, and work as a team instead of in isolation.",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "author": {
     "name": "Agent Relay",
     "url": "https://agentrelay.com"

plugins/claude-relay-plugin/agents/relay-worker/agent.md

@@ -6,13 +6,26 @@ You are a relay-connected worker in a coordinated multi-agent team. Your job is
 
 You MUST complete these steps in order before doing any work:
 
-1. **Register with your assigned name.** Call the `register_agent` MCP tool with the agent name from your task prompt and `type: "agent"`. You must register before you can send or receive messages. The workspace is already pinned to this project, so the relay MCP server picks it up for you — you do not need a workspace key. If `register_agent` fails with "Workspace key not configured", report that to your lead instead of asking for the key; the lead fixes the pin.
-2. **Never print or request a workspace key.** It is an administrative credential. If someone needs to watch this run, that is the lead's job via `get_observer_url`.
-3. **Check your inbox.** Call `check_inbox` with your assigned relay name in `as` to find your task assignment and lead information.
-4. **Send an ACK.** Before you do substantive work, send `ACK: <one-sentence understanding of the assignment>` to your lead via `send_dm`, again using your assigned relay name in `as`.
-5. If the task is ambiguous or blocked, send `BLOCKED: <question or blocker>` instead of guessing.
+1. **Register with your assigned name.** Call the `register_agent` MCP tool with the agent name from your task prompt and `type: "agent"`. You must register before you can send or receive messages. The workspace is already pinned to this project, so the relay MCP server picks it up for you — you do not need a workspace key.
+2. **Check your inbox.** Call `check_inbox` with your assigned relay name in `as` to find your task assignment and lead information.
+3. **Send an ACK.** Before you do substantive work, send `ACK: <one-sentence understanding of the assignment>` to your lead via `send_dm`, again using your assigned relay name in `as`.
+4. If the task is ambiguous or blocked, send `BLOCKED: <question or blocker>` instead of guessing.
 
-If any of steps 1-2 fail, retry once. If they fail again, stop and report the error — do not proceed without a relay connection.
+**Never print or request a workspace key.** It is an administrative credential. If someone needs to watch this run, that is the lead's job — via `get_observer_url`, or `agent-relay observer` from a shell.
+
+### When registration fails
+
+Registration is a prerequisite for every other relay call, so a failure there is not
+retryable and not reportable over relay — `send_dm` needs the identity you just failed to
+get. Do not retry, and do not try to reach your lead through the relay.
+
+Instead, stop and make the exact error your **final response**. That text is what your lead
+receives back from the Agent call, and it is the only channel you have left. Never ask for a
+workspace key as a workaround.
+
+The same applies if `check_inbox` returns no assignment: you may have registered into a
+different workspace than your lead, because the project pin is shared by everything running
+in this directory. Report that as your final response rather than guessing at the work.
 
 ## Working Rules
 

plugins/claude-relay-plugin/hooks/subagent-bootstrap.sh

@@ -10,12 +10,19 @@ MANDATORY relay setup — complete these steps IN ORDER before any other work:
 1. Call \`register_agent(name: "$AGENT_NAME", type: "agent")\` to register with the relay.
    The workspace is already pinned to this project, so the relay MCP server resolves it
    for you — you do NOT need a workspace key, and must never print or ask for one.
-   If this fails with "Workspace key not configured", report that to your lead.
 2. Call \`check_inbox(as: "$AGENT_NAME")\` to get your task assignment.
 3. Send an ACK to your lead via \`send_dm(as: "$AGENT_NAME")\` when you understand the task.
 4. When finished, send a DONE message with a concise completion summary via \`send_dm(as: "$AGENT_NAME")\` before stopping.
 
 IMPORTANT: Include \`as: "$AGENT_NAME"\` on EVERY relay tool call to ensure correct message attribution.
 
-Do NOT skip step 1. Without it you cannot send or receive messages.
+IF STEP 1 FAILS (for example "Workspace key not configured"): stop. Do not retry, and do
+not attempt any other relay call — every one of them needs the registration you just failed
+to get, so they will fail too. Relay is unavailable to you, which means you cannot tell your
+lead over relay. Report the exact error as your final response instead; that text is what
+your lead receives back from the Agent call. Do not ask anyone for a workspace key.
+
+IF STEP 2 RETURNS NO ASSIGNMENT: you may have registered into a different workspace than
+your lead (the project pin is shared by everything running in this directory). Do not guess
+at the work. Report that as your final response so the lead can re-spawn you.
 EOF

plugins/claude-relay-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-relay-plugin",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Agent Relay plugin for Claude Code - multi-agent coordination via Agent Relay MCP and hooks",
   "author": "Agent Relay <hello@agent-relay.com>",
   "license": "MIT",

plugins/claude-relay-plugin/skills/relay-fanout/SKILL.md

@@ -16,6 +16,7 @@ Workers are spawned with Claude Code's built-in **Agent tool**. The relay is onl
 - Use `subagent_type: "relay-worker"`. Only `relay-worker` subagents get the Agent Relay MCP server, the inbox-polling hooks, and the worker protocol. Other subagent types (`researcher`, `general-purpose`, …) cannot talk over the relay.
 - Run all workers in **background mode** (`run_in_background: true`) so they work concurrently.
 - Workers inherit the workspace automatically — the relay MCP server resolves the workspace pinned to this project. **Do not put the workspace key in a worker prompt.** It is an administrative credential, and copying it into N prompts puts it in N transcripts. If a worker reports no workspace, fix the pin (step 2) rather than pasting the key.
+- **One relay team per checkout.** The pin is per-project and last-writer-wins, so two leads running teams from the same directory will fight over it and a worker can register into the other lead's workspace. Run concurrent teams from separate checkouts or git worktrees. The ACK gate below is what catches this: a worker that landed in the wrong workspace finds no assignment and cannot ACK.
 - The `SubagentStart` hook injects the relay bootstrap (register, check inbox, ACK, DONE) into every worker.
 - Use the relay MCP tools (`send_dm`, `check_inbox`) to monitor progress.
 - Do not add setup scripts or dependencies. Use the plugin's existing hooks, MCP tools, and `relay-worker` agent definition.
@@ -24,12 +25,12 @@ Workers are spawned with Claude Code's built-in **Agent tool**. The relay is onl
 
 1. Pick a stable coordinator name — `relay-lead`. Pass `as: "relay-lead"` on **every** relay tool call you make, so your messages, inbox reads, and reactions stay attributed to the lead.
 2. **Set up the workspace.** Call `register_agent` with `relay-lead`. If it fails with "Workspace key not configured", call `create_workspace`, then `register_agent` again. Both `create_workspace` and `set_workspace_key` pin the workspace to this project, which is how workers pick it up.
-3. **Give the user a link to follow along.** Call `get_observer_url` and print the URL it returns. It is backed by a read-only token that expires, so it is safe to share. Never build an observer URL from the workspace key, and never print the key.
+3. **Give the user a link to follow along.** Call `get_observer_url` and print the URL it returns — or run `agent-relay observer` if your session does not expose that tool. Either way the link is backed by a read-only token that expires, so it is safe to share. Never build an observer URL from the workspace key, and never print the key.
 4. Confirm the work is genuinely parallelizable. Every worker must be able to finish without waiting on another worker's output. If that is not true, use the pipeline pattern instead.
 5. Pick the worker count from the task shape. Prefer 2–8, and stay low enough that you can still track every ACK and DONE.
 6. Partition the work into independent units — each with its own files, target, or scope boundary, and no shared intermediate state.
 7. Spawn one worker per unit with the Agent tool:
-   ```
+   ```text
    Agent(
      subagent_type: "relay-worker",
      run_in_background: true,
@@ -39,7 +40,9 @@ Workers are spawned with Claude Code's built-in **Agent tool**. The relay is onl
               Your unit: [specific target/scope].
               Files: [list of files/directories].
               Deliver: [concrete output].
-              Do NOT release yourself when done — report DONE and stay idle for review."
+              When done, DM your lead a DONE message with the evidence for your scope.
+              Do not call remove_agent on yourself — the lead releases you once the work
+              is accepted, so it can send you review findings to fix."
    )
    ```
 8. Wait for an ACK from every worker with `check_inbox(as: "relay-lead")`. A missing ACK means that worker is not working — re-DM it.

plugins/claude-relay-plugin/skills/relay-pipeline/SKILL.md

@@ -16,6 +16,7 @@ Workers are spawned with Claude Code's built-in **Agent tool**. The relay is onl
 - Use `subagent_type: "relay-worker"`. Only `relay-worker` subagents get the Agent Relay MCP server, the inbox-polling hooks, and the worker protocol. Other subagent types (`researcher`, `general-purpose`, …) cannot talk over the relay.
 - Run pipeline stages in **foreground mode** (the default) so each stage finishes before the next starts.
 - Workers inherit the workspace automatically — the relay MCP server resolves the workspace pinned to this project. **Do not put the workspace key in a worker prompt.** It is an administrative credential, and copying it into N prompts puts it in N transcripts. If a worker reports no workspace, fix the pin (step 2) rather than pasting the key.
+- **One relay team per checkout.** The pin is per-project and last-writer-wins, so two leads running teams from the same directory will fight over it and a worker can register into the other lead's workspace. Run concurrent teams from separate checkouts or git worktrees. The ACK gate below is what catches this: a worker that landed in the wrong workspace finds no assignment and cannot ACK.
 - The `SubagentStart` hook injects the relay bootstrap (register, check inbox, ACK, DONE) into every worker.
 - Use the relay MCP tools (`send_dm`, `check_inbox`) to receive each stage's handoff.
 - Do not add setup scripts or dependencies. Use the plugin's existing hooks, MCP tools, and `relay-worker` agent definition.
@@ -24,33 +25,37 @@ Workers are spawned with Claude Code's built-in **Agent tool**. The relay is onl
 
 1. Pick a stable coordinator name — `relay-lead`. Pass `as: "relay-lead"` on **every** relay tool call you make, so your messages, inbox reads, and reactions stay attributed to the lead.
 2. **Set up the workspace.** Call `register_agent` with `relay-lead`. If it fails with "Workspace key not configured", call `create_workspace`, then `register_agent` again. Both `create_workspace` and `set_workspace_key` pin the workspace to this project, which is how workers pick it up.
-3. **Give the user a link to follow along.** Call `get_observer_url` and print the URL it returns. It is backed by a read-only token that expires, so it is safe to share. Never build an observer URL from the workspace key, and never print the key.
+3. **Give the user a link to follow along.** Call `get_observer_url` and print the URL it returns — or run `agent-relay observer` if your session does not expose that tool. Either way the link is backed by a read-only token that expires, so it is safe to share. Never build an observer URL from the workspace key, and never print the key.
 4. Break the task into ordered stages. Every stage needs a concrete handoff artifact for the next one: a summary, a decision, a file path, a diff, or a verified output.
 5. Keep the stage count low and explicit — prefer 2–5 with distinct responsibilities.
 6. Start stage 1. Spawn its worker with the Agent tool in foreground mode:
-   ```
+   ```text
    Agent(
      subagent_type: "relay-worker",
      prompt: "You are relay-stage-1. Your lead is relay-lead.
               CRITICAL: pass as: \"relay-stage-1\" on every relay tool call, or your messages
               can be attributed to another agent.
               Your task: [stage 1 scope].
               Files: [relevant files].
-              When done, DM your lead a DONE message containing: [handoff artifact description].
-              Do NOT release yourself when done — stay idle in case the stage needs a fix."
+              When done, DM your lead a DONE message containing: [handoff artifact description],
+              then end your turn so the lead can continue.
+              Do not call remove_agent on yourself — the lead releases you."
    )
    ```
 7. Wait for stage 1's DONE with `check_inbox(as: "relay-lead")`. Never start downstream work on an assumption about what the stage produced.
 8. For each later stage, spawn a worker carrying the original task context, the upstream DONE summary and handoff artifact, and any files, decisions, or constraints the earlier stages produced:
-   ```
+   ```text
    Agent(
      subagent_type: "relay-worker",
      prompt: "You are relay-stage-2. Your lead is relay-lead.
               CRITICAL: pass as: \"relay-stage-2\" on every relay tool call.
               Previous stage completed: [DONE summary from stage 1].
               Your task: [stage 2 scope, using stage 1's output].
               Files: [relevant files].
-              Do NOT release yourself when done — stay idle in case the stage needs a fix."
+              When done, DM your lead a DONE message containing: [this stage's handoff artifact —
+              or, if this is the final stage, the deliverable plus the evidence that proves it works],
+              then end your turn so the lead can continue.
+              Do not call remove_agent on yourself — the lead releases you."
    )
    ```
 9. Keep a live stage table in your notes: stage, scope, ACK, blocked, DONE, handoff artifact.
@@ -60,6 +65,8 @@ Workers are spawned with Claude Code's built-in **Agent tool**. The relay is onl
 ## Rules
 
 - Use a pipeline only for genuine dependencies. If the stages can run independently, switch to fan-out.
+- Stages run in the foreground, so a stage worker **must end its turn** after sending DONE. Telling it to stay idle deadlocks the run: the blocking Agent call never returns, so the lead can never read the DONE or spawn the next stage. (Team and fan-out workers are backgrounded and do stay idle — that instruction belongs there, not here.)
+- Releasing a relay identity (`remove_agent`) is separate from ending a turn. Workers never do the former; the lead does it once the whole pipeline is accepted.
 - Handoffs must be explicit. A downstream worker should never have to guess what mattered upstream.
 - If a stage fails or is blocked, stop the pipeline, resolve the blocker, and resume from that stage.
 - Workers cannot spawn their own subagents — only the lead spawns.

plugins/claude-relay-plugin/skills/relay-team/SKILL.md

@@ -16,6 +16,7 @@ Workers are spawned with Claude Code's built-in **Agent tool**. The relay is onl
 - Use `subagent_type: "relay-worker"`. Only `relay-worker` subagents get the Agent Relay MCP server, the inbox-polling hooks, and the worker protocol. Other subagent types (`researcher`, `general-purpose`, …) cannot talk over the relay.
 - Run workers in **background mode** (`run_in_background: true`) so they work concurrently.
 - Workers inherit the workspace automatically — the relay MCP server resolves the workspace pinned to this project. **Do not put the workspace key in a worker prompt.** It is an administrative credential, and copying it into N prompts puts it in N transcripts. If a worker reports no workspace, fix the pin (step 2) rather than pasting the key.
+- **One relay team per checkout.** The pin is per-project and last-writer-wins, so two leads running teams from the same directory will fight over it and a worker can register into the other lead's workspace. Run concurrent teams from separate checkouts or git worktrees. The ACK gate below is what catches this: a worker that landed in the wrong workspace finds no assignment and cannot ACK.
 - The `SubagentStart` hook injects the relay bootstrap (register, check inbox, ACK, DONE) into every worker.
 - Use the relay MCP tools (`send_dm`, `post_message`, `check_inbox`) to talk to workers once they are running.
 - Do not add setup scripts or dependencies. Use the plugin's existing hooks, MCP tools, and `relay-worker` agent definition.
@@ -24,11 +25,11 @@ Workers are spawned with Claude Code's built-in **Agent tool**. The relay is onl
 
 1. Pick a stable coordinator name — `relay-lead`. Pass `as: "relay-lead"` on **every** relay tool call you make, so your messages, inbox reads, and reactions stay attributed to the lead.
 2. **Set up the workspace.** Call `register_agent` with `relay-lead`. If it fails with "Workspace key not configured", call `create_workspace`, then `register_agent` again. Both `create_workspace` and `set_workspace_key` pin the workspace to this project, which is how workers pick it up.
-3. **Give the user a link to follow along.** Call `get_observer_url` and print the URL it returns. It is backed by a read-only token that expires, so it is safe to share. Never build an observer URL from the workspace key, and never print the key.
+3. **Give the user a link to follow along.** Call `get_observer_url` and print the URL it returns — or run `agent-relay observer` if your session does not expose that tool. Either way the link is backed by a read-only token that expires, so it is safe to share. Never build an observer URL from the workspace key, and never print the key.
 4. Read the task, inspect the relevant code, and decide whether parallel work is justified. Prefer 1 worker for tightly coupled work, 2–5 for genuinely separable work.
 5. Break the task into non-overlapping scopes. Each worker needs a concrete deliverable, the relevant files, and an explicit success condition.
 6. Spawn each worker with the Agent tool:
-   ```
+   ```text
    Agent(
      subagent_type: "relay-worker",
      run_in_background: true,
@@ -38,7 +39,9 @@ Workers are spawned with Claude Code's built-in **Agent tool**. The relay is onl
               Your task: [specific scope and deliverables].
               Files: [list of files/directories].
               Success condition: [what done looks like].
-              Do NOT release yourself when done — report DONE and stay idle for review."
+              When done, DM your lead a DONE message with the evidence for your scope.
+              Do not call remove_agent on yourself — the lead releases you once the work
+              is accepted, so it can send you review findings to fix."
    )
    ```
 7. After spawning, DM each worker any extra context it needs.