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

.changeset/cleanup-ceremony.md

@@ -0,0 +1,12 @@
+---
+"@bradygaster/squad-cli": minor
+---
+
+Add cleanup watch capability for stale file housekeeping (#791)
+
+- New `cleanup` capability in the `housekeeping` phase
+- Clears `.squad/.scratch/` (all ephemeral temp files)
+- Archives orchestration-log and session-log entries older than 30 days
+- Warns about stale decision inbox files (>7 days)
+- Configurable: `everyNRounds` (default: 10), `maxAgeDays` (default: 30)
+- 12 new tests

.changeset/git-state-backends.md

@@ -0,0 +1,17 @@
+---
+"@bradygaster/squad-sdk": minor
+"@bradygaster/squad-cli": minor
+---
+
+feat(sdk): git-notes + orphan-branch state backends for .squad/
+
+Adds two git-native state storage backends as alternatives to the worktree
+and external directory approaches:
+
+- **git-notes** (`refs/notes/squad`): State stored in git notes ref. Survives
+  branch switches, invisible in diffs and PRs.
+- **orphan-branch** (`squad-state`): Dedicated orphan branch with no common
+  ancestor. State files never appear in main.
+
+Configure via `.squad/config.json`: `{ "stateBackend": "git-notes" }` or
+the `--state-backend` CLI flag.

.changeset/quiet-notifications.md

@@ -0,0 +1,13 @@
+---
+"@bradygaster/squad-cli": minor
+---
+
+Add `--notify-level` to control watch round reporting noise (#803)
+
+- `--notify-level important` (default): only print rounds with actual work items
+- `--notify-level all`: print every round including empty (old behavior)
+- `--notify-level none`: suppress all round output
+- Add machine name (`os.hostname()`) and repo name to round headers for attribution
+  (shown in round headers when the board has items, and in "Board is clear" message)
+- Configurable via `.squad/config.json` watch section: `"notifyLevel": "important"`
+- Empty rounds silenced by default — no more "Round 160, Round 161" spam

.changeset/watch-health.md

@@ -0,0 +1,10 @@
+---
+"@bradygaster/squad-cli": minor
+---
+
+feat(watch): health check — show running watch instance status (#808)
+
+Adds `squad watch --health` to display the status of a running watch
+instance: PID, uptime, auth account, capabilities, and auth drift
+detection. Writes `.squad/.watch-pid.json` at startup for instance
+tracking. Detects and cleans up stale PID files from crashed instances.

.gitignore

@@ -11,6 +11,7 @@ coverage/
 .squad/decisions/inbox/
 .squad/sessions/
 .squad/config.json
+
 # Test temp dirs (created in cwd by vitest tests, cleaned in afterEach)
 .test-*
 # Docs site generated files

README.md

@@ -99,7 +99,7 @@ Use `--force` to re-apply updates even when your installed version already match
 | `squad init` | **Init** — scaffold Squad in the current directory (idempotent — safe to run multiple times); alias: `hire`; use `--global` to init in personal squad directory, `--mode remote <path>` for dual-root mode |
 | `squad upgrade` | Update Squad-owned files to latest; never touches your team state; use `--global` to upgrade personal squad, `--migrate-directory` to rename `.ai-team/` → `.squad/` |
 | `squad status` | Show which squad is active and why |
-| `squad triage` | Watch issues and auto-triage to team (aliases: `watch`, `loop`); use `--interval <minutes>` to set polling frequency (default: 10) |
+| `squad triage` | **Watch mode** — poll for issues and auto-triage to team (aliases: `watch`, `loop`); use `--interval <minutes>` to set polling frequency (default: 10); with `--execute` dispatch Copilot agents; use `--agent-cmd`, `--copilot-flags`, `--auth-user` to customize agent execution; `--health` shows watch status; `--log-file` for diagnostics |
 | `squad copilot` | Add/remove the Copilot coding agent (@copilot); use `--off` to remove, `--auto-assign` to enable auto-assignment |
 | `squad doctor` | Check your setup and diagnose issues (alias: `heartbeat`) |
 | `squad link <team-repo-path>` | Connect to a remote team |
@@ -114,6 +114,158 @@ Use `--force` to re-apply updates even when your installed version already match
 
 ---
 
+## Watch Mode — Ralph's Autonomous Polling
+
+Ralph continuously polls for work and dispatches agents to handle it. Watch mode is perfect for unmanned squad operations — let agents work while you're away.
+
+### Quick Start
+
+```bash
+# Monitor for issues (triage mode — no execution)
+npx @bradygaster/squad-cli watch
+
+# Monitor and auto-execute against actionable issues
+npx @bradygaster/squad-cli watch --execute --interval 5
+
+# With custom agent runner and copilot flags
+npx @bradygaster/squad-cli watch --execute \
+  --agent-cmd "agency copilot" \
+  --copilot-flags "--yolo --autopilot --mcp mail --agent squad" \
+  --auth-user myaccount
+
+# Run watch with diagnostics
+npx @bradygaster/squad-cli watch --execute --log-file ./watch.log --verbose
+
+# Check health of running watch process
+npx @bradygaster/squad-cli watch --health
+```
+
+### Key Flags
+
+| Flag | Description |
+|------|-------------|
+| `--execute` | Enable agent execution (spawn Copilot sessions for actionable issues) |
+| `--interval N` | Poll every N minutes (default: 10) |
+| `--agent-cmd` | Custom agent command (default: `gh copilot`) |
+| `--copilot-flags` | Flags passed to the agent runner (e.g., `--yolo --autopilot`) |
+| `--auth-user` | GitHub/Azure DevOps account to use for agent auth |
+| `--log-file` | Mirror output to file for later review and diagnostics |
+| `--verbose` | Show extra diagnostic output (auth probes, callbacks, pulls) |
+| `--health` | Show status of running watch: PID, uptime, auth readiness, capabilities |
+| `--overnight-start HH:MM` | Pause watch during off-hours (e.g., `--overnight-start 18:00`) |
+| `--overnight-end HH:MM` | Resume watch at this time (e.g., `--overnight-end 08:00`) |
+| `--notify-level` | Control output verbosity (`all` / `important` / `none`, default: `important`) |
+| `--state-backend` | Persistence strategy (`git-notes` or `orphan-branch`, default: in-memory) |
+
+### How Watch Decides What to Execute
+
+Ralph uses an **agent-delegated selection pattern**:
+
+1. Ralph scans for triage-eligible issues (unassigned, labeled, etc.)
+2. Ralph builds a context snapshot: issue list, squad state, recent decisions
+3. Ralph writes this context to a **temp file** using the `-p <path>` flag
+4. Ralph invokes the agent with that file: `gh copilot -p context.md`
+5. The agent **decides which issue to work on** and **how**
+6. Ralph monitors execution, logs results, updates issue status
+
+This design gives **agents full autonomy** over issue selection while keeping the polling loop lean.
+
+### Issue Selection & Escalation
+
+Ralph provides a rich prompt scaffold to the agent:
+
+```
+## Work Context
+
+### Available Issues (prioritized)
+- #42 Urgent bug in auth (P0)
+- #89 Performance review pending (P1)
+- #123 Docs update (P2)
+
+### Why These Issues Matter
+...context from decision archive...
+
+### Success Criteria
+- Tests pass
+- Changes match team conventions
+- PR linked to issue
+
+### When to Escalate
+If blocker detected → pause, log, notify humans
+```
+
+Agents see **full context** and can decide intelligently rather than blindly executing random work.
+
+### Error Recovery (4-Tier Escalation)
+
+Watch includes a tiered remediation strategy:
+
+1. **Tier 1 — Circuit Breaker Reset**: Clear and retry
+2. **Tier 2 — Auth Reprobe**: Re-verify credentials
+3. **Tier 3 — Git Pull**: Update local state
+4. **Tier 4 — Pause 30m**: Back off for human intervention
+
+This prevents watch from spamming the same failure endlessly.
+
+### State Backends
+
+Watch can persist its state in different ways:
+
+```bash
+# Default: in-memory (loses state on restart)
+squad watch --execute
+
+# Persist to git-notes (survives restarts, no new branches)
+squad watch --execute --state-backend git-notes
+
+# Persist to orphan branch (isolated history, easy to prune)
+squad watch --execute --state-backend orphan-branch
+```
+
+### Graceful Shutdown
+
+To stop a running watch process gracefully:
+
+```bash
+# Create sentinel file
+touch .squad/ralph-stop
+
+# Watch will finish current round and exit cleanly
+# Logs final state, cleans scratch dirs
+```
+
+### Cleanup
+
+Watch automatically prunes stale artifacts:
+- Scratch directories older than 7 days
+- Log files older than 30 days
+- Orphaned orchestration state
+
+### Monitoring Watch
+
+Check on a running watch:
+
+```bash
+squad watch --health
+```
+
+Output example:
+```
+Ralph Watch Status
+
+PID: 12345
+Uptime: 2h 15m
+Last Poll: 2 minutes ago
+
+Auth: Ready (account: myaccount@github.com)
+Capabilities: Issue triage, PR review, ADO sync
+
+Next Poll: 14:35 (in 3 minutes)
+Round: 42 / 1200
+```
+
+---
+
 ## Interactive Shell
 
 Tired of typing `squad` followed by a command every time? Enter the interactive shell.

cspell.json

@@ -36,7 +36,8 @@
     "Pydantic", "sdkgen", "ttft", "Strausz", "mycompany",
     "slugified", "simplejwt", "pytest", "Luca", "Clemenza",
     "Tessio", "Triaging", "Futurama", "mklink", "slnx", "jqlang",
-    "benleane", "TELMU", "Automator", "kedacore"
+    "benleane", "TELMU", "Automator", "kedacore",
+    "DEVBOX", "myaccount"
   ],
   "dictionaries": ["en_US", "typescript", "node", "npm", "bash"],
   "allowCompoundWords": true