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

[tamirdresher]

Squad Watch — Next Generation

Combines 6 PRs into one cohesive watch feature set. This brings the CLI watch to near-parity with the PS1 ralph-watch reference implementation.

What's included

Execute redesign (was PR #776)

• Issue selection delegated to agent (no pre-filtering in TS)
• Rich prompt: Task/WHY/Success/Escalation + ralph-instructions.md reference
• Prompt written to temp file via -p flag (matches PS1 pattern)
• Fleet dispatch + machine capabilities plugin

Robustness (was PR #782)

• 4-tier error recovery: reset CB → re-probe auth → git pull → pause 30m
• Self-pull with stash/restart detection
• Overnight window (--overnight-start/--overnight-end)
• Sentinel stop file (.squad/ralph-stop)
• Generic auth via --auth-user + adapter.ensureAuth(preferredUser)
• Verbose flag

Capabilities (was PRs #794, #805)

• Cleanup capability (prune scratch/logs/stale files)
• Notify-level capability + board context

Health (was PR #809)

• --health flag shows PID, uptime, auth, capabilities
• PID file in os.tmpdir with repo-path hash

State backends (was PR #810)

• --state-backend flag: git-notes, orphan-branch, worktree
• StateBackend interface + GitNotesBackend + OrphanBranchBackend

Design decisions

• Agent command is configurable: --agent-cmd + --copilot-flags (no hardcoded 'agency')
• Auth user is configurable: --auth-user (no hardcoded usernames)
• All platform-specific code in adapter (GitHub + ADO)
• Cross-platform: execFileSync, no PS1/bash deps

Closes #775 #781 #792 #793 #804 #807 #808

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[github-actions]

🛫 PR Readiness Check

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

⚠️ 4 item(s) to address before review

Status	Check	Details
❌	Single commit	51 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	6 unresolved Copilot thread(s) — fix and resolve before merging
❌	CI passing	14 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.

[github-actions]

🏗️ Architectural Review

⚠️ Architectural review: 2 warning(s).

Severity	Category	Finding	Files
🟡 warning	export-surface	Package entry point(s) modified with 19 new/changed export(s). New public API surface requires careful review for backward compatibility.	packages/squad-sdk/src/index.ts
🟡 warning	sweeping-refactor	This PR touches 32 files (32 modified/added, 0 deleted). Large PRs are harder to review — consider splitting if possible.	—

---

Automated architectural review — informational only.

[github-actions]

🟠 Impact Analysis — PR #830

Risk tier: 🟠 HIGH

📊 Summary

Metric	Count
Files changed	32
Files added	14
Files modified	18
Files deleted	0
Modules touched	5
Critical files	4

🎯 Risk Factors

• 32 files changed (21-50 → HIGH)
• 5 modules touched (5-8 → HIGH)
• Critical files touched: packages/squad-cli/package.json, packages/squad-cli/src/cli/commands/watch/capabilities/index.ts, packages/squad-cli/src/cli/commands/watch/index.ts, packages/squad-sdk/src/index.ts

📦 Modules Affected

docs (4 files)

• docs/features/watch-next-gen.md
• docs/src/content/blog/030-v092-whats-coming.md
• docs/src/content/docs/features/notification-level.md
• docs/src/content/docs/features/ralph.md

root (7 files)

• .changeset/cleanup-ceremony.md
• .changeset/git-state-backends.md
• .changeset/quiet-notifications.md
• .changeset/watch-health.md
• .gitignore
• README.md
• cspell.json

squad-cli (8 files)

• packages/squad-cli/package.json
• packages/squad-cli/src/cli-entry.ts
• packages/squad-cli/src/cli/commands/watch/capabilities/cleanup.ts
• packages/squad-cli/src/cli/commands/watch/capabilities/index.ts
• packages/squad-cli/src/cli/commands/watch/capabilities/self-pull.ts
• packages/squad-cli/src/cli/commands/watch/config.ts
• packages/squad-cli/src/cli/commands/watch/health.ts
• packages/squad-cli/src/cli/commands/watch/index.ts

squad-sdk (6 files)

• packages/squad-sdk/src/index.ts
• packages/squad-sdk/src/platform/azure-devops.ts
• packages/squad-sdk/src/platform/github.ts
• packages/squad-sdk/src/platform/types.ts
• packages/squad-sdk/src/resolution.ts
• packages/squad-sdk/src/state-backend.ts

tests (7 files)

• test/cli-command-wiring.test.ts
• test/cli/upgrade.test.ts
• test/cli/watch-health.test.ts
• test/ralph-board.test.ts
• test/state-backend.test.ts
• test/watch-cleanup.test.ts
• test/watch-notify-level.test.ts

⚠️ Critical Files

• packages/squad-cli/package.json
• packages/squad-cli/src/cli/commands/watch/capabilities/index.ts
• packages/squad-cli/src/cli/commands/watch/index.ts
• packages/squad-sdk/src/index.ts

---

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

[Copilot]

Pull request overview

This PR delivers a “next-gen” squad watch experience, expanding the watch loop with new execution/dispatch behaviors, robustness features, health reporting, and related SDK support (scratch dir + git-native state backends), plus docs and test coverage.

Changes:

• Add watch enhancements: notify-level reporting, /fleet dispatch capability, cleanup capability, auth guard, and health check PID tracking.
• Introduce SDK utilities: scratch directory helpers and git-native state backends (git-notes + orphan branch).
• Add CLI self-upgrade support and accompanying docs/changesets/tests.

Reviewed changes

Copilot reviewed 37 out of 38 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
test/watch-notify-level.test.ts	Adds unit tests for notify-level output suppression/attribution.
test/watch-fleet-dispatch.test.ts	Adds unit tests for classifyIssue() read/write categorization.
test/watch-cleanup.test.ts	Adds unit tests for the new cleanup capability behavior.
test/state-backend.test.ts	Adds unit tests for new SDK state backends + resolver.
test/scratch-dir.test.ts	Adds unit tests for scratchDir() / scratchFile() helpers.
test/ralph-board.test.ts	Updates existing board-output test helper to pass notifyLevel.
test/cli/watch-health.test.ts	Adds tests for watch health check + PID file behaviors.
test/cli/watch-fleet-dispatch.test.ts	Adds CLI-level tests for dispatch classification.
test/cli/watch-execute.test.ts	Extends execute-mode tests to cover classification and routing expectations.
test/cli/upgrade.test.ts	Adds a test for upgrade --self behavior.
packages/squad-sdk/src/state-backend.ts	Implements Worktree/GitNotes/OrphanBranch state backends + resolver.
packages/squad-sdk/src/resolution.ts	Adds scratchDir() and scratchFile() utilities and stateBackend config field.
packages/squad-sdk/src/platform/types.ts	Extends platform adapter interface with optional ensureAuth().
packages/squad-sdk/src/platform/github.ts	Implements GitHub ensureAuth() auto-switch behavior.
packages/squad-sdk/src/platform/azure-devops.ts	Implements ADO ensureAuth() org default configuration.
packages/squad-sdk/src/index.ts	Exports scratch helpers and state backend APIs from SDK barrel.
packages/squad-sdk/src/config/init.ts	Ensures .squad/.scratch/ exists and is gitignored on init.
packages/squad-cli/src/cli/core/upgrade.ts	Adds selfUpgradeCli() for upgrading the CLI package itself.
packages/squad-cli/src/cli/commands/watch/index.ts	Adds notify-level reporting, auth guard, PID file integration, remediation tiers, and re-exports.
packages/squad-cli/src/cli/commands/watch/health.ts	Implements --health status output via PID file in OS temp.
packages/squad-cli/src/cli/commands/watch/config.ts	Extends watch config with notifyLevel/verbose/dispatch/etc.
packages/squad-cli/src/cli/commands/watch/capabilities/self-pull.ts	Enhances self-pull to stash/pull/pop + restart warning.
packages/squad-cli/src/cli/commands/watch/capabilities/index.ts	Registers new fleet-dispatch and cleanup capabilities.
packages/squad-cli/src/cli/commands/watch/capabilities/fleet-dispatch.ts	Adds /fleet batching dispatch capability.
packages/squad-cli/src/cli/commands/watch/capabilities/execute.ts	Redesigns execute behavior to build a richer prompt and classify issues.
packages/squad-cli/src/cli/commands/watch/capabilities/cleanup.ts	Adds housekeeping cleanup capability for scratch/log/inbox.
packages/squad-cli/src/cli-entry.ts	Adds --health, --self/--insider, and begins parsing new watch flags.
packages/squad-cli/package.json	Exports the new watch health module entrypoint.
docs/src/content/docs/features/ralph.md	Updates Ralph/watch docs to mention notify-level and cleanup.
docs/src/content/docs/features/notification-level.md	Adds a dedicated feature doc page for notify-level.
docs/src/content/blog/030-v092-whats-coming.md	Adds a draft blog post highlighting the upcoming features.
.gitignore	Minor formatting change (blank line).
.changeset/watch-health.md	Changeset entry for watch health feature.
.changeset/scratch-dir-utility.md	Changeset entry for scratch dir utility.
.changeset/quiet-notifications.md	Changeset entry for notify-level feature.
.changeset/git-state-backends.md	Changeset entry for git-native state backends.
.changeset/fleet-dispatch-hybrid.md	Changeset entry for fleet/hybrid dispatch.
.changeset/cleanup-ceremony.md	Changeset entry for cleanup capability.

[Copilot]

isProcessAlive() treats any process.kill(pid, 0) error as “dead”, but on some platforms (or when lacking permissions) kill throws EPERM even though the process exists. This breaks the intended behavior (and the added test). Handle EPERM as “alive” and only return false for ESRCH (and other definitive non-existence cases).

Suggested change

	*/
	export function isProcessAlive(pid: number): boolean {
	try {
	process.kill(pid, 0);
	return true;
	} catch {
	* `EPERM` means the process exists but cannot be signaled by this user.
	*/
	export function isProcessAlive(pid: number): boolean {
	try {
	process.kill(pid, 0);
	return true;
	} catch (error) {
	const code = typeof error === 'object' && error !== null && 'code' in error
	? (error as { code?: string }).code
	: undefined;
	if (code === 'EPERM') {
	return true;
	}
	if (code === 'ESRCH') {
	return false;
	}

[Copilot]

probeCurrentGhUser() (and the similar helper in watch/index.ts) only inspects stdout from gh auth status --active, but execFileSync() does not provide stderr on success. Since gh auth status frequently writes its status text to stderr even with exit code 0, this can return undefined even when authenticated. Consider using spawnSync/execFileSync via spawnSync result to parse both stdout+stderr on success as well as failure.

[Copilot]

Several new watch CLI flags are parsed (--notify-level, --overnight-start/--overnight-end, --sentinel-file, --auth-user), but the parsed values are never included in the cliOverrides passed to loadWatchConfig(). As a result, the flags have no effect at runtime. Also, --dispatch-mode is documented in the PR but is not parsed here at all, so config.dispatchMode can only be set via config file.

[Copilot]

--state-backend is written verbatim into .squad/config.json without validation. This allows invalid values that will later be ignored/fall back, but it’s better UX to validate upfront (worktree|external|git-notes|orphan) and fail fast with a clear message rather than persisting a bad config.

[Copilot]

selfUpgradeCli() builds a single shell command string and runs it via execSync(cmd), which (1) routes through the shell, (2) makes it harder to test/mocks (the added test spies on execFileSync, so it won’t observe this), and (3) ignores the force option entirely. Prefer execFileSync() with an args array (npm/pnpm/yarn + args), and wire options.force into the appropriate flag (e.g. --force for npm) so behavior matches the function signature and tests can reliably assert the invocation.

[Copilot]

File appears to start with a UTF-8 BOM / zero-width character before /** (shown as /**). This can cause noisy diffs and occasional tooling issues (linters, shebang parsing, etc.). Please remove the BOM so the file begins with a plain /**.

Suggested change

	/**
	/**

[Copilot]

This changeset file also appears to start with a UTF-8 BOM (---). Please remove the BOM so frontmatter parsing remains consistent across tools and platforms.

Suggested change

	---
	---

[Copilot]

The changeset text says the PID file is written to .squad/.watch-pid.json, but the implementation writes to an OS temp file (os.tmpdir()/squad-watch-{hash}.json) via getPidPath(). Please update the changeset (and any docs) to reflect the actual location, or change the implementation to match the documented .squad/ path.

Suggested change

	detection. Writes `.squad/.watch-pid.json` at startup for instance
	detection. Writes a watch PID file in the OS temp directory
	(`os.tmpdir()/squad-watch-{hash}.json`) at startup for instance

[Copilot]

ensureAuth() logs directly to stdout (console.log("✅ Auth context switched…")). Since this is in the SDK adapter layer, it introduces an unconditional user-facing side effect from a library call (and will also trigger the repo’s no-console eslint warning for console.log). Prefer returning a status (e.g., switched/targetUser) and letting the CLI decide when/how to display it (or only log under a passed-in verbose/logger option).

Suggested change

console.log(`✅ Auth context switched to ${targetUser}`);

[Copilot]

getActiveGhUser() claims to “capture stderr too”, but execFileSync() only returns stdout on success; stderr is only accessible on thrown errors. Since gh auth status often writes its status to stderr even with exit code 0, this function can return undefined even when logged in, weakening auth-drift detection and PID info. Consider using spawnSync (so you can inspect both stdout and stderr on success) or a gh api user -q .login style query.

[bradygaster]

once copilot's suggestions [that you agree with] are done i'm good here. thanks!

[bradygaster]

i think we should make sure to differentiate between the cleanup and nap commands but, maybe i just need to RTFM. :)