[guide] docs: troubleshooting.md — card-first diagnosis for agents that won't run (#5594 blockers line, never-scheduled chip, start & resume)

[kubestellar-hive]

Documentation Fix

Documents the v4.1.0 agent-card run-blocker diagnostics (#5594) in src/docs/troubleshooting.md § "Agents are stuck, paused, or need CLI login", which previously routed operators straight to tmux and described recovery as a two-step resume-then-restart — exactly the serial treasure hunt the card work eliminated.

Files/cluster claimed: src/docs/troubleshooting.md only. Disjoint from every open hold-gated PR (#5628 claims CHANGELOG.md + security-model.md; #5635 docs/rfc-4002; #5559 UPGRADE.md; the rest are code/test PRs).

What the new "Start on the agent card, not in tmux" subsection covers:

• the blockers line (session · scheduling · next kick): up/down/disabled session states, scheduling that joins every live reason ("paused + off in surge mode"), and next kick as an ETA or never;
• the ⏱ never scheduled — set cadences chip for the zero-cadence case, and that it shares its predicate with the fleet-level never-kicked banner;
• resume-leads and the combined ▶ start & resume button, including endpoint order (POST /api/resume/{agent} before POST /api/restart/{agent} so the fresh session is never born paused) and that it is client-side chaining of existing endpoints — no new API;
• the tmux path is kept under a new "Inspecting the session" subheading as the deeper-inspection escalation, and the paused-recovery step now points at the combined button.

Verified against the implementation at src/pkg/dashboard/static/index.html (agentBlockerLineHtml, agentToggleTitle, pausedAgentActionHtml, neverScheduledChipHtml, startResumeAgent).

Fixes #5639

— hive: agent=guide backend=copilot model=claude-sonnet-4-6

[clubanderson]

Verified every claim against the v4 dashboard code (src/pkg/dashboard/static/index.html) post-#5594/#5599/#5610:

• Blockers line: three segments (session / scheduling / next kick) rendered on both the agent card and the ops-center detail panel (agentBlockerLineHtml, .oc-detail-blockers) — matches.
• Session values up/down/disabled with the described restart-and-enable guidance — matches the tooltips verbatim.
• Scheduling: every live reason joined (paused + off in <mode> mode via agentSchedulingBlockers), on demand for on-demand agents — matches.
• Next kick: ETA form (in 12m; due now comes from formatETA in src/pkg/dashboard/next_kick_eta.go), never while any scheduling blocker exists — matches.
• Never-scheduled chip: exact text, opens the Cadences tab; the shared-predicate claim holds — the card's noCadence flag and the fleet-level hint are both driven by governor.NoCadenceAgents (src/pkg/config/expected_active.go is explicitly shared by both, #5577), so they cannot name different agents.
• Start & resume: startResumeAgent chains POST /api/resume first, then POST /api/restart, for exactly the stated reason (fresh session never born paused); no new API surface; pausedAgentActionHtml is the single render site, so a paused agent never shows a bare Start — all matches.
• Consistent with the just-merged src/docs/fleet-health.md (same never-kicked hint text and predicate); no contradictions found.

Verdict: OK to merge — accurate against the code.

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is APPROVED

Approval requirements bypassed by manually added approval.

This pull-request has been approved by:

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[github-actions]

Thank you for your contribution! Your PR has been merged.

Check out what's new:

• KubeStellar Console — Live multi-cluster dashboard
• Marketplace — Community extensions
• Knowledge Base — Troubleshooting and how-tos

Stay connected: Slack #kubestellar-dev | Multi-Cluster Survey