Show when a task is parked on a third party

[dkrattiger]

What

Adds Task.waiting_on — why a task is parked on someone who is neither you nor the agent — derived from the forge and rendered dim in the dashboard's turn cell.

Why

A task awaiting someone else's review sits at turn=user and renders yellow, indistinguishable from work that's actually yours. The only way to find out was to open it. On the live fleet: 32 of 36 tasks at turn=user, several parked on a reviewer.

Why not a third Actor

That was the obvious shape and it doesn't work:

• turn is machine-driven. The container's Stop hook sets it to user; its UserPromptSubmit hook sets it to agent. Every turn boundary rewrites it, so a third value survives until the agent does one more thing.
• Actor is load-bearing across turn_on_enter, advanced_by, and responsibility gating — 25 call sites. A third party has no meaning there: nothing external ever advances a task.

So this is a separate axis, which is what the turn can't carry.

Why derived, not declared

Nothing has to remember to set it, and — the part that matters — nothing has to remember to clear it. When the PR is approved or checks go green, the next pass reports None and the marker disappears. An agent skill that forgets to clear leaves a task looking parked forever, which is worse than no marker at all, because you learn to distrust it.

It's also distinct from blocked (the agent's own "I am stuck", cleared explicitly). Different lifecycles, so separate fields — and blocked still outranks this in the cell, since stuck needs attention while parked doesn't.

The derivation refuses to guess

PR state	Result	Why
Open, REVIEW_REQUIRED	external-review
Open, checks pending	ci	Review wins if both — it outlives a check run
Open, CHANGES_REQUESTED	none	The reviewer handed it back. That's work.
Open, check failed	none	Also work — only unfinished is a wait
Merged / closed	none	Self-clearing
Unreadable	unchanged	See below

That last row is the one that matters. gh absent, rate-limited, or unauthenticated leaves the previous value alone rather than reporting None — marking a parked task actionable because a shell command failed is exactly the error this feature exists to prevent.

Notes

• Throttled to one read per task per minute. The host wakes on the change feed, not a timer, so an unthrottled watcher would be one gh call per task per tick. Review state moves on human timescales.
• Skips paused tasks — no container, no triage value, no reason to spend the call.
• Unchanged values aren't re-posted, so it doesn't churn the change feed the dashboard long-polls.
• Migration is nullable, so no server_default needed (unlike the paused one).
• Unknown reasons render as their raw string rather than vanishing — a slightly ugly cell beats silently showing a parked task as actionable.

Tests

11 for the watcher (full derivation table, the three gates, the throttle, and the unreadable-PR case), 3 for the API (round-trip through the store, lifecycle untouched, unknown reason → 422), 3 for the rendering (dim beats the turn colour, blocked beats dim, unknown reason still dims).

Full suite passes (1,262). The two test_tarot_* failures are pre-existing — they assert tarot isn't installed, and it is on this machine.

🤖 Generated with Claude Code

[dkrattiger]

Correction pushed — the derivation was backwards for this repo's PRs

reviewDecision == "REVIEW_REQUIRED" is not evidence of an external wait. On a protected branch it means only that a review is required and none has been given. Every open task PR here reads exactly that way, with nobody requested:

#351    REVIEW_REQUIRED  author=dkrattiger  reviewRequests=[]
#10990  REVIEW_REQUIRED  author=dkrattiger  reviewRequests=[]
#10983  REVIEW_REQUIRED  author=dkrattiger  reviewRequests=[]
#10980  REVIEW_REQUIRED  author=dkrattiger  reviewRequests=[]

So the first cut would have labelled all four "ext review" and dimmed them — hiding exactly the work most in need of attention. Worse than no marker, since you'd learn to distrust the column.

The fix asks the narrower question: is a review pending from someone other than us? It reads reviewRequests and compares against the authenticated login (gh api user, resolved once and cached for the daemon's life). A requested team counts as external — we are never a team.

Where it can't tell, it errs toward "ours": an unresolvable identity, or a request naming only us, both fall through to no marker. Deliberate asymmetry — a wrong "external" hides work, a missing one costs a glance.

Verified against the live PRs — all four now derive to None:

PR #351    reviewRequests=[]   old → external-review   new → None
PR #10990  reviewRequests=[]   old → external-review   new → None
PR #10983  reviewRequests=[]   old → external-review   new → None
PR #10980  reviewRequests=[]   old → external-review   new → None

7 new tests cover the shapes: nobody requested, only-us requested, case-insensitive login, team requested, mixed including us, unresolvable identity, and that the identity lookup happens once. 18 watcher tests, 498 across everything the change touches.

🤖 Generated with Claude Code