cc-viewer 1.9.17 → 1.9.19

package/server/lib/sdk-manager.js

@@ -162,12 +162,39 @@ export function listSdkSessions() {
 
 registerSdkSessionLister(listSdkSessions);
 
-// Silence window for the watchdog. Must stay above the approval ceilings the turn can
-// legally wait on: perm/plan = 5min, AskUserQuestion = 24h ("GUI effectively has no
-// timeout" is a product contract). A pending approval exempts the turn from the
-// watchdog entirely; 25min covers long tool runs (big builds) with headroom.
-const TURN_WATCHDOG_MS = 25 * 60 * 1000;
+// The turn can legally wait on approval ceilings: perm/plan = 5min, AskUserQuestion =
+// 24h ("GUI effectively has no timeout" is a product contract). A pending approval
+// exempts the turn from probing entirely (the child is parked awaiting our response).
 const INTERRUPT_GRACE_MS = 10 * 1000;
+// Activity-probe tuning: how long a turn may produce NOTHING before we start pinging
+// the child's control plane, how often we re-ping, and how many consecutive unanswered
+// probes convict the child as wedged. A legal long turn (multi-hour tool, user away) is
+// silent yet answers probes, so it is never convicted on silence alone. The probe must
+// be a REAL control round-trip (getContextUsage — supportedCommands/initializationResult
+// are cached init promises in the SDK and resolve even against a wedged event loop).
+const ACTIVITY_PROBE_IDLE_MS = 10 * 60 * 1000;
+const ACTIVITY_PROBE_INTERVAL_MS = 3 * 60 * 1000;
+const ACTIVITY_PROBE_MAX_FAILURES = 2;
+// HTTP statuses the CLI/ccv treat as retryable API errors (drives the manual [retry]
+// affordance). error_status === null (a network error with no HTTP response) is also
+// retryable; auth (401/403) and billing failures are not — retrying them is pointless.
+const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504, 529]);
+// Synthetic continue instruction pushed by the manual [retry] affordance. Marked with a
+// sentinel the web UI hides from the chat bubble (the model still reads the instruction).
+// It does NOT resend the user's original message — that is already in the history.
+const RETRY_CONTINUE_PROMPT =
+  '[cc-viewer:retry] The previous response was interrupted by an API error. ' +
+  'Continue the same task from where it stopped. Do not repeat completed work; ' +
+  'finish the remaining steps and reply concisely.';
+// How often to re-broadcast sdk-session-state while a turn is active (keeps the client's
+// Stop button/spinner alive past its 30s stale sweep and re-seeds it after a view switch).
+const STATE_HEARTBEAT_MS = 10 * 1000;
+// Message-level activity coalescing: every non-boundary SDK message (assistant/user/
+// tool_progress/system task_*/status/api_retry/compact) refreshes turn liveness, but
+// rebroadcasting per message would flood the terminal WS on busy turns. Activity frames
+// reuse the sdk-session-state shape (heartbeat+activity flags) so clients need no new
+// handler, and are capped at one per ACTIVITY_MIN_INTERVAL_MS per turn.
+const ACTIVITY_MIN_INTERVAL_MS = 1000;
 // getContextUsage control requests have no SDK-side timeout — bound the wait so a live-but-
 // unresponsive child can't wedge the in-flight gate forever.
 const CTX_USAGE_TIMEOUT_MS = 10 * 1000;
@@ -184,6 +211,35 @@ let _onTurnEnd = null; // SDK mode has no Stop hook (ensureHooks() skipped) —
 let _onQueryError = null; // query-level failure → (message: string, meta: {cwd, sessionId, instanceKey}) => void; cli.js forwards it as a scoped sdk-error WS frame (dialogue row + toast)
 let _broadcastWs = null;
 let _runWaterfallHook = null;
+// Authoritative per-turn loop boundaries (voice/plugin/SSE agent_loop_*). Unlike the
+// debounced turn_end, these fire exactly once per accepted turn at push time (start) and
+// at the turn's real settlement (end) — see _emitAgentLoopStart/_emitAgentLoopEnd.
+let _onAgentLoopStart = null;
+let _onAgentLoopEnd = null;
+// Durable process-level wiring registered ONCE by cli.js. Unlike the mutable callbacks
+// above (which stopSession clears), this survives a workspace stop→relaunch so a launch
+// route that omits the callbacks still restores them (see _adoptProcessWiring). Tests
+// never register it, so stopSession's "clear the wiring" contract for tests is unchanged.
+let _processWiring = null;
+export function setSdkProcessWiring(w) {
+  _processWiring = (w == null) ? null : {
+    onTurnEnd: w.onTurnEnd || null,
+    onQueryError: w.onQueryError || null,
+    broadcastWs: w.broadcastWs || null,
+    runWaterfallHook: w.runWaterfallHook || null,
+    onAgentLoopStart: w.onAgentLoopStart || null,
+    onAgentLoopEnd: w.onAgentLoopEnd || null,
+  };
+}
+function _adoptProcessWiring() {
+  if (!_processWiring) return;
+  if (!_onTurnEnd) _onTurnEnd = _processWiring.onTurnEnd;
+  if (!_onQueryError) _onQueryError = _processWiring.onQueryError;
+  if (!_broadcastWs) _broadcastWs = _processWiring.broadcastWs;
+  if (!_runWaterfallHook) _runWaterfallHook = _processWiring.runWaterfallHook;
+  if (!_onAgentLoopStart) _onAgentLoopStart = _processWiring.onAgentLoopStart;
+  if (!_onAgentLoopEnd) _onAgentLoopEnd = _processWiring.onAgentLoopEnd;
+}
 
 // Process-level SDK LAUNCH-CONFIG template (2026-10-12). cli.js registers it once at boot
 // (the env carries the loopback-proxy URL + the per-cwd header is added per session). The
