[martin-conur]

Summary

This adds task-monitor, a live terminal board built in Rust with ratatui. For the repo you're in it shows what is in flight, what is next and what has landed, and an overview shows which repo needs you and why. It refreshes from disk the moment radio or a worker changes something, asks GitHub every 45 seconds, and keeps the last good screen up, marked stale, when a refresh fails.

Closes #276

What

• monitor/: a new crate that builds the task-monitor binary. It reads task-monitor-snapshot --json --all [--local] and nothing else. Every field is optional, unknown fields are ignored, and a different schema is refused.

• Screens: the repo view (in flight with status, PR, activity icon and age, reviewers; next, from the queue or the backlog, with notes; done with PR, SHA, age and a two-line summary) and the overview (attention light, signal text, in-flight count, zellij session). ⏎ expands an item in place, with a done item showing its full PR body, scrollable.

• Refresh: filesystem events (notify) on $TASK_FORCE_HOME/radio (excluding log), $TASK_FORCE_HOME/monitor and each worktree base (.<slug>.info only) run a --local snapshot. Events are debounced 400ms on the trailing edge and capped at 2s, and only one local run goes at a time, with a rerun if an event lands mid-run. The full run starts at launch and then 45s after the previous one finished (--poll 30-600). Timeouts are 20s for a local run and 180s for a full one, and a hung collector is killed. A result never replaces a newer run's.

• t: uses the sidecar TAB_ID, else the session's, or the PM's for queue/done items and overview rows. It refuses a tab in another zellij session by naming it. Otherwise it checks with list-tabs that the tab at that id still bears the item's name (the aw_tab_name_is_slug rule from task-done closes a stale TAB_ID without checking the tab is its own, killing an unrelated worker after a zellij restart #260) before go-to-tab-by-id.

• Snapshot: one new field, worktree_base, so the watcher doesn't re-derive task-work's path rule. It is in the schema doc and example, with a bats test.

• Docs: a README section, a task-monitor paragraph in .claude/gh-workflow.md and the seven steering templates, and a CHANGELOG entry.

• CI (the PM moved this here from task-monitor 5/6: install.sh cargo build + CI Rust job #277): a rust job on ubuntu-latest and macos-latest runs from monitor/ on stable: cargo fmt --check, cargo build --locked, cargo test --locked, cargo clippy --all-targets --locked -- -D warnings, with Swatinem/rust-cache (keyed on monitor/Cargo.lock). A rust-msrv job builds and tests on 1.88, the rust-version in Cargo.toml and ratatui 0.30's floor. I checked that pin locally with cargo +1.88 test --locked (45/45).

Branch protection: main requires four checks by name: ShellCheck, Bats tests (ubuntu-latest), Bats tests (macos-latest) and Loadout drift check. The new Rust (ubuntu-latest), Rust (macos-latest) and Rust MSRV (1.88) checks are not required. Add them in the branch settings if they should gate merges. I did not change protection.

install.sh stays with #277, and the queue is read only through the snapshot (#275 owns task-monitor-queue).

Verification

• cargo test: 45 pass, cargo clippy --all-targets: clean. I broke eight targets on purpose (tab-name rule, session check, run ordering, local-run coalescing, log filter, narrow fit, error reset, timeout kill), plus the symlink canonicalization, and each turned a test red.
• PTY end to end with a fake collector under a scratch TASK_FORCE_HOME: it renders, a session-file write and a new sidecar each trigger a --local run, a radio/log append does not, and q exits 0.
• I also rendered a real --all snapshot from this machine (4 repos) on a TestBackend to check the layout.
• ./run_tests.sh: 1436/1436. tools/check-drift.sh: clean. shellcheck -x bin/task-monitor-snapshot: clean. CI runs the Rust tests as of the second commit.

🤖 Generated with Claude Code

[martin-conur]

Spec compliance (#276)

Every scope bullet is delivered:

• Screens: the repo view (In flight / Next / Done) and the all-repos overview. The overview shows the attention light, the signal in words and the zellij session.
• Keys: ↑↓, ⏎ (in-place expand, scrollable full PR body for done items), o, t, a, q.
• t: it is limited to the monitor's own zellij session and names a target in another session instead of attempting it. It checks the tab at the recorded id against the item's name before go-to-tab-by-id, matching aw_tab_name_is_slug from task-done closes a stale TAB_ID without checking the tab is its own, killing an unrelated worker after a zellij restart #260.
• Real-time: notify watches radio (excluding log), monitor and each worktree base (.<slug>.info only). Events are debounced 400ms with a 2s cap, and only one local run goes at a time. The forge run is on a 45s timer (--poll 30-600).
• Never blank: the last good snapshot stays up with a stale marker.
• Rust tests: rendering from fixtures on a TestBackend, key handling, scheduler timing, the watcher filter and the fake-zellij tab checks.
• No task-force logic in Rust: the one addition is worktree_base in the snapshot. It is documented in the schema and the example, and it is the right way to avoid re-deriving task-work's path rule in Rust.

The PR body opens with ## Summary. CI ran for the head SHA and passed (bats on macOS and Ubuntu, drift check, ShellCheck). I also ran cargo test locally: 45 passed. check-drift is clean.

Code-review findings

No blockers. Two points are worth fixing in this PR; both are small.

1. A full run's result is dropped whenever a local run started after it lands first (App::offer, monitor/src/app.rs; the local-run trigger is in Scheduler::due, monitor/src/refresh.rs).

   • A full run can take up to 180s. The radio dir sees constant writes (session heartbeats), so a local run will almost always start and finish during a slow full run.
   • Because the full run started earlier, offer rejects it. It is dropped silently: no error is cleared, and freshness is not updated.
   • The data is not lost, since the collector's full-run cache is picked up by the next local run (the monitor/ dir is watched). But the screen can show pre-full-run forge state for one extra cycle, and the "forge " marker lags.
   • Fix: let a full result replace a local one even when it started earlier. This is safe because the full result is a superset (it includes the forge data and disk state read at its start). Or at minimum, when a full result is rejected, trigger a local rerun immediately so the cache lands. Add a test for "local lands during full".

2. A stale failure from an older run can mark a fresh screen stale (App::failed).

   • failed sets freshness.error unconditionally. If a full run times out at 180s after a newer local run succeeded, the screen is marked stale and shows the error until the next success, even though the data on screen is current.
   • Fix: give failed the run's start time and ignore it when snapshot_started is later, mirroring offer.

Nits (non-blocking)

• to_key maps Ctrl-C to Quit, which is good. The Quit arm in App::key could also be tested at the main/to_key level, but it is fine as is.
• The Rust tests are not in CI yet; the PR says this is task-monitor 5/6: install.sh cargo build + CI Rust job #277, which is fine since task-monitor 5/6: install.sh cargo build + CI Rust job #277 is a separate ticket.

Verdict

clean-with-nits. I would fix findings 1 and 2 in this PR, since they are small and in code the PR already owns. PM decides; neither blocks the merge.