feat(watch): --verbose flag for debugging empty boards by tamirdresher · Pull Request #782 · bradygaster/squad

tamirdresher · 2026-04-03T14:51:16Z

Add `--verbose` flag for debugging `squad watch`

When watch says "Board is clear — Ralph is idling", users have zero visibility into why. This PR adds --verbose / -v that outputs diagnostic info at every step.

Usage

squad watch --execute --verbose
squad watch --execute -v --interval 5

What verbose shows

Phase	Output
Startup	Repo, platform (github/ado), auth account, agent-cmd, dispatch mode, interval
Per-round	Issues found with labels/assignees, why each was included/excluded
PRs	Open PRs with draft/review status
Execute	Agent command being used, batch size, dispatch classification
Board	Counter breakdown (untriaged, assigned, drafts, review, CI, merge-ready)
Timing	Round duration in seconds
Warnings	Unused positional args, auth failures

Example output

[verbose] ── Startup ──
[verbose]   repo: C:\src\my-project
[verbose]   platform: github
[verbose]   auth: tamirdresher
[verbose]   execute: true
[verbose]   agentCmd: agency copilot --agent squad
[verbose]   interval: 10m
[verbose] ── Round 1 ──
[verbose] Issues found: 3
[verbose]   #42: "Fix auth bug" [squad, squad:data] assignees=[tamirdresher]
[verbose]   #43: "Research new lib" [squad] assignees=[]
[verbose]   #44: "Update docs" [squad, squad:seven] assignees=[]
[verbose] PRs found: 1
[verbose]   PR #100: "Fix auth" draft=false review=APPROVED
[verbose]   untriaged: 1
[verbose]   assigned: 2
[verbose]   readyToMerge: 1
[verbose] Round 1 complete (2.8s)

Also fixes

Warns on unused positional args: squad watch "Run scheduled tasks" now shows ⚠️ Positional args ignored by watch in verbose mode (the prompt is NOT used by watch)

Files changed

File	Change
`verbose.ts`	New — `createVerboseLogger()` (log, warn, section, table)
`config.ts`	`verbose` field in WatchConfig
`types.ts`	`verbose` in WatchContext
`cli-entry.ts`	`--verbose` / `-v` parsing + positional arg warning
`index.ts`	Verbose logging in startup, round loop, issue/PR scan, board report
`execute.ts`	Verbose logging for agent command, batch, dispatch

Closes #781

