feat(orchestrating-agent-relay): teach the orchestrator to hand out an observer link

README.md

@@ -12,7 +12,7 @@ Package metadata lives in [prpm.json](prpm.json). The repo currently publishes `
 | [writing-agent-relay-workflows](skills/writing-agent-relay-workflows/SKILL.md) | 1.6.18 | Build multi-agent workflows with WorkflowBuilder, DAG dependencies, Relayfile-backed Slack human assistance, integration subscriptions, waitFor gates, review-depth review/fix loops, channels, and chat-native coordination recipes. |
 | [setting-up-relayfile](skills/setting-up-relayfile/SKILL.md) | 1.1.1 | Set up Relayfile mounts and writeback for provider files through local filesystem access. |
 | [using-agent-relay](skills/using-agent-relay/SKILL.md) | 1.4.0 | Participant-side MCP reference for a **registered** relay agent (spawned worker / registered lead): messaging, channels, threads, reactions, search, inbox, actions, and worker spawn/release. Counterpart to `orchestrating-agent-relay`. |
-| [orchestrating-agent-relay](skills/orchestrating-agent-relay/SKILL.md) | 2.2.0 | The canonical way to run agent-relay: self-bootstrap the broker (`agent-relay node up`) and autonomously spawn, monitor, and coordinate a worker team over the relay MCP without human intervention. |
+| [orchestrating-agent-relay](skills/orchestrating-agent-relay/SKILL.md) | 2.3.0 | The canonical way to run agent-relay: self-bootstrap the broker (`agent-relay node up`) and autonomously spawn, monitor, and coordinate a worker team over the relay MCP without human intervention. |
 | [relay-80-100-workflow](skills/relay-80-100-workflow/SKILL.md) | 1.0.8 | Author workflows that close the 80-to-100 validation gap with repair-aware test, verify, review-depth review/fix with test hardening, and commit gates. |
 | [review-fix-signoff-loop](skills/review-fix-signoff-loop/SKILL.md) | 1.0.2 | Loop review, repair, validation, and fresh-context dual-agent signoff until independent reviewers both satisfy the verdict contract. |
 | [trigger-autocomplete-catalog](skills/trigger-autocomplete-catalog/SKILL.md) | 1.0.0 | Enforce webhook/event trigger autocomplete coverage through KNOWN_TRIGGER_CATALOG in @relayfile/adapter-core. |

prpm.json

@@ -89,7 +89,7 @@
     },
     {
       "name": "orchestrating-agent-relay",
-      "version": "2.2.0",
+      "version": "2.3.0",
       "description": "The canonical way to run agent-relay - self-bootstrap the local broker and autonomously spawn, monitor, and coordinate a team of worker agents without human intervention. Covers infrastructure startup, agent spawning, lifecycle monitoring, message-based reading via the relay MCP, and team coordination.",
       "format": "claude",
       "subtype": "skill",

skills/orchestrating-agent-relay/SKILL.md

@@ -62,6 +62,7 @@ reference is the **`using-agent-relay`** skill.
 | Send DM to worker (MCP)           | `send_dm(to: "Worker1", text: "...")`                             |
 | Post to channel (MCP)             | `post_message(channel: "general", text: "...")`                  |
 | Read worker replies (MCP)         | `check_inbox(limit: 20)` / `list_messages(channel: "general")`   |
+| Give a human a follow-along link  | `agent-relay observer`                                          |
 | Inspect a worker's TTY            | `agent-relay node agent attach Worker1 --mode view`             |
 | Release worker                    | `agent-relay node agent release Worker1`                         |
 | Stop broker                       | `agent-relay node down`                                          |
@@ -156,6 +157,28 @@ runs in `interactive` spawn mode; pass `--exit-after-task` for a one-shot worker
 > for at least 60s (e.g. a 30-iteration poll) before escalating to
 > troubleshooting.
 
+### Step 2.5: Give the Human a Way to Watch (optional)
+
+A human driving an autonomous run usually wants to see what the team is saying
+without joining it. Hand them a read-only observer link:
+
+```bash
+agent-relay observer
+```
+
+That prints a URL backed by a scoped `ot_live_` token — read-only, expiring in
+24 hours, agent DMs excluded. Narrow it with `--channels build,review`, widen it
+with `--include-dms` or `--expires 7d`, and cut it off early with
+`agent-relay observer revoke <id>`.
+
+From the relay MCP, the equivalent is `get_observer_url`.
+
+> **Never build an observer URL from the workspace key.** `rk_live_` is an
+> administrative credential — it can send messages, spawn agents, and change
+> workspace settings — and a URL query string is not a place to put one. The
+> realtime endpoint rejects it anyway; only a scoped observer token with
+> `stream:read` is accepted.
+
 ### Step 3: Monitor and Coordinate
 
 The orchestrator reads and sends through the relay MCP (it is auto-registered as
@@ -342,6 +365,9 @@ Quick Reference. Then enforce this protocol:
   model
 - Poll `agent-relay node agent list` for worker liveness; set a wall-clock
   fallback so a silently-dead worker can't hang the loop
+- If a human is watching, give them a follow-along link with
+  `agent-relay observer` and print the URL it returns. Never print the
+  workspace key or put it in a URL
 ```
 
 ## Multi-Round Review Loops (DONE → NO-GO → fix → re-review)
@@ -470,6 +496,7 @@ named `target_node`).
 | New worker appears in `node agent list` but no ACK yet  | Expected — appearing means process up (~5s); the CLI cold-starts for another 30–45s before its first ACK DM. Wait ≥60s before troubleshooting a fresh worker                                   |
 | Harness blocks `sleep 25; check_inbox ...`               | Bare foreground `sleep` wait loops are disallowed in harnessed environments. Run the poll loop with `run_in_background` (or Monitor + until-loop); the inline `sleep` snippets show logic only |
 | Worker self-removed; can't send review fixes             | Instruct workers not to self-remove until told. If already gone, spawn a fresh worker and re-inject branch + commit SHA + full verdict (see Multi-Round Review Loops)                          |
+| Told the user to open an observer URL built from the workspace key | That is an admin credential in a query string, and the realtime endpoint rejects it. Run `agent-relay observer` (or `get_observer_url`) and share the `ot_live_` URL it returns |
 | Worker died silently; loop hangs                         | Inbox polling fires on messages only. Poll `agent-relay node agent list` for liveness and set a wall-clock fallback (~30 min ScheduleWakeup)                                                  |
 
 ## Prerequisites