feat: controller-level stuck-agent sweep (#571)

[rileywhite]

Summary

Adds a fifth health-patrol tracker — stuckTracker — to the controller reconciler. It detects sessions whose terminal output (SHA-256 hash of Peek output) has not changed for longer than a configurable stuck_timeout, kills them, and marks them for immediate re-wake. A built-in circuit breaker quarantines sessions that repeatedly get stuck.

Key changes

• Core tracker (cmd/gc/stuck_tracker.go): stuckTracker interface + memoryStuckTracker with doCheckStuck pure function, grace period, and own circuit breaker (quarantine after 3 kills in 2 * timeout window)
• Reconciler integration (cmd/gc/session_reconciler.go): Stuck check after idle check with drain-in-progress guard and CanPeek gating
• Config (internal/config/config.go): stuck_timeout field on DaemonConfig with duration accessor and validation
• Runtime (internal/runtime/probe.go): CanPeek capability flag (true for tmux/k8s/fake, false for subprocess/exec/acp)
• Wake bypass (cmd/gc/session_sleep.go): configWakeSuppressed exception for stuck-timeout (matches idle-timeout behavior)
• Telemetry (internal/telemetry/recorder.go): RecordAgentStuckKill counter + log event
• Dashboard (cmd/gc/dashboard/helpers.go): 🧊 ice icon, category, summary for session.stuck_killed
• Doctor (internal/doctor/checks_semantic.go): Informational daemon-stuck-timeout check
• Docs: Updated event-bus.md (full table replacement with correct session.* names), health-patrol.md (fifth tracker), controller.md, primitive-test.md (ZFC clarification)

Design decisions

• Hash comparison is transport, not cognition (ZFC clean): The controller observes that output has not changed; it does not classify or interpret content
• Opt-in, city-wide: stuck_timeout disabled by default. Set to accommodate the slowest-running agent
• resetDetection vs clearSession: After a stuck-kill, detection state resets but kill history is preserved for the circuit breaker

What was tested

• make fmt-check — pass
• make lint — 0 issues
• make vet — pass
• 19 targeted tests pass (stuck_tracker_test.go + session_reconciler_test.go stuck integration tests)

Review outcome

Five parallel reviews (adversarial, what-about, UAT, docs, alignment) + neutral judge.

Critical finding (fixed): clearSession wiped kill history after every stuck-kill, making the circuit breaker unreachable in production. Fixed by adding resetDetection() that preserves kills while resetting detection state.

Judge verdict: CLEARED. The implementation matches the design brief, adversarial findings were handled appropriately, and the change is aligned with Gas City's principles (ZFC, Bitter Lesson, Primitive Test all pass).

Review Story

The stuck-agent sweep adds the third leg of the controller's health triad (crash, idle, stuck). The design brief laid out a clear architecture; the implementation followed it faithfully. Five independent reviews converged on one critical bug — the circuit breaker was unreachable because clearSession wiped the kill history it depended on — and the fix was structurally correct. Secondary findings (CanPeek granularity, test coverage gaps, cosmetic truncation) are real but non-blocking. The implementation is aligned with Gas City's core principles: hash comparison is pure transport observation (ZFC clean), stuck detection remains necessary regardless of model capability (Bitter Lesson pass), and no role names appear in the code (zero hardcoded roles).

Residual risks (non-blocking)

1. CanPeek granularity: Provider-level, not per-session. Hybrid/auto with ACP backend could theoretically false-positive. Mitigated by empty-output guard and idle-fires-first ordering.
2. City-wide timeout: No per-agent override yet. Documented limitation.

Closes #571

[rileywhite]

FYI: I'm running a parallel implementation with a different formula as a comparison test. I expect the older formula's PR (this one) to be closed on delivery. I plan to compare the results.

I'm going to go ahead and open it for review. It's a significant change, though, and my formula allowed for context compactions during dev that may have affected quality. If you pick this up for review, then please keep that in mind. This may just be too much for one go, and while #571 did get labeling indicating it's available for work, I did move forward before getting a clear signal that the direction is architecturally aligned, especially with respect to ZFC. (Though I did find the argument compelling.)

[rileywhite]

Review Fix: Grace Period After Stuck-Kill Reset

Adversarial review discovered a critical bug: resetDetection zeroed firstSeen, causing doCheckStuck to bypass the grace period after a stuck-kill restart. A restarted session could be re-killed after just one stuck_timeout duration instead of the intended grace + timeout window.

Fix (commit 2045361):

• doCheckStuck now re-initializes zero firstSeen to now, giving restarted sessions a real grace period
• Added TestStuckTracker_ResetDetection_GracePeriod proving the fix
• Fixed controller.md: tracker rebuild doc was inaccurate about stuck tracker's state-preserving behavior

Quality gates: make fmt-check, make vet, make lint — all pass, 0 issues.

Review summary:

• Adversarial: 1 Critical (fixed), 4 Important (1 fixed doc, others assessed as acceptable)
• UAT: PASS — all user-facing surfaces coherent
• Docs: FINDINGS — minor gaps (telemetry counter, CanPeek capability not documented in engdocs)
• GC Alignment: ALIGNED — passes ZFC, Bitter Lesson, Primitive Test, all product alignment checks
• What-About: FINDINGS — 4 concerns, 1 fixed (grace period), others assessed as acceptable