From dbd8179043b65a7752c164d51afaf3e653a52842 Mon Sep 17 00:00:00 2001 From: "Dina Berry (She/her)" Date: Tue, 31 Mar 2026 13:27:58 -0700 Subject: [PATCH] fix(cli): warn when squad watch receives unused message args (#703) Add warning when squad watch receives message arguments it cannot route. Update docs and changelog. Co-authored-by: tamirdresher Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CHANGELOG.md | 7 +++++++ docs/src/content/docs/features/ralph.md | 18 ++++++++++++++++++ docs/src/content/docs/reference/cli.md | 4 +++- packages/squad-cli/src/cli-entry.ts | 13 +++++++++++++ 4 files changed, 41 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5dab04371..c4ef2d72e 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/src/content/docs/features/ralph.md b/docs/src/content/docs/features/ralph.md index 3a12c2ad7..3c3b152b8 100644 --- a/docs/src/content/docs/features/ralph.md +++ b/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 | diff --git a/docs/src/content/docs/reference/cli.md b/docs/src/content/docs/reference/cli.md index d472a3e60..a03d418a4 100644 --- a/docs/src/content/docs/reference/cli.md +++ b/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 ` | 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 ` | Continuous triage (default: every 10 min) | Yes | + +| `squad triage --interval ` | 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 | diff --git a/packages/squad-cli/src/cli-entry.ts b/packages/squad-cli/src/cli-entry.ts index c6101a71c..2df3b4702 100644 --- a/packages/squad-cli/src/cli-entry.ts +++ b/packages/squad-cli/src/cli-entry.ts @@ -383,6 +383,19 @@ async function main(): Promise { : { 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,