… failures (#781) New --verbose / -v flag outputs diagnostic info: - Startup: repo, platform, auth account, agent-cmd, dispatch mode - Per-round: issues found with labels/assignees, PRs with review status - Execute: agent command, batch selection, dispatch classification - Timing: round duration - Warnings: unused positional args, auth failures Also warns when positional args are passed to watch (they're ignored). New file: verbose.ts — createVerboseLogger utility (log/warn/section/table) Closes #781 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-04-03T14:51:29Z

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 820b148

⚠️ 4 item(s) to address before review

Status	Check	Details
❌	Single commit	7 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
❌	Copilot threads resolved	1 unresolved Copilot thread(s) — fix and resolve before merging
❌	CI passing	13 check(s) still running

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

Copilot

Pull request overview

Adds a --verbose / -v diagnostics mode to squad watch to make “empty board” states debuggable by printing startup/round/board details and a warning about ignored positional args.

Changes:

Introduces a small createVerboseLogger() helper and wires it through watch + execute flows.
Extends watch config/context to carry a verbose flag (CLI + .squad/config.json).
Adds additional verbose output for startup, issue/PR discovery, board counters, and execute batching.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/squad-cli/src/cli/commands/watch/verbose.ts	New verbose logger utility (log/warn/section/table).
packages/squad-cli/src/cli/commands/watch/types.ts	Adds `verbose?: boolean` to `WatchContext`.
packages/squad-cli/src/cli/commands/watch/index.ts	Wires verbose logging into startup + per-round checks and reporting.
packages/squad-cli/src/cli/commands/watch/config.ts	Adds `verbose` to config load/merge + reserved-key handling.
packages/squad-cli/src/cli/commands/watch/capabilities/execute.ts	Adds verbose diagnostics for execution batching/selection.
packages/squad-cli/src/cli-entry.ts	Parses `--verbose/-v` and adds positional-args warning.
.changeset/watch-verbose-mode.md	Changeset for releasing the new flag.

Copilot · 2026-04-03T14:54:30Z

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


+    // After parsing all flags, check for positional args that look like prompts
+    const watchArgStart = args.indexOf(cmd) + 1;
+    const positionalArgs = args.slice(watchArgStart).filter(a => !a.startsWith('--') && !a.startsWith('-'));


The positional-arg warning will produce false positives because it treats any token not starting with '-' as positional, including values for flags (e.g. --interval 5 makes 5 look positional). Consider tracking/stripping known option-value pairs (interval/timeout/max-concurrent/copilot-flags/agent-cmd/board-project, etc.) before checking for true positional args, so valid invocations don’t trigger the warning.

Suggested change

const positionalArgs = args.slice(watchArgStart).filter(a => !a.startsWith('--') && !a.startsWith('-'));

const knownValueFlags = new Set([

'--interval',

'--copilot-flags',

'--agent-cmd',

'--max-concurrent',

'--timeout',

'--board-project',

]);

const knownBooleanFlags = new Set([

'--execute',

'--verbose',

'-v',

...registry.all().flatMap((cap) => [`--${cap.name}`, `--no-${cap.name}`]),

]);

const positionalArgs: string[] = [];

const watchArgs = args.slice(watchArgStart);

for (let i = 0; i < watchArgs.length; i++) {

const arg = watchArgs[i]!;

if (knownValueFlags.has(arg)) {

i++;

continue;

}

if (knownBooleanFlags.has(arg) || arg.startsWith('-')) {

continue;

}

positionalArgs.push(arg);

}

Copilot · 2026-04-03T14:54:31Z

packages/squad-cli/src/cli/commands/watch/index.ts

+  // Auth check (verbose)
+  if (adapter.type === 'github') {
+    try {
+      const authOut = execFileSync('gh', ['auth', 'status'], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+      const activeAccount = authOut.match(/Logged in to .* account (\S+)/)?.[1];
+      vlog.log(`Auth: ${activeAccount ?? 'unknown'}`);
+    } catch {
+      vlog.warn('gh auth status failed — API calls may fail silently');
+    }
+  }


gh auth status is executed unconditionally (even when --verbose is off) because only the logging is gated. This adds a synchronous process spawn to every watch startup and can slow/hang startup. Gate the auth check itself behind config.verbose (or the vlog enabled state), and consider running it after confirming ghAvailable() to avoid calling gh before the availability check.

Copilot · 2026-04-03T14:54:31Z

packages/squad-cli/src/cli/commands/watch/index.ts

+  vlog.section('Startup');
+  vlog.table({
+    repo: teamRoot,
+    platform: adapter.type,
+    verbose: true,
+    interval: `${config.interval}m`,
+    execute: config.execute ?? false,
+    agentCmd: config.agentCmd ?? '(default: gh copilot)',
+    dispatchMode: config.capabilities['wave-dispatch'] ? 'wave' : 'task',
+    maxConcurrent: config.maxConcurrent ?? 1,
+  });


The startup verbose table hard-codes verbose: true, which can be misleading if the logger enablement logic changes (and is redundant since the table only prints when verbose is enabled). Prefer using config.verbose (or omitting this field entirely) so the diagnostic output reflects the actual configuration source-of-truth.

diberry

LGTM

Review Summary

Verdict: Approve

What's Good

Solves real pain — 'Board is clear' with zero visibility into why. Verbose output covers startup, per-round issues/PRs, execute phase, board counters, and timing.
Clean implementation — createVerboseLogger() is a simple factory returning no-ops when disabled. Zero overhead when --verbose is off.
Good API surface — log, warn, section, table cover all formatting needs. [verbose] prefix makes output easy to grep.
Covers all phases — Startup config dump, auth check, per-round issue details (labels + assignees), PR scan, execute batch, board counters, round timing.
Positional arg warning — Smart catch for squad watch "Run tasks" where prompt gets silently ignored. Only warns in verbose mode.
Config file support — verbose can be set in squad-watch.json too, not just CLI flag.

Suggestions (non-blocking)

Consider dropping -v short flag (reserve for --version if CLI ever adds it)
Add 2-3 basic tests for createVerboseLogger (enabled/disabled output)
Future: derive vlog from WatchContext.verbose instead of threading parameter separately

- Gate gh auth status behind config.verbose (avoid unnecessary process spawn) - Fix startup table verbose: true → config.verbose - Fix positional args false-positive: skip values after known value-flags Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add clarifying comment explaining verbose:true is expected in startup table (table only renders when verbose mode is active) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add JSDoc to reportBoard() documenting default notifyLevel='important' - Include machine/repo context in 'Board is clear' message for all modes - Add comment noting verbose flag parsing is in PR #782 - Replace console.log direct mutation with vi.spyOn in tests - Update changeset to clarify attribution is in round headers and clear message Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tamirdresher · 2026-04-04T19:27:04Z

Superseded by #830 — combined into a single watch next-gen PR for easier review.

tamirdresher · 2026-04-04T20:11:19Z

Closing — superseded by #830 (watch-next-gen combined PR)

github-actions · 2026-04-04T20:28:33Z

🟡 Impact Analysis — PR #782

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	7
Files added	2
Files modified	5
Files deleted	0
Modules touched	2
Critical files	1

🎯 Risk Factors

7 files changed (6-20 → MEDIUM)
2 modules touched (2-4 → MEDIUM)
Critical files touched: packages/squad-cli/src/cli/commands/watch/index.ts

📦 Modules Affected

root (1 file)

.changeset/watch-verbose-mode.md

squad-cli (6 files)

packages/squad-cli/src/cli-entry.ts
packages/squad-cli/src/cli/commands/watch/capabilities/execute.ts
packages/squad-cli/src/cli/commands/watch/config.ts
packages/squad-cli/src/cli/commands/watch/index.ts
packages/squad-cli/src/cli/commands/watch/types.ts
packages/squad-cli/src/cli/commands/watch/verbose.ts

⚠️ Critical Files

packages/squad-cli/src/cli/commands/watch/index.ts

This report is generated automatically for every PR. See #733 for details.

… dev

Copilot AI review requested due to automatic review settings April 3, 2026 14:51

Copilot started reviewing on behalf of tamirdresher April 3, 2026 14:51 View session

Copilot AI reviewed Apr 3, 2026

View reviewed changes

tamirdresher mentioned this pull request Apr 3, 2026

[Bug] squad watch triage fails silently — wrong label slug + missing label pre-creation #784

Closed

tamirdresher requested a review from diberry April 3, 2026 18:09

diberry approved these changes Apr 3, 2026

View reviewed changes

Copilot and others added 3 commits April 3, 2026 23:50

Merge branch 'dev' into squad/781-watch-verbose

b6d38f8

fix: address Copilot review comments

e356645

- Add clarifying comment explaining verbose:true is expected in startup table (table only renders when verbose mode is active) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tamirdresher mentioned this pull request Apr 4, 2026

feat(watch): next-gen watch with execute redesign, robustness, and PS1 parity #830

Merged

tamirdresher closed this Apr 4, 2026

tamirdresher reopened this Apr 4, 2026

tamirdresher added 3 commits April 4, 2026 23:30

merge: resolve conflicts between verbose-flag and watch-ux-fixes from…

e6247b9

… dev

merge: resolve conflicts with dev (fleet-dispatch + ux-fixes)

e894553

fix: remove undefined maxConcurrent ref in execute.ts verbose log

820b148

tamirdresher merged commit a22e087 into dev Apr 4, 2026
17 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(watch): --verbose flag for debugging empty boards#782

feat(watch): --verbose flag for debugging empty boards#782
tamirdresher merged 7 commits intodevfrom
squad/781-watch-verbose

tamirdresher commented Apr 3, 2026

Uh oh!

github-actions bot commented Apr 3, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

Copilot AI Apr 3, 2026

Uh oh!

diberry left a comment

Uh oh!

tamirdresher commented Apr 4, 2026

Uh oh!

tamirdresher commented Apr 4, 2026

Uh oh!

github-actions bot commented Apr 4, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

-    const positionalArgs = args.slice(watchArgStart).filter(a => !a.startsWith('--') && !a.startsWith('-'));
+    const knownValueFlags = new Set([
+      '--interval',
+      '--copilot-flags',
+      '--agent-cmd',
+      '--max-concurrent',
+      '--timeout',
+      '--board-project',
+    ]);
+    const knownBooleanFlags = new Set([
+      '--execute',
+      '--verbose',
+      '-v',
+      ...registry.all().flatMap((cap) => [`--${cap.name}`, `--no-${cap.name}`]),
+    ]);
+    const positionalArgs: string[] = [];
+    const watchArgs = args.slice(watchArgStart);
+    for (let i = 0; i < watchArgs.length; i++) {
+      const arg = watchArgs[i]!;
+      if (knownValueFlags.has(arg)) {
+        i++;
+        continue;
+      }
+      if (knownBooleanFlags.has(arg) || arg.startsWith('-')) {
+        continue;
+      }
+      positionalArgs.push(arg);
+    }

Conversation

tamirdresher commented Apr 3, 2026

Add --verbose flag for debugging squad watch

Usage

What verbose shows

Example output

Also fixes

Files changed

Uh oh!

github-actions bot commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🛫 PR Readiness Check

⚠️ 4 item(s) to address before review

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

diberry left a comment

Choose a reason for hiding this comment

Review Summary

What's Good

Suggestions (non-blocking)

Uh oh!

tamirdresher commented Apr 4, 2026

Uh oh!

tamirdresher commented Apr 4, 2026

Uh oh!

github-actions bot commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟡 Impact Analysis — PR #782

📊 Summary

🎯 Risk Factors

📦 Modules Affected

⚠️ Critical Files

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add `--verbose` flag for debugging `squad watch`

github-actions bot commented Apr 3, 2026 •

edited

Loading

github-actions bot commented Apr 4, 2026 •

edited

Loading