fix(cli): warn when squad watch receives unused message args (#703)

CHANGELOG.md

@@ -4,6 +4,7 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+
 ### Added — Full Work Monitor for squad watch (#708)
 - `--execute` flag spawns Copilot sessions to work on actionable issues autonomously
 - Multi-platform support — auto-detects GitHub vs Azure DevOps from git remote URL
@@ -30,6 +31,12 @@ All notable changes to this project will be documented in this file.
 - **Contract test suite** (#640) — provider conformance tests ensuring all implementations satisfy the StorageProvider interface
 - **Sample projects** (#640) — `storage-provider-azure` and `storage-provider-sqlite` in `samples/`
 
+### Fixed — squad watch ignores extra arguments silently (#703)
+- `squad watch` (and `squad triage`) now warns when extra arguments are passed instead of silently ignoring them — users see: `⚠️  Watch mode does not route messages to agents. Ignoring: "..."`
+- Documentation in `ralph.md` and `cli.md` clarifies that `squad watch` is a polling loop, not a message router — create a `squad:{agent}` issue label to route work to a specific agent
+
+
+
 ## [0.9.0] - 2026-03-23
 
 ### Added — Personal Squad Governance Layer

docs/src/content/docs/features/ralph.md

@@ -208,6 +208,23 @@ 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
 
+
+:::caution[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:
@@ -353,6 +370,7 @@ squad watch --execute                       # full work monitor (auto-detects pl
 - ADO rate limiting is handled differently — the circuit breaker skips quota checks
 - ADO PRs don't expose `statusCheckRollup` — CI status columns may be empty
 
+
 ### Three layers of Ralph
 
 | Layer | When | How |

docs/src/content/docs/reference/cli.md

@@ -37,7 +37,8 @@ squad init
 | `squad upgrade --migrate-directory` | Rename legacy `.ai-team/` directory to `.squad/` | Yes |
 | `squad link <team-repo-path>` | Link project to a remote team root | 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 — 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 |
@@ -49,6 +50,7 @@ squad init
 | `squad watch --max-concurrent N` | Max parallel issues per round (default: 1) | Yes |
 | `squad watch --timeout N` | Per-issue timeout in minutes (default: 30) | Yes |
 | `squad watch --copilot-flags "..."` | Extra flags for Copilot CLI | Yes |
+
 | `squad copilot` | Add the @copilot coding agent to the team | Yes |
 | `squad copilot --off` | Remove @copilot from the team | Yes |
 | `squad copilot --auto-assign` | Enable auto-assignment for @copilot | Yes |

packages/squad-cli/src/cli-entry.ts

@@ -383,6 +383,19 @@ async function main(): Promise<void> {
         : { projectNumber: parseInt(args[boardProjectIdx + 1]!, 10) };
     }
 
+    // Detect positional args that look like agent messages (user may expect routing)
+    const flagArgValues = new Set(
+      ([intervalIdx, copilotFlagsIdx, agentCmdIdx, maxConcurrentIdx, timeoutIdx, boardProjectIdx] as number[])
+        .filter(i => i !== -1 && args[i + 1])
+        .map(i => args[i + 1]!)
+    );
+    const unknownPositionals = args.filter(a => a !== cmd && !a.startsWith('--') && !flagArgValues.has(a));
+    if (unknownPositionals.length > 0) {
+      const message = unknownPositionals.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`);
+    }
+
     // Load config: .squad/config.json merged with CLI overrides
     const config = loadWatchConfig(process.cwd(), {
       interval,