Documentation Gap
v4.1.0 and the current unreleased line shipped a coherent set of dashboard agent-card diagnostics for "my agent won't run" (#5594, PRs #5599, #5610, and the be52a38d / 361df1ab commits):
- a blockers line on every card and the ops-center detail panel (
session · scheduling · next kick) that names every live reason the governor will not kick the agent, reading raw server flags so a paused agent with a down session shows both;
- a
⏱ never scheduled — set cadences chip when no governor mode gives the agent a cadence (noCadence, sharing config.HasAnyCadenceIn with the fleet banner);
- resume-leads: a paused agent's primary action is always its pause toggle, with a tooltip that names what resuming will not clear;
- a combined
▶ start & resume button when the session is also down (chains POST /api/resume/{agent} then POST /api/restart/{agent}, resume first so the fresh session is never born paused);
- next-kick ETA (
in 12m, due now) instead of a wall-clock stamp; never when blockers exist.
None of this appears in any operator doc. The only prose is the CHANGELOG. In particular, src/docs/troubleshooting.md § "Agents are stuck, paused, or need CLI login" sends operators straight to tmux capture-pane and describes recovery as "Resume the agent from the dashboard, or POST /api/resume/{agent}" — exactly the serial treasure hunt #5594 eliminated. fleet-health.md tells operators to "set cadences on the agent card" without saying the card itself now names the zero-cadence state.
Recommendation
Add a card-first diagnosis subsection to troubleshooting.md § "Agents are stuck, paused, or need CLI login": read the blockers line first, what each segment means (including disabled/down session states, joined scheduling reasons, next kick: never), the never-scheduled chip, and when the card offers ▶ resume vs ▶ start & resume (and that the combined button is client-side chaining of the two existing endpoints — no new API). Keep the tmux path as the deeper-inspection escalation.
Disjoint from open PR #5628 (CHANGELOG.md, security-model.md) and every other open hold-gated PR — no open PR touches src/docs/troubleshooting.md.
Filed by guide agent (ACMM L5 — hold-gated mode)
🐝 Hive Agent: guide | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown
— hive: agent=guide backend=copilot model=claude-sonnet-4-6
Documentation Gap
v4.1.0 and the current unreleased line shipped a coherent set of dashboard agent-card diagnostics for "my agent won't run" (#5594, PRs #5599, #5610, and the
be52a38d/361df1abcommits):session · scheduling · next kick) that names every live reason the governor will not kick the agent, reading raw server flags so a paused agent with a down session shows both;⏱ never scheduled — set cadenceschip when no governor mode gives the agent a cadence (noCadence, sharingconfig.HasAnyCadenceInwith the fleet banner);▶ start & resumebutton when the session is also down (chainsPOST /api/resume/{agent}thenPOST /api/restart/{agent}, resume first so the fresh session is never born paused);in 12m,due now) instead of a wall-clock stamp;neverwhen blockers exist.None of this appears in any operator doc. The only prose is the CHANGELOG. In particular,
src/docs/troubleshooting.md§ "Agents are stuck, paused, or need CLI login" sends operators straight totmux capture-paneand describes recovery as "Resume the agent from the dashboard, orPOST /api/resume/{agent}" — exactly the serial treasure hunt #5594 eliminated.fleet-health.mdtells operators to "set cadences on the agent card" without saying the card itself now names the zero-cadence state.Recommendation
Add a card-first diagnosis subsection to
troubleshooting.md§ "Agents are stuck, paused, or need CLI login": read the blockers line first, what each segment means (includingdisabled/downsession states, joined scheduling reasons,next kick: never), the never-scheduled chip, and when the card offers▶ resumevs▶ start & resume(and that the combined button is client-side chaining of the two existing endpoints — no new API). Keep the tmux path as the deeper-inspection escalation.Disjoint from open PR #5628 (CHANGELOG.md, security-model.md) and every other open hold-gated PR — no open PR touches
src/docs/troubleshooting.md.Filed by guide agent (ACMM L5 — hold-gated mode)
🐝 Hive Agent:
guide| Instance:hosted-available-oke-11-placeholder-r05x| SHA:unknown— hive: agent=guide backend=copilot model=claude-sonnet-4-6