From 85dc7c8d55566a368bd27241b8e170146919a28b Mon Sep 17 00:00:00 2001
From: "Dina Berry (She/her)" <diberry@microsoft.com>
Date: Sun, 5 Apr 2026 10:52:17 -0700
Subject: [PATCH] fix(cli): warn when squad watch receives unused message args
 (#703)

Detects extra positional args passed to squad watch and prints a clear
warning instead of silently ignoring them. Users who expect routing get
guidance to use an interactive session.

Closes #703

Co-authored-by: tamirdresher <tamirdresher@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .changeset/watch-message-warning.md     |  5 +++++
 docs/src/content/docs/features/ralph.md | 15 +++++++++++++++
 docs/src/content/docs/reference/cli.md  |  2 +-
 packages/squad-cli/src/cli-entry.ts     |  6 ++++--
 4 files changed, 25 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/watch-message-warning.md

diff --git a/.changeset/watch-message-warning.md b/.changeset/watch-message-warning.md
new file mode 100644
index 000000000..9f26567e5
--- /dev/null
+++ b/.changeset/watch-message-warning.md
@@ -0,0 +1,5 @@
+---
+'@bradygaster/squad-cli': patch
+---
+
+Warn when squad watch receives unused positional arguments instead of silently ignoring them
diff --git a/docs/src/content/docs/features/ralph.md b/docs/src/content/docs/features/ralph.md
index e6f42e399..b3a1f056e 100644
--- a/docs/src/content/docs/features/ralph.md
+++ b/docs/src/content/docs/features/ralph.md
@@ -208,6 +208,21 @@ This runs as a standalone local process (not inside Copilot) that:
 - Assigns @copilot to `squad:copilot` issues (if auto-assign is enabled)
 - Runs until Ctrl+C
 
+> ⚠️ **Watch mode does not route messages**
+>
+> `squad watch` is a **triage polling loop**, not a message router. Extra arguments like agent names or messages are ignored:
+>
+> ```bash
+> # ❌ This does NOT route to Nick — the message is ignored
+> squad watch --interval 5 "Nick, Run scheduled tasks"
+>
+> # ✅ To address an agent directly, use an interactive session:
+> squad
+> > Nick, Run scheduled tasks
+> ```
+>
+> To route work to a specific agent, create a GitHub issue with the appropriate `squad:{member}` label — `squad watch` will pick it up during the next poll cycle.
+
 ### Full Work Monitor Mode (`--execute`)
 
 Add `--execute` to transform Ralph from a triage bot into a full work monitor that spawns Copilot sessions and actually does the work:
diff --git a/docs/src/content/docs/reference/cli.md b/docs/src/content/docs/reference/cli.md
index 6c47ae2da..8944eb170 100644
--- a/docs/src/content/docs/reference/cli.md
+++ b/docs/src/content/docs/reference/cli.md
@@ -40,7 +40,7 @@ squad init
 | `squad upgrade` | Upgrade Squad-owned files to latest version | Yes |
 | `squad upgrade --migrate-directory` | Rename legacy `.ai-team/` directory to `.squad/` | Yes |
 | `squad triage` | Auto-triage issues and assign to team (primary name; `watch` is an alias) | Yes |
-| `squad triage --interval <min>` | Continuous triage (default: every 10 min) | Yes |
+| `squad triage --interval <min>` | Continuous triage (default: every 10 min). **Note:** extra args (e.g., agent messages) are ignored — triage/watch is a polling loop, not a message router | Yes |
 | `squad watch --execute` | Enable work execution (spawn Copilot to work on issues) | Yes |
 | `squad watch --monitor-teams` | Scan Teams for actionable messages each round | Yes |
 | `squad watch --monitor-email` | Scan email for alerts and action items each round | Yes |
diff --git a/packages/squad-cli/src/cli-entry.ts b/packages/squad-cli/src/cli-entry.ts
index 421baca46..3d48c57a3 100644
--- a/packages/squad-cli/src/cli-entry.ts
+++ b/packages/squad-cli/src/cli-entry.ts
@@ -473,8 +473,10 @@ async function main(): Promise<void> {
       if (arg.startsWith('-')) continue;
       positionalArgs.push(arg);
     }
-    if (positionalArgs.length > 0 && config.verbose) {
-      console.log(`[verbose] ⚠️ Positional args ignored by watch: "${positionalArgs.join(' ')}". Use --execute to process issues.`);
+    if (positionalArgs.length > 0) {
+      const message = positionalArgs.join(' ');
+      console.warn(`\n⚠️  Watch mode does not route messages to agents. Ignoring: "${message}"`);
+      console.warn(`   To address an agent directly, use an interactive session instead.\n`);
     }
 
     await runWatch(getSquadStartDir(), config);