@@ -360,10 +416,41 @@ function _createSession(key, cwd) {
                              // CLI-side turn may still be running; without the sticky flag a
                              // second Stop would silently no-op).
   let _settleGraceTimer = null; // backstop after interrupt: force-settle if no result arrives
-  let _lateResultTombstones = 0; // results to discard (already force-settled via grace/watchdog)
+  let _lostResultTimer = null;  // lost-result backstop handle (cleared on turn settle/teardown)
+  // Generation guard for late results (replaces the old _lateResultTombstones counter).
+  // Result frames carry no turn id, so a force-settled turn's late result is
+  // indistinguishable from the NEXT turn's result on arrival order alone. The counter
+  // solved this by counting "results still owed", but it only reset on teardown/reset —
+  // so when the owed result NEVER arrived (the lost-result case), the count outlived its
+  // turn and swallowed the NEXT turn's result (no shift, no turn_end → that turn then
+  // force-settled as turn-stuck too). The guard instead binds the debt to the force-settled
+  // turn's epoch: a result is discarded only while it provably belongs to the dead
+  // generation. Once a NEWER turn is in flight, its own result pairs normally — the stale
+  // debt is dropped (the old result may never come, and must not tax the live turn).
+  let _turnEpoch = 0;        // advanced per _beginTurn; rec.epoch snapshots it
+  let _lateResultEpoch = 0;  // epoch of the force-settled turn awaiting a late result (0 = none)
   let _consecutiveDeaths = 0;   // backstop against respawn storms in a broken environment
-  let _turnWatchdog = null; // SILENCE watchdog: re-armed on every incoming message; fires only
-                            // when the session produces nothing for the whole window
+  // Activity probe (replaces the old fixed 25min silence watchdog): re-armed on every
+  // incoming SDK message. When a turn stays silent past ACTIVITY_PROBE_IDLE_MS it pings
+  // the CLI's control plane (getContextUsage — a REAL round-trip; the init-cached
+  // supportedCommands/initializationResult would resolve even against a wedged child).
+  // Only consecutive unanswered probes mean the child is genuinely wedged (a legal
+  // multi-hour tool turn keeps its event loop responsive and answers). This never kills
+  // a long turn for being merely quiet.
+  let _activityProbe = null;
+  let _probeFailures = 0;
+  let _probeEpoch = 0; // bumped on any message/interrupt → invalidates an in-flight probe
+  // Monotonic inbound-message counter, bumped ONCE per received SDK message (not by
+  // watchdog arms/clears like _probeEpoch). The lost-result backstop snapshots it at
+  // arm time: any message arriving afterwards proves the head turn is producing work,
+  // so a mis-armed conviction (uncorrelatable-idle hazard) disarms instead of firing.
+  let _inboundMsgSeq = 0;
+  // Suspect generation: set when an interrupt grace expires with no result (the CLI never
+  // answered our Stop) or a probe convicts the child. The wedged query is torn down LAZILY
+  // — on the next push rather than at conviction time — so we never SIGTERM a child that
+  // may just be slow, and the rebuild resumes _sessionId for continuity.
+  let _suspectGeneration = false;
+  let _lastFailedTurn = null; // { turnId, retryable, apiStatus, attempt, maxRetries, code, ts } — drives the manual [retry] affordance
   let _sessionId = null;
   let _initAnnouncedSid = ''; // sessionId whose slash-command surface was already announced (reset on full reset)
   let _lastInitSnapshot = null; // last sdk-init payload for WS reconnect replay
@@ -380,6 +467,13 @@ function _createSession(key, cwd) {
   // injected by cli.js) > push-running / result-idle fallbacks below. Retained for WS
   // reconnect replay like _lastInitSnapshot; reset alongside it on switch/reset.
   let _lastSessionState = null;
+  let _stateHeartbeat = null;   // setInterval re-broadcasting sdk-session-state while a turn is active
+  // Message-activity coalescer state (see ACTIVITY_MIN_INTERVAL_MS): pending throttled
+  // activity frame plus the wall-clock turn stamp used as the wire-level turnStartedAt.
+  let _lastActivityAt = 0;
+  let _activityPending = null;  // { kind, rec }
+  let _activityTimer = null;
+  let _lastTurnStartedAt = 0;   // wire turnStartedAt for frames emitted with no head turn (idle settles)
   let _lastContextUsage = null;   // last sdk-context-usage frame for WS reconnect replay
   let _ctxUsageFetching = false;  // one getContextUsage control request in flight
   let _ctxUsageQueued = false;    // a turn-end/compact arrived while in flight → rerun once (coalesce)
@@ -450,11 +544,20 @@ function _createSession(key, cwd) {
   // (an interrupted turn still synthesizes an error_during_execution result). All
   // settle paths (result / grace force-settle / teardown settleAll) go through
   // _settleTurn, which is idempotent via rec.settled.
+  let _turnSeq = 0;
   function _beginTurn() {
     let resolve;
     const promise = new Promise((r) => { resolve = r; });
-    const rec = { resolve, interrupted: false, settled: false };
+    const rec = {
+      id: 'turn_' + (++_turnSeq).toString(36) + '_' + Math.random().toString(36).slice(2, 8),
+      resolve, interrupted: false, settled: false,
+      epoch: ++_turnEpoch, // generation this turn belongs to — the late-result guard keys off it
+      startedAt: Date.now(), // wall-clock turn stamp — the wire-level turnStartedAt (restart-safe, unlike the counter epoch)
+      loopStarted: false, loopEnded: false, // idempotence for the agent_loop boundary callbacks
+      apiRetry: { count: 0, attempt: 0, maxRetries: 0, lastStatus: null, lastError: null },
+    };
     _pendingTurns.push(rec);
+    _lastTurnStartedAt = rec.startedAt;
     return { rec, promise };
   }
 
@@ -471,38 +574,157 @@ function _createSession(key, cwd) {
     _queryBusy = false;
     _turnInFlight = false;
     _clearTurnWatchdog();
+    _clearLostResultBackstop();
   }
 
   function _clearGraceTimer() {
     if (_settleGraceTimer) { clearTimeout(_settleGraceTimer); _settleGraceTimer = null; }
   }
 
-  /** Soft SILENCE watchdog: re-armed on every incoming SDK message, so it only fires
-   * when the session has produced nothing for the full window — a genuinely stuck/dead
-   * turn. Pending approvals prove the session is alive (the child is parked waiting for
-   * our control response), so the watchdog merely re-arms in that case. Force-settle is
-   * symmetric with the interrupt grace path: settle the head turn FIRST (its promise
-   * must resolve), then tombstone the result that may still arrive. */
+  /** Activity probe (replaces the old fixed 25min silence watchdog). Re-armed on every
+   * incoming SDK message, so it only fires after ACTIVITY_PROBE_IDLE_MS of total silence.
+   * Instead of force-killing the turn for being quiet (which would murder a legal
+   * multi-hour tool run), it pings the CLI's control plane: a live child answers, a wedged
+   * one does not. Only ACTIVITY_PROBE_MAX_FAILURES consecutive unanswered probes convict
+   * the child and trigger recovery. Pending approvals also prove liveness (the child is
+   * parked awaiting our control response), so probes are not even sent then.
+   *
+   * `_probeFailures` deliberately survives re-arms: _clearTurnWatchdog only cancels the
+   * pending timer, and the counter is reset by a successful/answered probe (or a full
+   * teardown/reset) — otherwise conviction at MAX_FAILURES would be unreachable. */
   function _armTurnWatchdog() {
+    // NOTE: cancel + bump the epoch FIRST (any arm is triggered by observed activity
+    // and must invalidate an in-flight probe), then decide whether a timer is needed.
     _clearTurnWatchdog();
     if (_pendingTurns.length === 0) return;
-    _turnWatchdog = setTimeout(() => {
-      _turnWatchdog = null;
+    if (_pendingApprovals.size > 0) {
+      // Approval pending = the child is parked awaiting our control response, which
+      // itself proves liveness — do not even probe. No timer is armed here; probing
+      // resumes via _rearmWatchdogAfterApprovalSettled when the last approval settles.
+      return;
+    }
+    _activityProbe = setTimeout(() => {
+      _activityProbe = null;
       if (_pendingTurns.length === 0) return;
-      if (_pendingApprovals.size > 0) {
-        _armTurnWatchdog(); // approval pending = alive; wait out the approval timeout instead
+      if (_pendingApprovals.size > 0) { _armTurnWatchdog(); return; } // approval parked mid-wait — stand down
+      _runActivityProbe();
+    }, _probeFailures === 0 ? ACTIVITY_PROBE_IDLE_MS : ACTIVITY_PROBE_INTERVAL_MS);
+    if (_activityProbe.unref) _activityProbe.unref();
+  }
+
+  /** Re-arm the activity probe after the LAST pending approval settles (answered,
+   * cancelled, or timed out). _armTurnWatchdog deliberately arms NO timer while an
+   * approval is parked (the park itself proves liveness), so without this hook a
+   * child that wedges AFTER the approval clears would never be probed again — the
+   * watchdog would be permanently disarmed for the rest of the turn. Only re-arm
+   * when the approval map just emptied; a still-pending sibling approval keeps the
+   * park (and its liveness guarantee) intact. */
+  function _rearmWatchdogAfterApprovalSettled() {
+    if (_pendingTurns.length === 0) return;
+    if (_pendingApprovals.size > 0) return;
+    _armTurnWatchdog();
+  }
+
+  function _clearTurnWatchdog() {
+    if (_activityProbe) { clearTimeout(_activityProbe); _activityProbe = null; }
+    // Any arm/clear is triggered by observed activity (a message re-arms on every frame,
+    // a settle clears) — invalidate an in-flight probe and reset consecutive-failure
+    // counting so a slow probe on the PREVIOUS quiet stretch cannot convict a live turn.
+    _probeEpoch++;
+    if (_pendingTurns.length === 0) _probeFailures = 0;
+  }
+
+  /** Ping the child's control plane once with a REAL control round-trip (getContextUsage;
+   * supportedCommands/initializationResult resolve from the cached init promise and prove
+   * nothing). An answer — resolve OR reject — means the event loop is responsive: reset
+   * the failure count and keep waiting silently. No answer within the timeout counts one
+   * failure; ACTIVITY_PROBE_MAX_FAILURES consecutive failures convict the child as wedged.
+   * Both outcomes re-check the generation + FIFO: a probe started on query A must never
+   * convict generation B, and a turn that completed mid-probe must not be "recovered".
+   * A probe that never resolves leaks one in-flight control request per conviction —
+   * bounded, and the pending reject on teardown (Query.cleanup) is swallowed by `done`. */
+  function _runActivityProbe() {
+    const q = _activeQuery;
+    if (!q || typeof q.getContextUsage !== 'function') { _armTurnWatchdog(); return; }
+    // Bind the verdict to the TURN probed AND the probe epoch: any message/interrupt
+    // observed since this probe started proves the child is alive, so its timeout must be
+    // discarded rather than charged. (a new turn as head also invalidates the verdict.)
+    const probeRec = _pendingTurns[0] || null;
+    const epoch = _probeEpoch;
+    let timer = null;
+    let done = false;
+    // NOTE: own .then/.catch handlers instead of Promise.race — under node:test mocked
+    // timers a Promise.race([neverSettlingPromise, mockedTimerPromise]) never runs its
+    // reactions (race subscribes to the pending promise first; the mocked timer's later
+    // settle does not flush the race's capability). Plain handlers are immune.
+    timer = setTimeout(() => {
+      if (done) return;
+      done = true;
+      timer = null;
+      finish('timeout');
+    }, CTX_USAGE_TIMEOUT_MS);
+    if (timer.unref) timer.unref();
+    let probeCall;
+    try { probeCall = q.getContextUsage(); }
+    catch { finish('answered'); return; } // a sync throw still proves the event loop runs
+    if (!probeCall || typeof probeCall.then !== 'function') { finish('answered'); return; } // non-Promise impl = responsive
+    probeCall.then(
+      () => { if (done) return; done = true; if (timer) { clearTimeout(timer); timer = null; } finish('answered'); },
+      () => { if (done) return; done = true; if (timer) { clearTimeout(timer); timer = null; } finish('answered'); },
+    );
+    function finish(outcome) {
+      // Stale generation / settled-or-switched turn / activity since the probe started /
+      // a user interrupt / a parked approval: the probe's verdict no longer applies.
+      if (_activeQuery !== q || _pendingTurns.length === 0 || _pendingTurns[0] !== probeRec) return;
+      if (epoch !== _probeEpoch) return; // activity observed mid-probe — the child is alive
+      if (probeRec && probeRec.interrupted) return;
+      if (_pendingApprovals.size > 0) return;
+      if (outcome === 'timeout') {
+        _probeFailures += 1;
+        if (_probeFailures < ACTIVITY_PROBE_MAX_FAILURES) { _armTurnWatchdog(); return; }
+        console.warn('[sdk-manager] turn unresponsive to control probes — recovering the wedged query');
+        _recoverFromStuckTurn(_pendingTurns[0] || null);
         return;
       }
-      console.warn('[sdk-manager] turn silent beyond watchdog window — force-settling (possible silent session death)');
-      _lateResultTombstones++;
-      _settleAllTurns();
-      _maybeDrain();
-    }, TURN_WATCHDOG_MS);
-    if (_turnWatchdog.unref) _turnWatchdog.unref();
+      // resolve OR reject both prove the control plane (event loop) is responsive.
+      _probeFailures = 0;
+      _armTurnWatchdog(); // still no turn output — schedule the next idle probe
+    }
   }
 
-  function _clearTurnWatchdog() {
-    if (_turnWatchdog) { clearTimeout(_turnWatchdog); _turnWatchdog = null; }
+  /** Recover from a genuinely wedged query (proven by control probes, or an interrupt the
+   * CLI never answered). Settles turn promises, announces idle, records a retryable failure
+   * so the UI can offer a manual [retry], and marks the generation suspect. The teardown
+   * itself is LAZY — deferred to the next push (_startTurn consults _suspectGeneration) —
+   * so we never SIGTERM a merely-slow child mid-side-effect; the rebuild resumes
+   * _sessionId for continuity. */
+  function _recoverFromStuckTurn(stalledRec) {
+    _suspectGeneration = true;
+    // Cancel any parked approvals: they belong to the (now suspect) generation's canUseTool,
+    // and leaving them would replay a ghost modal on attach AND suppress probing on the
+    // rebuilt generation (size > 0 = "alive"). They time out / deny as their own path.
+    _cancelAllApprovals();
+    // Mark the result that a merely-slow child may still emit before the lazy teardown —
+    // otherwise it would fire a spurious turn_end for an already-failed turn. Bound to the
+    // head turn's epoch so it cannot tax a later turn if the result never arrives.
+    if (_pendingTurns[0]) _lateResultEpoch = _pendingTurns[0].epoch;
+    const stuckRecs = [..._pendingTurns];
+    _settleAllTurns();
+    for (const r of stuckRecs) _emitAgentLoopEnd(r, 'turn-stuck');
+    _announceSessionState('idle', stalledRec || null);
+    _clearActivity();
+    // Retry is only possible if a session id was captured to resume — a first turn that
+    // wedges before any init frame has nothing to continue, so don't offer [retry].
+    const retryable = !!(_sessionId || _launchResume);
+    _lastFailedTurn = {
+      turnId: stalledRec?.id || null, retryable, apiStatus: null,
+      attempt: stalledRec?.apiRetry?.attempt || 0, maxRetries: stalledRec?.apiRetry?.maxRetries || 0,
+      code: 'turn-stuck', ts: Date.now(),
+    };
+    _notifyQueryError(new Error('The turn became unresponsive; the SDK session will restart on the next message.'), {
+      code: 'turn-stuck', retryable, turnId: stalledRec?.id || null,
+    });
+    _maybeDrain(); // a queued backlog must not stall behind the recovered turn
   }
 
   /**
@@ -536,7 +758,18 @@ function _createSession(key, cwd) {
     // A fresh user-initiated turn re-arms automatic draining of parked (Stop-kept) items.
     _suppressDrain = false;
     _consecutiveDeaths = 0; // explicit user action re-arms the death-drain backstop
-    const { promise } = await _startTurn(text);
+    const { started, promise, notified } = await _startTurn(text);
+    // A pre-push delivery failure (teardown raced / query closed) would otherwise leave
+    // the user with a cleared composer and no signal. _startTurn already settled the turn
+    // promise (so `promise` won't hang); reject HERE with a code so server.js can route a
+    // directed sdk-send-failed to the initiator. Construction failures are excluded
+    // (notified:true) — they already fired _notifyQueryError (a second toast would
+    // double-report).
+    if (!started && !notified) {
+      const err = new Error('message not delivered to the SDK session');
+      err.code = 'not-delivered';
+      throw err;
+    }
     return promise;
   }
 
@@ -569,6 +802,16 @@ function _createSession(key, cwd) {
    *    rejects; a later turn failure must NOT put an already-pushed message back.
    */
   async function _startTurn(text, dispatch = null) {
+    // A convicted/suspect generation is torn down HERE — lazily, just before the next
+    // push — rather than at conviction time. Deferring avoids SIGTERM-ing a merely-slow
+    // child mid-side-effect; rebuilding now lets _ensureResidentQuery resume _sessionId.
+    // This MUST run before _beginTurn(): teardown settles every pending turn record, so a
+    // record created first would be settled (and its message silently dropped) by its own
+    // teardown, leaving _queryBusy wedged with an empty FIFO.
+    if (_suspectGeneration) {
+      _suspectGeneration = false;
+      _teardownResident();
+    }
     const { rec, promise } = _beginTurn();
     if (dispatch) rec.dispatchItem = dispatch;
     _queryBusy = true;
@@ -580,7 +823,9 @@ function _createSession(key, cwd) {
       _settleTurn(rec);
       _queryBusy = false;
       _notifyQueryError(err);
-      return { started: false, promise };
+      // notified:true tells _sendUserMessage NOT to also reject not-delivered — the user
+      // already got the query-error toast; a second rejection would double-report.
+      return { started: false, promise, turnId: rec.id, notified: true };
     }
     // Teardown/stop raced with construction — the settle already happened; don't push.
     if (rec.settled || (dispatch && _dispatching !== dispatch)) {
@@ -589,13 +834,13 @@ function _createSession(key, cwd) {
         _settleTurn(rec);
         if (_dispatching !== dispatch) _queryBusy = false;
       }
-      return { started: false, promise };
+      return { started: false, promise, turnId: rec.id };
     }
     if (!_activeQuery || !_inputQueue || (typeof _inputQueue.isClosed === 'function' && _inputQueue.isClosed()) || (dispatch && _dispatching !== dispatch)) {
       _pendingTurns = _pendingTurns.filter((turn) => turn !== rec);
       _settleTurn(rec);
       _queryBusy = false;
-      return { started: false, promise };
+      return { started: false, promise, turnId: rec.id };
     }
     // Typed /clear is detected at EXECUTION time (never at enqueue time): a clear queued
     // behind a busy turn must not wipe the running turn's usage panel. Invalidate the
@@ -613,16 +858,19 @@ function _createSession(key, cwd) {
       _settleTurn(rec);
       _queryBusy = false;
       reportSwallowed('sdk-manager.queue-push', err);
-      return { started: false, promise };
+      return { started: false, promise, turnId: rec.id };
     }
     _turnInFlight = true;
     // Turn-level loading fallback: light the spinner the moment the turn is pushed.
     // The CLI's own session_state_changed(running) arrives later and is idempotent
     // against this — on CLIs that never emit it (no env gate / older build) this is
     // the only "on" signal, paired with the result-idle broadcast in _processMessage.
-    _announceSessionState('running');
+    _announceSessionState('running', rec);
+    // Authoritative loop start (voice/plugin/SSE agent_loop_start) — fires once, only
+    // after the push is accepted (queued/undelivered messages never ring).
+    _emitAgentLoopStart(rec);
     _armTurnWatchdog();
-    return { started: true, promise };
+    return { started: true, promise, turnId: rec.id };
   }
 
   /**
@@ -883,6 +1131,10 @@ function _createSession(key, cwd) {
   async function _drainResidentIterator(query, inputQueue) {
     try {
       for await (const msg of query) {
+        // Generation guard: after a teardown/switch, a stale generation's late frames must
+        // NOT be processed — they belong to the dead child and would mis-settle the NEW
+        // generation's pending turns. Bail out and let _onResidentDeath dismiss it as stale.
+        if (_activeQuery !== query) break;
         // A message-processing failure (e.g. a broadcast callback throwing) must NOT be
         // mistaken for session death — the child is still alive; only the iterator's
         // end/throw is a death signal.
@@ -891,7 +1143,13 @@ function _createSession(key, cwd) {
         } catch (msgErr) {
           reportSwallowed('sdk-manager.process-message', msgErr);
         }
-        _armTurnWatchdog(); // silence watchdog: any message proves the session is alive
+        // Any message proves the child is alive: reset consecutive-failure counting too,
+        // so a probe that timed out on the PREVIOUS quiet stretch cannot convict a turn
+        // that has since demonstrably produced output.
+        _probeFailures = 0;
+        _inboundMsgSeq++;
+        _armTurnWatchdog(); // reset the activity probe on observed activity
+        _noteActivity(msg); // coalesced UI liveness (≤1/s sdk-session-state activity frame)
       }
       _onResidentDeath(query, inputQueue, null);
     } catch (err) {
@@ -909,6 +1167,10 @@ function _createSession(key, cwd) {
     if (_activeQuery !== query) return; // stale generation — teardown already moved on
     _activeQuery = null;
     _inputQueue = null;
+    // The (possibly wedged) child exited on its own — the suspicion dies with it, so the
+    // next push must not run a pointless teardown against an already-dead generation.
+    _suspectGeneration = false;
+    _probeFailures = 0;
     if (_ctxUsageClearPending) {
       // A child that exits while applying /clear must not resume the cleared session on the
       // next message. Start fresh, allow the next init/read, and invalidate older controls.
@@ -919,13 +1181,38 @@ function _createSession(key, cwd) {
     }
     _clearGraceTimer();
     _clearTurnWatchdog();
-    _lateResultTombstones = 0;
+    _clearStateHeartbeat();
+    _clearActivity();
+    // Clear any stale late-result debt: the dead generation's frames are filtered by the
+    // _activeQuery guard, so the owed result can never arrive — leaving the debt would
+    // suppress the next generation's api_retry frames (and its retry affordance).
+    _lateResultEpoch = 0;
+    const hadTurns = _pendingTurns.length > 0;
+    const headTurn = _pendingTurns[0] || null;
     // Session died mid-turn: no result will arrive, so without this the spinner would
-    // hang until the 25min watchdog. The turn is unambiguously over.
-    _announceSessionState('idle');
+    // hang forever. The turn is unambiguously over. `headTurn` stamps the idle with the
+    // dead turn's id, and every pending turn reports its loop end (session-ended).
+    _announceSessionState('idle', headTurn);
+    // Only a turn that actually STARTED reports an end — a record that never reached the
+    // push (construction raced with this death) must not emit an end with no matching start.
+    if (hadTurns) { for (const rec of _pendingTurns) { if (rec.loopStarted) _emitAgentLoopEnd(rec, 'session-ended'); } }
     if (err && err.name !== 'AbortError') {
       console.error('[SDK] Resident query error:', err.message);
       _notifyQueryError(err);
+    } else if (!err && hadTurns) {
+      // Clean exit with a turn still in flight is itself a failure — the user would
+      // otherwise see only "idle" with no error. If the CLI exhausted API retries
+      // before dying, keep it retryable so the manual [retry] affordance appears.
+      const retried = (headTurn?.apiRetry?.count || 0) > 0;
+      if (retried) {
+        const status = headTurn.apiRetry.lastStatus;
+        _lastFailedTurn = {
+          turnId: headTurn.id, retryable: (status == null || RETRYABLE_STATUS.has(status)) && !!(_sessionId || _launchResume),
+          apiStatus: status, attempt: headTurn.apiRetry.attempt, maxRetries: headTurn.apiRetry.maxRetries,
+          code: 'session-ended', ts: Date.now(),
+        };
+      }
+      _notifyQueryError(new Error('Agent SDK session ended before the turn completed'), { code: 'session-ended', retryable: retried && !!(_sessionId || _launchResume), turnId: headTurn?.id || null });
     }
     _settleAllTurns();
     // A dispatching item waiting on an interrupt unwind never reached the SDK. Death
@@ -974,7 +1261,21 @@ function _createSession(key, cwd) {
     _initSkills = null;        // re-captured from the next init frame
     _clearGraceTimer();
     _clearTurnWatchdog();
-    _lateResultTombstones = 0;
+    _probeFailures = 0;
+    _clearStateHeartbeat();
+    _clearActivity();
+    // Teardown filters the dead generation's late frames via _activeQuery, so its owed
+    // result can never arrive — clear the debt or it would suppress the rebuilt turn's
+    // api_retry frames. (_lastFailedTurn survives on purpose; the debt must not.)
+    _lateResultEpoch = 0;
+    // NOTE: _lastFailedTurn deliberately survives teardown — the lazy rebuild path
+    // (_startTurn's suspect-generation teardown) must keep the recorded failure so the
+    // manual [retry] affordance stays available. User-facing session boundaries clear it
+    // instead: _resetFullState / _switchToSession (which funnel close/teardown/stop).
+    // Teardown is also a loop boundary: any turn that STARTED must report its end, or
+    // SSE clients / onAgentLoopEnd plugins see a start with no end (killed workspace,
+    // session switch mid-turn). Guard on loopStarted so a never-pushed record stays silent.
+    for (const rec of _pendingTurns) { if (rec.loopStarted) _emitAgentLoopEnd(rec, 'session-ended'); }
     _settleAllTurns();
     if (inputQueue) inputQueue.close();
     if (query) {
@@ -984,10 +1285,11 @@ function _createSession(key, cwd) {
   }
 
   /** Query-level error signal; the routing envelope always comes from this
-   * session's closure (callback throw must never break the caller). */
-  function _notifyQueryError(err) {
+   * session's closure (callback throw must never break the caller). `extra` carries
+   * failure metadata (code/retryable/turnId/apiStatus) through to the sdk-error frame. */
+  function _notifyQueryError(err, extra = {}) {
     if (!_onQueryError) return;
-    const context = { cwd: _cwd, sessionId: _sessionId || null, instanceKey };
+    const context = { cwd: _cwd, sessionId: _sessionId || null, instanceKey, ...extra };
     try { _onQueryError(String(err?.message || err), context); }
     catch (cbErr) { console.warn('[sdk-manager] onQueryError threw:', cbErr?.message); }
   }
@@ -1070,14 +1372,116 @@ function _createSession(key, cwd) {
    * Announce a turn-level session state to WS clients (spinner source in SDK mode).
    * State-change guarded + retained for reconnect replay. Broadcast failures are
    * swallowed inside this helper — the message loop must never die on a UI signal.
+   *
+   * Every frame carries turn correlation (turnId + turnStartedAt): the CLI's
+   * session_state_changed has no turn id of its own, so a late frame from the PREVIOUS
+   * turn (e.g. its idle arriving after a fresh push) would otherwise clear the new
+   * turn's spinner. `rec` is the turn this state belongs to — internal settle paths
+   * pass it explicitly because the FIFO head may already have shifted.
    */
-  function _announceSessionState(state) {
+  function _announceSessionState(state, rec = null) {
     const valid = state === 'idle' || state === 'running' || state === 'requires_action';
     if (!valid || state === _lastSessionState) return;
     _lastSessionState = state;
+    const owner = rec || _pendingTurns[0] || null;
     // _broadcast carries the routing envelope (cwd + sessionId + instanceKey) — every
     // frame needs it so concurrent sessions' clients filter correctly.
-    _broadcast({ type: 'sdk-session-state', state });
+    _broadcast({
+      type: 'sdk-session-state', state,
+      turnId: owner ? owner.id : null,
+      turnStartedAt: owner ? owner.startedAt : _lastTurnStartedAt,
+    });
+    _syncStateHeartbeat();
+  }
+
+  /** One-shot agent-loop boundary callbacks (voice/plugin/SSE agent_loop_*). Idempotent
+   * per turn record — every settle path (result, interrupt grace, lost result, stuck
+   * recovery, death) funnels through _emitAgentLoopEnd exactly once. Callback throws are
+   * isolated so a broken host can never wedge the message loop. */
+  function _emitAgentLoopStart(rec) {
+    if (!rec || rec.loopStarted) return;
+    rec.loopStarted = true;
+    if (!_onAgentLoopStart) return;
+    try { _onAgentLoopStart({ sessionId: _sessionId || null, ts: Date.now(), cwd: _cwd, instanceKey, turnId: rec.id, turnStartedAt: rec.startedAt }); }
+    catch (err) { reportSwallowed('sdk-manager.agent-loop-start', err); }
+  }
+  function _emitAgentLoopEnd(rec, reason) {
+    if (!rec || rec.loopEnded) return;
+    rec.loopEnded = true;
+    if (!_onAgentLoopEnd) return;
+    try { _onAgentLoopEnd({ sessionId: _sessionId || null, ts: Date.now(), cwd: _cwd, instanceKey, turnId: rec.id, turnStartedAt: rec.startedAt, reason }); }
+    catch (err) { reportSwallowed('sdk-manager.agent-loop-end', err); }
+  }
+
+  /** Coalesced message-level liveness: any non-boundary SDK message (assistant/user/
+   * tool_progress / system task_* frames / status / api_retry / compact …) proves the
+   * loop is alive mid-turn — including tool/compaction/hook phases the proxy's per-API
+   * streaming_status cannot see. Frames reuse the sdk-session-state shape with
+   * heartbeat+activity flags (no new client handler) and are capped at one per
+   * ACTIVITY_MIN_INTERVAL_MS. */
+  function _noteActivity(msg) {
+    if (_pendingTurns.length === 0 || !msg) return;
+    const t = msg.type;
+    if (t === 'result') return; // boundary, not progress
+    if (t === 'system' && msg.subtype === 'session_state_changed') return; // state frame, not activity
+    const rec = _pendingTurns[0];
+    const kind = t === 'system' ? `system:${msg.subtype || ''}`
+      : t === 'stream_event' ? `stream:${(msg.event && msg.event.type) || ''}` : t;
+    _activityPending = { kind, rec };
+    const wait = Math.max(0, ACTIVITY_MIN_INTERVAL_MS - (Date.now() - _lastActivityAt));
+    if (wait === 0) _flushActivity();
+    else if (!_activityTimer) {
+      _activityTimer = setTimeout(_flushActivity, wait);
+      if (_activityTimer.unref) _activityTimer.unref();
+    }
+  }
+  function _flushActivity() {
+    if (_activityTimer) { clearTimeout(_activityTimer); _activityTimer = null; }
+    const p = _activityPending; _activityPending = null;
+    if (!p || p.rec.settled || _pendingTurns[0] !== p.rec) return;
+    if (_lastSessionState !== 'running' && _lastSessionState !== 'requires_action') return;
+    _lastActivityAt = Date.now();
+    _broadcast({
+      type: 'sdk-session-state', state: _lastSessionState, heartbeat: true, activity: true,
+      kind: p.kind, turnId: p.rec.id, turnStartedAt: p.rec.startedAt,
+      pendingApprovals: _pendingApprovals.size,
+    });
+  }
+  function _clearActivity() {
+    if (_activityTimer) { clearTimeout(_activityTimer); _activityTimer = null; }
+    _activityPending = null;
+    _lastActivityAt = 0;
+  }
+
+  // The in-flight turn is the FIFO HEAD (the result branch shifts from the head).
+  const _currentTurnId = () => (_pendingTurns.length ? _pendingTurns[0].id : null);
+
+  /** While a turn is running/requires_action, re-broadcast the session state every
+   * STATE_HEARTBEAT_MS so clients (a) keep their Stop button / spinner alive past the
+   * frontend's 30s no-signal stale sweep, and (b) can re-derive it after a view switch.
+   * The heartbeat does NOT re-arm the activity probe (silence semantics unchanged) and
+   * is cleared on idle/teardown/reset/switch/death. */
+  function _syncStateHeartbeat() {
+    const active = _lastSessionState === 'running' || _lastSessionState === 'requires_action';
+    if (active && !_stateHeartbeat) {
+      _stateHeartbeat = setInterval(() => {
+        if (_lastSessionState !== 'running' && _lastSessionState !== 'requires_action') return;
+        const head = _pendingTurns[0] || null;
+        _broadcast({
+          type: 'sdk-session-state', state: _lastSessionState, heartbeat: true,
+          turnId: _currentTurnId(), turnStartedAt: head ? head.startedAt : _lastTurnStartedAt,
+          pendingApprovals: _pendingApprovals.size,
+        });
+      }, STATE_HEARTBEAT_MS);
+      if (_stateHeartbeat.unref) _stateHeartbeat.unref();
+    } else if (!active && _stateHeartbeat) {
+      clearInterval(_stateHeartbeat);
+      _stateHeartbeat = null;
+    }
+  }
+
+  function _clearStateHeartbeat() {
+    if (_stateHeartbeat) { clearInterval(_stateHeartbeat); _stateHeartbeat = null; }
   }
 
   /**
@@ -1096,7 +1500,58 @@ function _createSession(key, cwd) {
         // which cli.js injects into the child env; on CLIs that never emit it the
         // push/result fallbacks keep the spinner correct at result granularity.
         if (msg.subtype === 'session_state_changed') {
-          _announceSessionState(msg.state);
+          // Late-idle suppression (LOAD-BEARING gate): session_state_changed carries no
+          // turn id, so an idle that settles the PREVIOUS turn can arrive after a fresh
+          // push. If the head turn has never been seen running/requires_action by the CLI,
+          // this idle cannot belong to it — drop it, or it would kill the new turn's
+          // spinner. The frontend's turnStartedAt guard is NOT a substitute here: a stale
+          // idle processed AFTER the new push is stamped with the NEW head's epoch, so the
+          // client cannot tell it apart — only this server-side cliStateSeen gate can (the
+          // client guard only helps against transport-level reordering of older-stamped
+          // frames). Residual hazard (new turn's running lands before the old idle): the
+          // gate passes it; the lost-result backstop's armedSeq check below disarms the
+          // resulting mis-armed conviction when the head turn is still producing messages.
+          const head = _pendingTurns[0] || null;
+          const staleIdle = msg.state === 'idle' && head && !head.cliStateSeen;
+          if (!staleIdle) {
+            _announceSessionState(msg.state, head);
+            // A CLI-emitted running/requires_action proves the head turn is genuinely
+            // in-flight on the child (vs a freshly-drained turn whose own CLI frames have
+            // not arrived yet). Lost-result only arms for such a turn — a LATE idle frame
+            // from the previous turn must not convict the just-pushed one.
+            if ((msg.state === 'running' || msg.state === 'requires_action') && head) head.cliStateSeen = true;
+            // Lost-result backstop: the CLI says the turn settled (idle) but no result
+            // message arrived for our pending FIFO. Without this _queryBusy would wedge
+            // forever now that the 25min silence watchdog is gone. Give the result a short
+            // grace to arrive first (frame ordering within a turn end is not guaranteed),
+            // then settle as a retryable failure.
+            if (msg.state === 'idle' && head && head.cliStateSeen) _armLostResultBackstop();
+          }
+        } else if (msg.subtype === 'api_retry') {
+          // The CLI's own retry of a retryable API error (502/429/5xx/network). It carries
+          // no turn id, so we attribute it to the head pending turn — approximate but
+          // correct in the common single-turn case. Skipped only while a late-result debt
+          // is pending AND no live turn could own the frame (a late retry of an
+          // already-interrupted turn must not relight the bar). The gate mirrors the
+          // result branch's orphan rule: a stale debt must never suppress a live turn's
+          // own retry frames, and must not outlive the teardown/reset that orphaned it.
+          if (_lateResultEpoch === 0 || _pendingTurns.length > 0) {
+            const rec = _pendingTurns.length ? _pendingTurns[0] : null;
+            if (rec) {
+              rec.apiRetry.count += 1;
+              rec.apiRetry.attempt = Number(msg.attempt) || rec.apiRetry.count;
+              rec.apiRetry.maxRetries = Number(msg.max_retries) || 0;
+              rec.apiRetry.lastStatus = (typeof msg.error_status === 'number') ? msg.error_status : null;
+              rec.apiRetry.lastError = msg.error || null;
+              _broadcast({
+                type: 'sdk-retry-state', phase: 'retrying', turnId: rec.id,
+                attempt: rec.apiRetry.attempt, maxRetries: rec.apiRetry.maxRetries,
+                retryDelayMs: Number(msg.retry_delay_ms) || 0,
+                errorStatus: rec.apiRetry.lastStatus, error: rec.apiRetry.lastError || null,
+                ts: Date.now(),
+              });
+            }
+          }
         } else if (msg.subtype === 'init') {
           // /clear may reinitialize instead of returning a normal result. The new session is
           // now authoritative, so context reads may resume (without resuming the old session).
@@ -1165,36 +1620,88 @@ function _createSession(key, cwd) {
 
       case 'result': {
         if (msg.session_id) _sessionId = msg.session_id;
-        // Grace/watchdog tombstone: a result that arrives AFTER its turn was already
-        // force-settled belongs to that dead turn — discard it instead of letting it
-        // settle (and prematurely end) the NEXT turn. If the tombstone outlived its turn
-        // entirely (the owed result never comes) the count would swallow a FUTURE turn's
-        // result — the bookkeeping clear below keeps that mistake bounded to the
-        // turn-end signal rather than wedging _queryBusy.
-        if (_lateResultTombstones > 0) {
-          _lateResultTombstones--;
-          _clearGraceTimer();
-          _queryBusy = false;
-          _turnInFlight = false;
-          // The tombstoned turn is over — but a NEWER turn may already be in flight
-          // (Stop → grace settle → user re-sent → late result of the old turn arrives).
-          // Only announce idle when no turn is pending, else we'd kill turn 2's spinner.
-          if (_pendingTurns.length === 0) {
-            _announceSessionState('idle');
-            _clearTurnWatchdog();
+        // Background-task wake results are NOT turn boundaries: while local_agent /
+        // local_workflow tasks are active the CLI holds the turn's real result back, and
+        // each answered task notification can yield a synthetic result (num_turns: 0,
+        // empty result). Treating one as end-of-turn fires a phantom turn_end (and would
+        // ring the voice pack / clear the spinner mid-loop), so skip it entirely.
+        if (msg.origin && msg.origin.kind === 'task-notification') break;
+        // Generation guard for late results. Result frames carry no turn id, so a result
+        // that arrives AFTER its turn was force-settled is indistinguishable from the NEXT
+        // turn's result on arrival order alone. The guard resolves this by generation:
+        // a force-settled turn is REMOVED from the FIFO (shift / settleAll), so when a
+        // result arrives and the FIFO is EMPTY, nothing live could own it — it is the dead
+        // generation's late result and is discarded (no turn_end, no error attribution).
+        //
+        // Deliberate trade-off (NOT a guarantee): when a NEWER turn is already in flight,
+        // an arriving result is paired with it (`head.epoch > _lateResultEpoch`), because
+        // swallowing the live turn's own result is the worse failure (that was the original
+        // bug — the stuck turn got mis-settled as turn-stuck and re-ran). The cost is that
+        // a genuinely-late result of the dead generation CAN be mis-paired to the live turn
+        // here (an early/extra turn_end, or a wrong error toast attributed to it) — accepted
+        // because the live turn must not lose its own result. This window is narrow: the
+        // late result must arrive after the backstop AND after a newer turn has started.
+        if (_lateResultEpoch !== 0) {
+          const head = _pendingTurns[0] || null;
+          if (!head) {
+            // No live turn could own this result — it is the dead generation's late result.
+            _lateResultEpoch = 0;
+            _clearGraceTimer();
+            _queryBusy = false;
+            _turnInFlight = false;
+            // The dead generation is over — but a NEWER turn may already be in flight
+            // (Stop → grace settle → user re-sent → late result of the old turn arrives).
+            // Only announce idle when no turn is pending, else we'd kill turn 2's spinner.
+            if (_pendingTurns.length === 0) {
+              _announceSessionState('idle');
+              _clearTurnWatchdog();
+              _clearActivity();
+            }
+            _maybeDrain();
+            break;
           }
-          _maybeDrain();
-          break;
+          // A NEWER generation is in flight: this result is that live turn's own, so fall
+          // through to pair it normally — and drop the never-arriving late result's debt.
+          _lateResultEpoch = 0;
         }
         const rec = _pendingTurns.shift();
+        // 502/retry state machine. An error result after observed CLI retries records a
+        // retryable _lastFailedTurn (drives the manual [retry] affordance). ANY success
+        // unconditionally closes a recorded failure — including a manual retry that
+        // succeeds on its first API attempt (apiRetry.count === 0) — and clears
+        // _lastFailedTurn; `retryOf` carries the FAILED turn's id (rec.retryOf when this
+        // turn is itself a manual retry) because the frontend matches cleanup by it.
+        if (rec) {
+          const isError = msg.is_error === true || (msg.subtype && msg.subtype !== 'success');
+          if (isError && !rec.interrupted) {
+            const status = rec.apiRetry.lastStatus;
+            const retryable = rec.apiRetry.count > 0 && (status == null || RETRYABLE_STATUS.has(status));
+            _lastFailedTurn = {
+              turnId: rec.id, retryable, apiStatus: status,
+              attempt: rec.apiRetry.attempt, maxRetries: rec.apiRetry.maxRetries, code: null, ts: Date.now(),
+            };
+          } else if (!isError && _lastFailedTurn && (rec.apiRetry.count > 0 || rec.retryOf === _lastFailedTurn.turnId)) {
+            // recovered only when there IS a recorded failure AND this turn closes it
+            // (a manual retry of it — even on its first attempt — or a turn that itself
+            // saw CLI retries). A clean success (no _lastFailedTurn) emits nothing; an
+            // unrelated later success neither clears the affordance nor spams the frame.
+            _broadcast({ type: 'sdk-retry-state', phase: 'recovered', turnId: rec.id, retryOf: rec.retryOf || _lastFailedTurn.turnId, ts: Date.now() });
+            _lastFailedTurn = null;
+          }
+        }
         // An interrupted turn's result is expected to be an error (turn aborted) — don't
         // toast it. Turn-end still fires, matching the PTY Stop-hook semantics.
-        if (rec && !rec.interrupted) _notifyTurnError(msg);
+        if (rec && !rec.interrupted) _notifyTurnError(msg, rec);
         // SDK turn-end signal. Equivalent to Claude Code's Stop hook
         // in CLI mode — fires once per user-prompt response when the whole chain
         // (assistant text + all tool calls + final reply) completes. SDK mode
         // doesn't go through ensureHooks() so this in-process callback is the
-        // only way the renderer learns the turn is over.
+        // only way the renderer learns the turn is over. NOTE: deliberately NOT
+        // gated on `rec` — the late-result trade-off (see the generation-guard
+        // comment above) pairs a dead turn's late result with the live turn, and
+        // the live turn's OWN result can then arrive with an empty FIFO; phantom
+        // ringing from background tasks is prevented by the task-notification
+        // filter above, not by requiring a FIFO record.
         if (_onTurnEnd) {
           // Per-workspace (2026-10): carry the session's own cwd so the server
           // can route turn_end to THIS workspace's SSE scope (SDK mode has no
@@ -1203,13 +1710,23 @@ function _createSession(key, cwd) {
           catch (err) { console.warn('[sdk-manager] onTurnEnd threw:', err?.message); }
         }
         if (rec) _settleTurn(rec);
+        // Authoritative loop end for THIS turn — immediate, per-turn (turnId/turnStartedAt
+        // correlated), unlike the debounced turn_end above. `is_error`/non-success
+        // subtypes distinguish error ends; interrupted turns report their own reason.
+        if (rec) {
+          const errored = msg.is_error === true || (msg.subtype && msg.subtype !== 'success');
+          _emitAgentLoopEnd(rec, rec.interrupted ? 'interrupted' : (errored ? 'error' : 'success'));
+        }
         _clearGraceTimer();
+        _clearActivity();
         _queryBusy = false;
         _turnInFlight = false;
         // Turn-level spinner clear at result time — immediate, unlike the debounced
         // `turn_end` SSE (voice-pack semantics). Idempotent against a real
-        // session_state_changed(idle) arriving before/after.
-        _announceSessionState('idle');
+        // session_state_changed(idle) arriving before/after. `rec` is passed explicitly:
+        // the FIFO head has already shifted, so the default head lookup would stamp this
+        // idle with the NEXT turn's id.
+        _announceSessionState('idle', rec);
         if (_pendingTurns.length === 0) _clearTurnWatchdog();
         _maybeDrain();
         // Refresh the context-usage panel AFTER the turn fully settles (fire-and-forget,
@@ -1231,14 +1748,17 @@ function _createSession(key, cwd) {
    * never signals it, so a dead/errored turn would otherwise look like a hang. The
    * sdk-error frame renders as a persistent dialogue row plus a toast client-side.
    */
-  function _notifyTurnError(resultMsg) {
+  function _notifyTurnError(resultMsg, rec = null) {
     const isError = resultMsg.is_error === true || (resultMsg.subtype && resultMsg.subtype !== 'success');
     if (!isError) return;
     const errs = Array.isArray(resultMsg.errors) && resultMsg.errors.length
       ? resultMsg.errors.join('; ')
       : (typeof resultMsg.result === 'string' && resultMsg.result) || resultMsg.subtype || 'unknown error';
+    const retry = rec?.apiRetry || null;
+    const status = retry?.lastStatus ?? null;
+    const retryable = !!retry?.count && (status == null || RETRYABLE_STATUS.has(status));
     if (_broadcastWs) {
-      try { _broadcastWs({ type: 'sdk-error', message: String(errs), cwd: _cwd, sessionId: _sessionId || null, instanceKey }); } catch (err) { console.warn('[sdk-manager] sdk-error broadcast threw:', err?.message); }
+      try { _broadcastWs({ type: 'sdk-error', message: String(errs), turnId: rec?.id || null, retryable, apiStatus: status, attempt: retry?.attempt || 0, maxRetries: retry?.maxRetries || 0, cwd: _cwd, sessionId: _sessionId || null, instanceKey }); } catch (err) { console.warn('[sdk-manager] sdk-error broadcast threw:', err?.message); }
     }
   }
 
@@ -1683,6 +2203,7 @@ function _createSession(key, cwd) {
         // Close the modal on every client — a silent deny would leave it hanging forever.
         _broadcastApprovalDismiss(kind, id, 'timeout');
         resolve(null);
+        _rearmWatchdogAfterApprovalSettled();
       }, timeoutMs);
       const entry = {
         kind,  // 'ask' | 'plan' | 'perm' — lets cancelApproval distinguish types so an
@@ -1701,6 +2222,7 @@ function _createSession(key, cwd) {
           if (cur?.auto) cancelAutoApproveState(cur.auto);
           _pendingApprovals.delete(id);
           resolve(value);
+          _rearmWatchdogAfterApprovalSettled();
         },
       };
       _pendingApprovals.set(id, entry);
@@ -1831,29 +2353,90 @@ function _createSession(key, cwd) {
     return cancelled;
   }
 
-  /** Backstop: if no result shows up within the grace window after an interrupt, force-
-   * settle the head turn (keeping _queryBusy from wedging forever) and mark a tombstone
-   * so the result that eventually arrives is discarded instead of settling the next turn. */
+  /** Backstop: if no result shows up within the grace window after an interrupt, settle
+   * the head turn (keeping _queryBusy from wedging forever) and mark the generation
+   * suspect — the CLI never answered our Stop, so the child may be wedged. The actual
+   * teardown is deferred to the next push (_startTurn) so we never SIGTERM a child that
+   * was merely slow to unwind; the rebuild resumes _sessionId. A tombstone discards the
+   * late result if it ever arrives. */
   function _armSettleGrace() {
     _clearGraceTimer();
     _settleGraceTimer = setTimeout(() => {
       _settleGraceTimer = null;
       const rec = _pendingTurns[0];
       if (!rec || !rec.interrupted) return;
-      console.warn('[sdk-manager] no result within interrupt grace — force-settling the turn');
-      _lateResultTombstones++;
+      console.warn('[sdk-manager] no result within interrupt grace — settling the turn and marking the generation suspect');
+      _lateResultEpoch = rec.epoch; // discard this generation's late result, never a later turn's
       _pendingTurns.shift();
       _settleTurn(rec);
+      _emitAgentLoopEnd(rec, 'interrupt-timeout');
       _queryBusy = false;
+      _suspectGeneration = true;
       // The CLI never answered the interrupt — no result is coming, so clear the
       // spinner here rather than waiting on a dead signal.
-      _announceSessionState('idle');
+      _announceSessionState('idle', rec);
+      _clearActivity();
       if (_pendingTurns.length === 0) _clearTurnWatchdog();
       _maybeDrain();
     }, INTERRUPT_GRACE_MS);
     if (_settleGraceTimer.unref) _settleGraceTimer.unref();
   }
 
+  /** Lost-result backstop: the CLI announced session_state_changed('idle') (turn over,
+   * tools included) but never produced a result message for our pending FIFO. Give the
+   * result a short grace to arrive (frame ordering at turn end is not guaranteed), then
+   * settle as a retryable failure — without this _queryBusy would wedge forever now that
+   * the fixed silence watchdog is gone. */
+  function _armLostResultBackstop() {
+    const GRACE_MS = 5000;
+    // Capture the pending turn at arm time and re-verify identity at fire time: a stale
+    // backstop from turn A must never settle turn B (which may be parked on the SAME idle
+    // state). The interrupt-grace path owns user-cancelled turns — skip those here.
+    const armedRec = _pendingTurns[0] || null;
+    const armedSeq = _inboundMsgSeq; // any message arriving after arming bumps this
+    _lostResultTimer = setTimeout(() => {
+      _lostResultTimer = null;
+      const rec = _pendingTurns[0];
+      if (!rec || rec !== armedRec || rec.interrupted) return;   // stale arm / different turn / user-cancelled
+      if (_queryBusy === false) return;
+      if (_lastSessionState !== 'idle') return; // a newer turn started running — not lost
+      // Mitigation for the uncorrelatable-idle hazard: if the accepted idle actually
+      // belonged to the PREVIOUS turn (the new turn's `running` landed first, so
+      // cliStateSeen was already true and the gate passed it), the head turn may still
+      // be alive. A message arriving after arming proves the head turn is producing
+      // work — not lost. Disarm rather than convict it as turn-stuck. (armedSeq is read
+      // inside _processMessage, BEFORE the drain loop increments the seq for the very
+      // idle that armed us — so exactly ONE bump is expected from the arming message;
+      // anything beyond it is post-arm activity.)
+      if (_inboundMsgSeq > armedSeq + 1) return;
+      console.warn('[sdk-manager] session idle but a turn result never arrived — settling as lost result');
+      // Mark the head turn's epoch as owing a result: without it a late result would
+      // consume the NEXT turn's FIFO record (settling it early and mispairing turn-end).
+      // Binding to the epoch (not a count) is the fix for the swallowed-next-result bug —
+      // this result never arriving must not let the debt outlive its generation.
+      if (_pendingTurns[0]) _lateResultEpoch = _pendingTurns[0].epoch;
+      const lostRecs = [..._pendingTurns];
+      _settleAllTurns();
+      _clearActivity();
+      for (const r of lostRecs) _emitAgentLoopEnd(r, 'lost-result');
+      const retryable = !!(_sessionId || _launchResume);
+      _lastFailedTurn = {
+        turnId: rec.id || null, retryable, apiStatus: rec.apiRetry?.lastStatus ?? null,
+        attempt: rec.apiRetry?.attempt || 0, maxRetries: rec.apiRetry?.maxRetries || 0,
+        code: 'turn-stuck', ts: Date.now(),
+      };
+      _notifyQueryError(new Error('The turn ended without a result; you can retry it.'), {
+        code: 'turn-stuck', retryable, turnId: rec.id || null,
+      });
+      _maybeDrain();
+    }, GRACE_MS);
+    if (_lostResultTimer.unref) _lostResultTimer.unref();
+  }
+
+  function _clearLostResultBackstop() {
+    if (_lostResultTimer) { clearTimeout(_lostResultTimer); _lostResultTimer = null; }
+  }
+
   /**
    * Interrupt the current turn (user clicked the Stop button) while KEEPING the
    * session alive: the resident query is a streaming-input session, so interrupt()
@@ -1988,6 +2571,35 @@ function _createSession(key, cwd) {
     _broadcastQueueState();
   }
 
+  /**
+   * Manual [retry] of the last failed turn. The original user message is still in the
+   * session history (the CLI closed the failed turn with a synthetic API-error entry and
+   * stayed alive), so we do NOT resend it — we push a tiny synthetic continue instruction
+   * that makes the model redo the interrupted step with full context. Refuses with a
+   * reason unless there is a retryable recorded failure and the session is idle.
+   */
+  async function _retryInterruptedTurn(turnId = null) {
+    if (_queryBusy || _dispatchingStarting || _dispatching) return { ok: false, reason: 'busy' };
+    if (_switching) return { ok: false, reason: 'busy' }; // a session switch must not race a retry push
+    if (!_lastFailedTurn) return { ok: false, reason: 'nothing-to-retry' };
+    if (turnId && _lastFailedTurn.turnId && turnId !== _lastFailedTurn.turnId) return { ok: false, reason: 'stale' };
+    if (_lastFailedTurn.retryable === false) return { ok: false, reason: 'not-retryable' };
+    if (!_sessionId && !_launchResume) return { ok: false, reason: 'no-session' };
+    const retryOf = _lastFailedTurn.turnId; // snapshot BEFORE the await (a new turn mutates state)
+    _suppressDrain = false;
+    const { started, promise, turnId: newTurnId } = await _startTurn(RETRY_CONTINUE_PROMPT);
+    if (!started) return { ok: false, reason: 'not-delivered' };
+    // Stamp the lineage on the new turn's record so the result branch's `recovered`
+    // frame can name the FAILED turn (the frontend matches cleanup by retryOf).
+    // Look the new turn up by id (not index) — a fast result could have shifted the FIFO
+    // in the microtask gap, and the retryOf stamp must land on the retry turn itself.
+    const newRec = _pendingTurns.find(r => r.id === newTurnId) || null;
+    if (newRec) newRec.retryOf = retryOf;
+    _broadcast({ type: 'sdk-retry-state', phase: 'recovering', turnId: newTurnId, retryOf, ts: Date.now() });
+    promise.catch((err) => reportSwallowed('sdk-manager.retry-turn', err));
+    return { ok: true, turnId: newTurnId };
+  }
+
   /**
    * Switch the session to a different session id (web "resume session" entry — SDK-mode
    * counterpart of the PTY /resume injection). options.resume only applies at query
@@ -2015,6 +2627,9 @@ function _createSession(key, cwd) {
       _lastInitSnapshot = null; // don't replay the OLD session's sdk-init to the new one
       _lastSkillsSnapshot = null; // same for the skill surface
       _lastSessionState = null; // same for the session-state snapshot — new session starts idle
+      _clearStateHeartbeat();
+      _suspectGeneration = false;
+      _lastFailedTurn = null; // the failure belongs to the outgoing session — never retry it into this one
       _clearContextUsage('session-switched');
       _clearMcpStatus('session-switched');
       _clearQueued(); // broadcasts the emptied queue-state
@@ -2042,11 +2657,16 @@ function _createSession(key, cwd) {
     // legit idle). Skip the broadcast when nothing was ever announced.
     if (_lastSessionState && _lastSessionState !== 'idle') _announceSessionState('idle');
     _lastSessionState = null;
+    _clearStateHeartbeat();
+    _clearActivity();
+    _lastTurnStartedAt = 0;
     _clearContextUsage('session-switched');
     _clearMcpStatus('session-switched');
     _pendingTurns = [];
-    _lateResultTombstones = 0;
+    _lateResultEpoch = 0; // session boundary: a stale debt must not follow into the new session
     _consecutiveDeaths = 0;
+    _suspectGeneration = false;
+    _lastFailedTurn = null;
     _clearGraceTimer();
     _clearTurnWatchdog();
     const hadQueued = _messageQueue.length > 0 || !!_dispatching;
@@ -2099,7 +2719,8 @@ function _createSession(key, cwd) {
     getSdkInitSnapshot: () => _lastInitSnapshot,
     getSessionStateSnapshot: () => {
       if (!_lastSessionState) return null;
-      return { type: 'sdk-session-state', state: _lastSessionState, sessionId: _sessionId || null, cwd: _cwd };
+      const head = _pendingTurns[0] || null;
+      return { type: 'sdk-session-state', state: _lastSessionState, sessionId: _sessionId || null, cwd: _cwd, instanceKey, turnId: _currentTurnId(), turnStartedAt: head ? head.startedAt : _lastTurnStartedAt, pendingApprovals: _pendingApprovals.size };
     },
     getContextUsageSnapshot: () => _lastContextUsage,
     getMcpStatusSnapshot: () => _lastMcpStatus,
@@ -2127,6 +2748,7 @@ function _createSession(key, cwd) {
     },
     switchToSession: _switchToSession,
     getSessionId: () => _sessionId,
+    retryInterruptedTurn: _retryInterruptedTurn,
     runEphemeralTurn: _runEphemeralTurn,
     close: () => {
       for (const { id, kind } of _cancelAllApprovals()) {
@@ -2234,6 +2856,8 @@ export function __isEphemeralHostForTests(cwd) {
  * @param {function} deps.broadcastWs — (msg) => void, terminal-WS broadcast for approvals
  * @param {string} [deps.permissionMode]
  * @param {function} [deps.runWaterfallHook] — plugin waterfall (onPlanRequest/onAskRequest/onPermRequest)
+ * @param {function} [deps.onAgentLoopStart] — ({sessionId, ts, cwd, instanceKey, turnId, turnStartedAt}) => void, fired once per accepted turn
+ * @param {function} [deps.onAgentLoopEnd] — (same + reason) => void, fired once at the turn's real settlement
  * @param {object} [deps.env] — child env (must already contain ANTHROPIC_BASE_URL → ccv proxy)
  * @param {object} [deps.settings] — merged Settings object (env.ANTHROPIC_BASE_URL double-injection)
  * @param {string} [deps.model] — --model lifted from user args (options.model)
@@ -2243,7 +2867,7 @@ export function __isEphemeralHostForTests(cwd) {
  *   must come from the same selection as PTY mode, else the SDK spawns a PATH claude that
  *   host security tooling (e.g. agent-security headless guards) may SIGKILL on spawn
  */
-export function initSdkSession(cwd, projectName, { onTurnEnd, onQueryError, broadcastWs, permissionMode, runWaterfallHook, env, settings, model, launchResume, userArgs, claudeExecutable } = {}) {
+export function initSdkSession(cwd, projectName, { onTurnEnd, onQueryError, broadcastWs, permissionMode, runWaterfallHook, onAgentLoopStart, onAgentLoopEnd, env, settings, model, launchResume, userArgs, claudeExecutable } = {}) {
   void projectName; // reserved (display name comes from the wire path)
   // Process-global callbacks (cli.js registers one wiring; every session reuses it). Only
   // OVERWRITE when a callback is actually passed — a later per-workspace init (the launch
@@ -2253,6 +2877,12 @@ export function initSdkSession(cwd, projectName, { onTurnEnd, onQueryError, broa
   if (onQueryError !== undefined) _onQueryError = onQueryError || null;
   if (broadcastWs !== undefined) _broadcastWs = broadcastWs;
   if (runWaterfallHook !== undefined) _runWaterfallHook = runWaterfallHook || null;
+  if (onAgentLoopStart !== undefined) _onAgentLoopStart = onAgentLoopStart || null;
+  if (onAgentLoopEnd !== undefined) _onAgentLoopEnd = onAgentLoopEnd || null;
+  // Restore any callback stopSession() cleared from the durable process wiring (cli.js's
+  // registration). A workspace stop→relaunch omits these callbacks, so without this every
+  // sdk-* frame would silently stop broadcasting after returning to the workspace list.
+  _adoptProcessWiring();
   // Register this workspace's session (per-cwd, re-using the record on re-init) and make
   // it active. init() adopts the launch config and tears down ONLY this session's prior
   // generation (tests / hot reload) — other workspaces' sessions are untouched.
@@ -2430,6 +3060,8 @@ export function stopSession() {
   _onQueryError = null;
   _broadcastWs = null;
   _runWaterfallHook = null;
+  _onAgentLoopStart = null;
+  _onAgentLoopEnd = null;
 }
 
 /**
@@ -2546,6 +3178,22 @@ export function getSessionId(anchor) {
   return sess ? sess.getSessionId() : null;
 }
 
+/**
+ * Manual [retry] of the last failed turn on the active (or anchored) session. Pushes a
+ * synthetic continue instruction instead of resending the user's original message.
+ * Returns the session's { ok, reason? , turnId? } verdict.
+ */
+export async function retryInterruptedTurn(turnId, anchor) {
+  if (!_query) return { ok: false, reason: 'unavailable' };
+  const sess = anchor ? _sessionForAnchor(anchor) : _active();
+  if (!sess) return { ok: false, reason: 'not-found' };
+  const r = await sess.retryInterruptedTurn(turnId);
+  // Only a SUCCESSFUL retry re-routes the process-wide active session — a rejected retry
+  // (busy/stale/no-session) must not steal the active anchor from the foreground view.
+  if (r && r.ok && anchor && sess.key !== _activeKey) _activeKey = sess.key;
+  return r;
+}
+
 /**
  * The last sdk-init snapshot for WS reconnect replay. No anchor → active session;
  * with an anchor → that session. Returns null if no init has been announced yet