fix: restore grace period after stuck-kill resetDetection (#571)

resetDetection zeroed firstSeen, causing doCheckStuck to skip the
grace period (now.Sub(time.Time{}) is always huge). Restarted sessions
could be re-killed after just one timeout instead of the intended
grace + timeout window.

Fix: doCheckStuck re-initializes zero firstSeen to now, giving the
restarted session a real grace period. Add test proving the grace
period holds after reset.

Also fix controller.md: tracker rebuild doc was inaccurate — the stuck
tracker preserves state when its timeout is unchanged, unlike other
trackers that rebuild unconditionally.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rileywhite

cmd/gc/stuck_tracker.go

@@ -160,6 +160,13 @@ func (m *memoryStuckTracker) resetDetection(sessionName string) {
 // This function is independently testable without any Provider mock.
 func doCheckStuck(entry stuckEntry, output string, now time.Time, timeout time.Duration) (stuck bool, updated stuckEntry) {
 	updated = entry
+
+	// After resetDetection, firstSeen is zero — re-initialize so the
+	// restarted session gets a real grace period from this tick.
+	if updated.firstSeen.IsZero() {
+		updated.firstSeen = now
+	}
+
 	h := sha256.Sum256([]byte(output))
 
 	if h != entry.hash {

cmd/gc/stuck_tracker_test.go

@@ -125,6 +125,33 @@ func TestStuckTracker_ResetDetection_PreservesKills(t *testing.T) {
 	}
 }
 
+func TestStuckTracker_ResetDetection_GracePeriod(t *testing.T) {
+	st := newStuckTracker(5 * time.Minute)
+	now := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)
+
+	// Establish session.
+	st.checkStuck("sess1", "frozen", now)
+
+	// Simulate stuck-kill: reset detection state.
+	st.resetDetection("sess1")
+
+	// After reset, first observation with new output — hash change, not stuck.
+	restartTime := now.Add(1 * time.Hour)
+	if st.checkStuck("sess1", "new output", restartTime) {
+		t.Fatal("expected false on first observation after reset")
+	}
+
+	// Same output within grace period (timeout/2 < timeout) — must NOT fire.
+	if st.checkStuck("sess1", "new output", restartTime.Add(3*time.Minute)) {
+		t.Fatal("expected false: should be within grace period after reset")
+	}
+
+	// Same output past grace period AND past timeout — should fire.
+	if !st.checkStuck("sess1", "new output", restartTime.Add(11*time.Minute)) {
+		t.Fatal("expected true: past grace period and timeout after reset")
+	}
+}
+
 func TestStuckTracker_MultipleSessionsIndependent(t *testing.T) {
 	st := newStuckTracker(5 * time.Minute)
 	now := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)

engdocs/architecture/controller.md

@@ -164,9 +164,11 @@ indicate bugs.
   startup; changing it requires a controller restart.
 
 - **Tracker rebuild is atomic per tick**: When config reloads, all five
-  trackers (crash, idle, stuck, wisp GC, order) are rebuilt in the same
-  tick before reconciliation runs. No tick ever uses a mix of old and new
-  tracker state.
+  trackers (crash, idle, stuck, wisp GC, order) are updated in the same
+  tick before reconciliation runs. Most trackers are rebuilt unconditionally;
+  the stuck tracker preserves accumulated state when its timeout value is
+  unchanged (only rebuilt when `stuck_timeout` changes or is removed).
+  No tick ever uses a mix of old and new tracker config.
 
 - **Dirty flag is edge-triggered, not level-triggered**: The `atomic.Bool`
   is set by the fsnotify goroutine and cleared by `dirty.Swap(false)` at