feat(overseer): top-down loop-runner / overseer agent

[TraderSamwise]

What

Adds an optional overseer agent per project — the first entrypoint for human-initiated, top-down, cross-worktree orchestration. Its day-1 use case is loop-running: keep designated agents working until they hard-signal done or blocked beyond repair, instead of giving back their turn early (a frequent Claude Code failure mode). It's built generic so the same agent can also answer "what is everyone working on?" and direct agents across worktrees.

Built entirely on existing primitives (tasks/threads/spawn//agents/input//agents/output/topology). No new orchestration primitives.

Design

• Daemon = heartbeat + detector (deterministic, zero tokens). A LoopWatcher runs beside PluginRuntime in the project-service host, scanning on an interval for in-loop agents that stopped (activity idle/done, attention normal, not waiting on a human).
• Overseer = reactive brain (LLM, on-demand). The watcher only wakes the overseer when there's an actual candidate — cheaper than a self-looping LLM, agent-agnostic (wakes via tmux input), and robust (the heartbeat doesn't depend on the overseer staying awake).
• Without an overseer, the daemon stays observe-only unless loop.autoNudgeWithoutOverseer is enabled (default off).

Phases (one commit each)

1. Metadata flags + observe/act CLI — overseer/loop fields on SessionMetadata; GET /agents snapshot + POST /agents/loop; aimux input, aimux ps, aimux loop add/remove.
2. Daemon loop watcher — pure findLoopCandidates + LoopWatcher; LoopConfig (15s/60s/off); listPendingInteractions so we never steamroll an agent waiting on a human.
3. Overseer role + preamble — buildOverseerPreamble, sticky system prompt gated on team.role === "overseer"; aimux overseer start/clear.
4. Agent self-exit — aimux loop done / aimux loop block (resolve own $AIMUX_SESSION_ID, clear the loop, emit a task_done/blocked status).

Closing the loop

human aimux loop add → watcher detects a premature stop → overseer reads output and aimux inputs a continue (or releases) → agent aimux loop done/block when genuinely finished/blocked.

Verification

yarn typecheck, yarn lint, yarn build, and the full yarn vitest suite (1111 tests) pass. New unit tests cover the candidate truth table, overseer-wake vs canned-nudge dispatch + cooldowns, the overseer-present-but-offline fallthrough, metadata round-trips, the GET /agents/POST /agents/loop routes, overseer-preamble injection, and the self-exit nudge wording. CLI registration smoke-tested via --help.

A full live-agent end-to-end (spawn real agents, watch a nudge fire) was not run headless in this environment.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
app	Ready	Preview, Comment	Jun 13, 2026 2:48pm

[coderabbitai]

Warning

Review limit reached

@TraderSamwise, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 2 hours, 16 minutes, and 4 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0283c9dc-1e63-4257-9312-4ead477ad547

📥 Commits

Reviewing files that changed from the base of the PR and between 18b5b90 and 38842a6.

📒 Files selected for processing (13)

• src/config.ts
• src/loop-watcher.test.ts
• src/loop-watcher.ts
• src/main.ts
• src/metadata-server.test.ts
• src/metadata-server.ts
• src/metadata-store.test.ts
• src/metadata-store.ts
• src/multiplexer/dashboard-model.ts
• src/multiplexer/dashboard-tail-methods.ts
• src/session-bootstrap.test.ts
• src/session-bootstrap.ts
• src/team.ts

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent-loop-watcher

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[TraderSamwise]

Sub-agent review (round 1) — dispositions

CodeRabbit is rate-limited on this account (≈2h), so an independent sub-agent reviewed the diff. Findings and resolutions:

#	Sev	Finding	Resolution
1	med	LoopWatcher set the nudge/briefing cooldown before the send succeeded, so a failed delivery silenced the target for a full cooldown	Fixed (38842a6) — cooldown only starts after a successful send; failures retry next scan
2	med	POST /agents/loop cleared the loop flag when active was omitted	Fixed (38842a6) — active must be an explicit boolean, else 400
3	med	Self-exit (loop done/block) did two POSTs; a failed 2nd left no status	Fixed (38842a6) — clear the loop first (watcher stops nudging regardless), then emit the event best-effort. Reversing the order would be worse: a failed event would leave a finished agent still being nudged
4	low	overseer metadata flag isn't cleared when the session stops	By design — stop ≠ demote (a revived overseer keeps its role); graveyard is excluded from aimux ps; the watcher only acts on a running overseer. aimux overseer clear demotes explicitly
5	low	An overseer in starting status wasn't discovered by the watcher	Fixed (38842a6) — scan now includes starting
6	—	Two-hop spawn routing for the overseer flag	Non-issue (confirmed correct)

New tests: omitted-active ⇒ 400; a failed nudge does not consume the cooldown.