@threadbase-sh/streamer 1.53.1 → 1.54.0

package/dist/index.d.cts

@@ -169,6 +169,24 @@ declare function isProviderName(value: unknown): value is ProviderName;
 declare function isProviderResumable(_provider: string | null | undefined, availabilityResumable: boolean): boolean;
 
 type SessionStatus = "running" | "waiting_input" | "idle";
+/**
+ * Phase axis *inside* `status === "running"` — what the agent is doing during a
+ * turn. Deliberately a separate field rather than new SessionStatus members:
+ * VALID_STATUSES rejects unknown values and the store drops sessions outside
+ * the requested set, so a new status string would make those sessions vanish
+ * from already-shipped apps. Additive fields are safe; additive values in a
+ * union a shipped client filters on are not.
+ *
+ * The full set is defined here even though Codex only ever emits `working`
+ * (its status bar is binary — Ready/Working, and claiming otherwise would be
+ * invention). Defining it up front keeps a two-valued provider from fixing the
+ * field's shape before Claude's richer footer lands. Consumers must ignore an
+ * unrecognised value rather than coerce it.
+ *
+ * This union lives in exactly one place. Two independently-maintained copies of
+ * a TUI-derived grammar have already drifted once (tb-mobile PR #647).
+ */
+type AgentPhase = "thinking" | "streaming" | "hooks" | "acting" | "working";
 /**
  * Process-lifetime axis for a managed session (C1 durable session runtime).
  * Orthogonal to SessionStatus — see SessionResponse.lifecycle for why the two
@@ -233,6 +251,20 @@ interface ManagedSession {
      */
     statusSource?: StatusSource$1;
     statusUpdatedAt?: Date;
+    /**
+     * Agent phase within a running turn, scraped from the rendered screen.
+     * Optional internally (every existing construction site predates it), but
+     * managedToResponse emits it unconditionally as `?? null` — on the wire
+     * absence must never be a third state, because the client merges session
+     * frames and a merge cannot express a removed key.
+     *
+     * Cleared in markReady() for the running -> waiting_input turn end, which is
+     * the only exit a runner observes on screen. Every other way out of `running`
+     * — handleExit, putOnHold, failStartup — is enforced by SessionStore
+     * .updateManaged() instead: a phase exists only while the status is
+     * `running`, so leaving it clears the field.
+     */
+    subStatus?: AgentPhase | null;
     filePath?: string;
     resumedFromConversationId?: string;
     /**
@@ -339,6 +371,28 @@ type WSMessage = {
     stage?: Stage | string;
     stalledSinceMs?: number;
     reworkAttempt?: number;
+}
+/**
+ * Agent phase changed within a running turn. Scoped to that session's
+ * subscribers, like terminal_output and user_message.
+ *
+ * A minimal frame rather than a SessionResponse copy, deliberately:
+ * managedToResponse recomputes `elapsedMs` from `new Date()` on every call
+ * for a live session, so a session copy would differ on every tick whether
+ * or not the phase changed — and a client that merges frames would get a
+ * fresh object identity several times a second, re-rendering every consumer
+ * for the whole turn.
+ *
+ * `phase` is always present and is `null` when there is no phase. Absence
+ * must never carry meaning: clients merge session state, and a merge cannot
+ * express a removed key, so an omitted field would keep its previous value
+ * and the indicator would latch on a finished turn.
+ */
+ | {
+    type: "session_phase";
+    sessionId: string;
+    phase: AgentPhase | null;
+    updatedAt: string;
 } | {
     type: "session_list";
     sessions: readonly SessionResponse[];
@@ -504,6 +558,20 @@ interface SessionResponse {
      * Live sessions only.
      */
     permissionMode?: string;
+    /**
+     * Agent phase within a running turn, scraped from the rendered PTY screen.
+     *
+     * NOT optional, and always serialised — `null` when there is no phase. A
+     * client that merges session frames (`{...prev, ...next}`) cannot express a
+     * removed key, so an omitted field would keep its previous value and the
+     * indicator would latch on a finished turn. That is the bug tb-mobile PR #647
+     * shipped; absence must never carry meaning here.
+     *
+     * Consequently this must NOT be moved into the `...(x != null && { x })`
+     * guard block in managedToResponse: `!= null` catches null and undefined
+     * alike and would convert an explicit clear back into absence.
+     */
+    subStatus: AgentPhase | null;
     account?: string;
     messageCount?: number;
     preview?: string;
@@ -630,6 +698,24 @@ interface PTYManagerOptions {
         options: PermissionOption[];
         cursor?: number;
     } | null) => void;
+    /**
+     * Fired when the agent's phase within a running turn changes, including to
+     * `null` at turn end. Additive; absent in tests that omit it.
+     *
+     * Deliberately NOT routed through onStatusChange, even though that callback
+     * already exists and is already relayed across the pty-host boundary. Its
+     * handler writes a DB row per invocation with no same-status guard, refreshes
+     * the scanner index, broadcasts globally, and pokes the APNs and push
+     * notifiers — machinery built for a handful of transitions per session, not
+     * for a signal that can fire every SCRAPE_THROTTLE_MS.
+     *
+     * The server must broadcast this to that session's subscribers only
+     * (wsHub.broadcastToClients), as a minimal frame rather than a SessionResponse
+     * copy: managedToResponse recomputes elapsedMs on every call, so a session
+     * copy would differ every tick and re-render every client consumer of that
+     * session for the whole turn.
+     */
+    onPhaseChange?: (sessionId: string, phase: AgentPhase | null) => void;
     onLiveQuestion?: (sessionId: string, questions: AskQuestion[]) => void;
     onLiveQuestionGone?: (sessionId: string) => void;
     onUserMessage?: (sessionId: string, text: string, ts: number) => void;
@@ -1942,6 +2028,7 @@ declare class PTYManager implements SessionRunner {
     private onStatusChange;
     private onReady;
     private onPermissionChange;
+    private onPhaseChange;
     private onLiveQuestion;
     private onLiveQuestionGone;
     private onUserMessage;
@@ -1986,6 +2073,15 @@ declare class PTYManager implements SessionRunner {
     private recheckReadyFromScreen;
     private armReadyFallback;
     private clearReadyFallback;
+    /**
+     * Record the agent's phase and notify only on a real change.
+     *
+     * The change guard is load-bearing, not an optimisation: the scrape pass runs
+     * on every chunk, so an unguarded setter would fire the callback — and the
+     * WS frame behind it — several times a second for the entire duration of a
+     * turn while reporting the same value.
+     */
+    private setPhase;
     private markReady;
     private handleExit;
 }
@@ -2375,4 +2471,4 @@ declare class StreamerServer {
     private applyLiveSessionSetting;
 }
 
-export { type AgentClient, type AgentClientOpts, type AgentConfig, type AppendArgs, type AskOption, type AskQuestion, CLAUDE_CODE_PROVIDER, CODEX_CLI_PROVIDER, type CacheAlertResolveAction, type ConversationListResponse, ConversationWatcher, type ConversationWriter, type DbConfig, type DiscoveredProcess, LiveSessionManager, type ManagedSession, PTYManager, type PTYManagerOptions, type PermissionOption, type ProcessLiveness, type ProgressDedupeLRU, type ProviderName, type ServerConfig, type ServerWarmingUpResponse, type ServerWarmupState, type SessionActivity, type SessionCursor, type SessionLifecycle, type SessionListPage, type SessionListQuery, type SessionOwnership, type SessionResponse, type SessionRunner, type SessionSortKey, type SessionStatus, SessionStore, type SortOrder, type StartForkSessionOptions, type StartFreshSessionOptions, type StartSessionOptions, type StatusConfidence, type StatusSource$1 as StatusSource, StreamerServer, type UserMessage, WSHub, type WSMessage, confidenceForSource, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };
+export { type AgentClient, type AgentClientOpts, type AgentConfig, type AgentPhase, type AppendArgs, type AskOption, type AskQuestion, CLAUDE_CODE_PROVIDER, CODEX_CLI_PROVIDER, type CacheAlertResolveAction, type ConversationListResponse, ConversationWatcher, type ConversationWriter, type DbConfig, type DiscoveredProcess, LiveSessionManager, type ManagedSession, PTYManager, type PTYManagerOptions, type PermissionOption, type ProcessLiveness, type ProgressDedupeLRU, type ProviderName, type ServerConfig, type ServerWarmingUpResponse, type ServerWarmupState, type SessionActivity, type SessionCursor, type SessionLifecycle, type SessionListPage, type SessionListQuery, type SessionOwnership, type SessionResponse, type SessionRunner, type SessionSortKey, type SessionStatus, SessionStore, type SortOrder, type StartForkSessionOptions, type StartFreshSessionOptions, type StartSessionOptions, type StatusConfidence, type StatusSource$1 as StatusSource, StreamerServer, type UserMessage, WSHub, type WSMessage, confidenceForSource, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };

package/dist/index.d.ts

@@ -169,6 +169,24 @@ declare function isProviderName(value: unknown): value is ProviderName;
 declare function isProviderResumable(_provider: string | null | undefined, availabilityResumable: boolean): boolean;
 
 type SessionStatus = "running" | "waiting_input" | "idle";
+/**
+ * Phase axis *inside* `status === "running"` — what the agent is doing during a
+ * turn. Deliberately a separate field rather than new SessionStatus members:
+ * VALID_STATUSES rejects unknown values and the store drops sessions outside
+ * the requested set, so a new status string would make those sessions vanish
+ * from already-shipped apps. Additive fields are safe; additive values in a
+ * union a shipped client filters on are not.
+ *
+ * The full set is defined here even though Codex only ever emits `working`
+ * (its status bar is binary — Ready/Working, and claiming otherwise would be
+ * invention). Defining it up front keeps a two-valued provider from fixing the
+ * field's shape before Claude's richer footer lands. Consumers must ignore an
+ * unrecognised value rather than coerce it.
+ *
+ * This union lives in exactly one place. Two independently-maintained copies of
+ * a TUI-derived grammar have already drifted once (tb-mobile PR #647).
+ */
+type AgentPhase = "thinking" | "streaming" | "hooks" | "acting" | "working";
 /**
  * Process-lifetime axis for a managed session (C1 durable session runtime).
  * Orthogonal to SessionStatus — see SessionResponse.lifecycle for why the two
@@ -233,6 +251,20 @@ interface ManagedSession {
      */
     statusSource?: StatusSource$1;
     statusUpdatedAt?: Date;
+    /**
+     * Agent phase within a running turn, scraped from the rendered screen.
+     * Optional internally (every existing construction site predates it), but
+     * managedToResponse emits it unconditionally as `?? null` — on the wire
+     * absence must never be a third state, because the client merges session
+     * frames and a merge cannot express a removed key.
+     *
+     * Cleared in markReady() for the running -> waiting_input turn end, which is
+     * the only exit a runner observes on screen. Every other way out of `running`
+     * — handleExit, putOnHold, failStartup — is enforced by SessionStore
+     * .updateManaged() instead: a phase exists only while the status is
+     * `running`, so leaving it clears the field.
+     */
+    subStatus?: AgentPhase | null;
     filePath?: string;
     resumedFromConversationId?: string;
     /**
@@ -339,6 +371,28 @@ type WSMessage = {
     stage?: Stage | string;
     stalledSinceMs?: number;
     reworkAttempt?: number;
+}
+/**
+ * Agent phase changed within a running turn. Scoped to that session's
+ * subscribers, like terminal_output and user_message.
+ *
+ * A minimal frame rather than a SessionResponse copy, deliberately:
+ * managedToResponse recomputes `elapsedMs` from `new Date()` on every call
+ * for a live session, so a session copy would differ on every tick whether
+ * or not the phase changed — and a client that merges frames would get a
+ * fresh object identity several times a second, re-rendering every consumer
+ * for the whole turn.
+ *
+ * `phase` is always present and is `null` when there is no phase. Absence
+ * must never carry meaning: clients merge session state, and a merge cannot
+ * express a removed key, so an omitted field would keep its previous value
+ * and the indicator would latch on a finished turn.
+ */
+ | {
+    type: "session_phase";
+    sessionId: string;
+    phase: AgentPhase | null;
+    updatedAt: string;
 } | {
     type: "session_list";
     sessions: readonly SessionResponse[];
@@ -504,6 +558,20 @@ interface SessionResponse {
      * Live sessions only.
      */
     permissionMode?: string;
+    /**
+     * Agent phase within a running turn, scraped from the rendered PTY screen.
+     *
+     * NOT optional, and always serialised — `null` when there is no phase. A
+     * client that merges session frames (`{...prev, ...next}`) cannot express a
+     * removed key, so an omitted field would keep its previous value and the
+     * indicator would latch on a finished turn. That is the bug tb-mobile PR #647
+     * shipped; absence must never carry meaning here.
+     *
+     * Consequently this must NOT be moved into the `...(x != null && { x })`
+     * guard block in managedToResponse: `!= null` catches null and undefined
+     * alike and would convert an explicit clear back into absence.
+     */
+    subStatus: AgentPhase | null;
     account?: string;
     messageCount?: number;
     preview?: string;
@@ -630,6 +698,24 @@ interface PTYManagerOptions {
         options: PermissionOption[];
         cursor?: number;
     } | null) => void;
+    /**
+     * Fired when the agent's phase within a running turn changes, including to
+     * `null` at turn end. Additive; absent in tests that omit it.
+     *
+     * Deliberately NOT routed through onStatusChange, even though that callback
+     * already exists and is already relayed across the pty-host boundary. Its
+     * handler writes a DB row per invocation with no same-status guard, refreshes
+     * the scanner index, broadcasts globally, and pokes the APNs and push
+     * notifiers — machinery built for a handful of transitions per session, not
+     * for a signal that can fire every SCRAPE_THROTTLE_MS.
+     *
+     * The server must broadcast this to that session's subscribers only
+     * (wsHub.broadcastToClients), as a minimal frame rather than a SessionResponse
+     * copy: managedToResponse recomputes elapsedMs on every call, so a session
+     * copy would differ every tick and re-render every client consumer of that
+     * session for the whole turn.
+     */
+    onPhaseChange?: (sessionId: string, phase: AgentPhase | null) => void;
     onLiveQuestion?: (sessionId: string, questions: AskQuestion[]) => void;
     onLiveQuestionGone?: (sessionId: string) => void;
     onUserMessage?: (sessionId: string, text: string, ts: number) => void;
@@ -1942,6 +2028,7 @@ declare class PTYManager implements SessionRunner {
     private onStatusChange;
     private onReady;
     private onPermissionChange;
+    private onPhaseChange;
     private onLiveQuestion;
     private onLiveQuestionGone;
     private onUserMessage;
@@ -1986,6 +2073,15 @@ declare class PTYManager implements SessionRunner {
     private recheckReadyFromScreen;
     private armReadyFallback;
     private clearReadyFallback;
+    /**
+     * Record the agent's phase and notify only on a real change.
+     *
+     * The change guard is load-bearing, not an optimisation: the scrape pass runs
+     * on every chunk, so an unguarded setter would fire the callback — and the
+     * WS frame behind it — several times a second for the entire duration of a
+     * turn while reporting the same value.
+     */
+    private setPhase;
     private markReady;
     private handleExit;
 }
@@ -2375,4 +2471,4 @@ declare class StreamerServer {
     private applyLiveSessionSetting;
 }
 
-export { type AgentClient, type AgentClientOpts, type AgentConfig, type AppendArgs, type AskOption, type AskQuestion, CLAUDE_CODE_PROVIDER, CODEX_CLI_PROVIDER, type CacheAlertResolveAction, type ConversationListResponse, ConversationWatcher, type ConversationWriter, type DbConfig, type DiscoveredProcess, LiveSessionManager, type ManagedSession, PTYManager, type PTYManagerOptions, type PermissionOption, type ProcessLiveness, type ProgressDedupeLRU, type ProviderName, type ServerConfig, type ServerWarmingUpResponse, type ServerWarmupState, type SessionActivity, type SessionCursor, type SessionLifecycle, type SessionListPage, type SessionListQuery, type SessionOwnership, type SessionResponse, type SessionRunner, type SessionSortKey, type SessionStatus, SessionStore, type SortOrder, type StartForkSessionOptions, type StartFreshSessionOptions, type StartSessionOptions, type StatusConfidence, type StatusSource$1 as StatusSource, StreamerServer, type UserMessage, WSHub, type WSMessage, confidenceForSource, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };
+export { type AgentClient, type AgentClientOpts, type AgentConfig, type AgentPhase, type AppendArgs, type AskOption, type AskQuestion, CLAUDE_CODE_PROVIDER, CODEX_CLI_PROVIDER, type CacheAlertResolveAction, type ConversationListResponse, ConversationWatcher, type ConversationWriter, type DbConfig, type DiscoveredProcess, LiveSessionManager, type ManagedSession, PTYManager, type PTYManagerOptions, type PermissionOption, type ProcessLiveness, type ProgressDedupeLRU, type ProviderName, type ServerConfig, type ServerWarmingUpResponse, type ServerWarmupState, type SessionActivity, type SessionCursor, type SessionLifecycle, type SessionListPage, type SessionListQuery, type SessionOwnership, type SessionResponse, type SessionRunner, type SessionSortKey, type SessionStatus, SessionStore, type SortOrder, type StartForkSessionOptions, type StartFreshSessionOptions, type StartSessionOptions, type StatusConfidence, type StatusSource$1 as StatusSource, StreamerServer, type UserMessage, WSHub, type WSMessage, confidenceForSource, createAgentClient, createConversationWriter, createPool, createProgressDedupeLRU, createProgressRoutes, discoverClaudeProcesses, generateApiKey, getDbConfig, isDbEnabled, isProviderName, isProviderResumable, loadOrCreateApiKey, maskConnectionString, readAgentConfig, validateApiKey };

package/dist/index.js

@@ -1061,6 +1061,7 @@ function rememberedGateDigit(gate) {
 // src/services/questions/codexScreen.ts
 var CODEX_PROMPT_READY_TEXT = "Ready";
 var CODEX_BUSY_STATUS_RE = /\b(?:Starting|Working)\b/;
+var CODEX_WORKING_STATUS_RE = /\bWorking\b/;
 var CODEX_MCP_BOOT_RE = /Booting MCP|Starting MCP servers/i;
 var CODEX_TRUST_GATE_REGEX = /trust the contents/i;
 var CODEX_HOOKS_GATE_REGEX = /hooks need review/i;
@@ -1097,12 +1098,15 @@ function detectCodexBlockingPrompt(lines) {
 function codexStatusBarLine(lines) {
   return [...lines].reverse().find((l) => l.trim() !== "") ?? "";
 }
-function codexScreenBlocksComposer(lines) {
+function codexScreenPreTurn(lines) {
   const screenText = lines.join("\n");
   if (CODEX_HOOKS_GATE_REGEX.test(screenText) || CODEX_TRUST_GATE_REGEX.test(screenText)) {
     return true;
   }
-  if (CODEX_MCP_BOOT_RE.test(screenText)) return true;
+  return CODEX_MCP_BOOT_RE.test(screenText);
+}
+function codexScreenBlocksComposer(lines) {
+  if (codexScreenPreTurn(lines)) return true;
   return CODEX_BUSY_STATUS_RE.test(codexStatusBarLine(lines));
 }
 function codexScreenShowsReady(lines) {
@@ -1149,6 +1153,20 @@ function gateCard(gate, lines) {
   };
 }
 
+// src/services/questions/parseAgentPhase.ts
+function codexPhase(lines) {
+  if (codexScreenPreTurn(lines)) return null;
+  return CODEX_WORKING_STATUS_RE.test(codexStatusBarLine(lines)) ? "working" : null;
+}
+function claudePhase(_lines) {
+  return null;
+}
+function parseAgentPhase(lines, provider) {
+  if (provider === CODEX_CLI_PROVIDER) return codexPhase(lines);
+  if (provider === CLAUDE_CODE_PROVIDER) return claudePhase(lines);
+  return null;
+}
+
 // src/utils/debounce.ts
 function debounce(fn, waitMs) {
   let timer = null;
@@ -1193,6 +1211,7 @@ var CodexPtyRunner = class {
   sessions = /* @__PURE__ */ new Map();
   onOutput;
   onStatusChange;
+  onPhaseChange;
   onReady;
   // Broadcasts Codex's blocking startup gates (directory trust, hooks review)
   // as question cards; null dismisses the card once the gate leaves the screen.
@@ -1241,6 +1260,7 @@ var CodexPtyRunner = class {
   constructor(options = {}) {
     this.onOutput = options.onOutput;
     this.onStatusChange = options.onStatusChange;
+    this.onPhaseChange = options.onPhaseChange;
     this.onReady = options.onReady;
     this.onPermissionChange = options.onPermissionChange;
     this.onLiveQuestion = options.onLiveQuestion;
@@ -1808,6 +1828,9 @@ var CodexPtyRunner = class {
       );
       return;
     }
+    if (session.status === "running") {
+      this.setPhase(sessionId, session, parseAgentPhase(lines, CODEX_CLI_PROVIDER));
+    }
     const gate = CODEX_HOOKS_GATE_REGEX.test(screenText) ? "hooks" : CODEX_TRUST_GATE_REGEX.test(screenText) ? "trust" : null;
     if (gate) {
       this.handleGate(sessionId, session, gate, lines);
@@ -1922,11 +1945,25 @@ var CodexPtyRunner = class {
     });
     this.onPermissionChange?.(sessionId, card);
   }
+  /**
+   * Record the agent's phase and notify only on a real change. The guard is
+   * load-bearing, not an optimisation: detectScreenState runs on every chunk,
+   * so an unguarded setter would fire the WS frame behind this several times a
+   * second for a whole turn while reporting the same value. Same contract as
+   * PTYManager.setPhase — the two runners deliberately stay separate classes.
+   */
+  setPhase(sessionId, session, phase) {
+    const next = phase ?? null;
+    if ((session.subStatus ?? null) === next) return;
+    session.subStatus = next;
+    this.onPhaseChange?.(sessionId, next);
+  }
   markReady(sessionId, session, source, reason) {
     session.lastActivityAt = /* @__PURE__ */ new Date();
     session.status = "waiting_input";
     session.statusSource = source;
     session.statusUpdatedAt = /* @__PURE__ */ new Date();
+    this.setPhase(sessionId, session, null);
     this.log.info(`[codex.ready] ${sessionId.slice(0, 8)} ${reason}`, {
       event: "codex.ready",
       sessionId,
@@ -2018,12 +2055,16 @@ function toPublicSession(s) {
     ...s.lastActivityAt != null && { lastActivityAt: s.lastActivityAt },
     ...s.statusSource != null && { statusSource: s.statusSource },
     ...s.statusUpdatedAt != null && { statusUpdatedAt: s.statusUpdatedAt },
-    ...s.filePath != null && { filePath: s.filePath }
+    ...s.filePath != null && { filePath: s.filePath },
+    // Unconditional — see PTYManager's toPublicSession: a streamer re-adopting
+    // a surviving pty-host's sessions mid-turn has no other source for the
+    // phase, and the host's change guard will not re-emit it.
+    subStatus: s.subStatus ?? null
   };
 }
 
 // src/pty-host/protocol.ts
-var PTY_HOST_PROTOCOL_VERSION = 2;
+var PTY_HOST_PROTOCOL_VERSION = 3;
 function isHostEvent(message) {
   return "type" in message && message.type === "event";
 }
@@ -2261,6 +2302,9 @@ var RemoteSessionRunner = class _RemoteSessionRunner {
       case "permission-change":
         this.options.onPermissionChange?.(event.sessionId, event.gate);
         break;
+      case "phase-change":
+        this.options.onPhaseChange?.(event.sessionId, event.phase);
+        break;
       case "live-question":
         this.options.onLiveQuestion?.(event.sessionId, event.questions);
         break;
@@ -2659,6 +2703,7 @@ var PTYManager = class {
   onStatusChange;
   onReady;
   onPermissionChange;
+  onPhaseChange;
   onLiveQuestion;
   onLiveQuestionGone;
   onUserMessage;
@@ -2720,6 +2765,7 @@ var PTYManager = class {
     this.onStatusChange = options.onStatusChange;
     this.onReady = options.onReady;
     this.onPermissionChange = options.onPermissionChange;
+    this.onPhaseChange = options.onPhaseChange;
     this.onLiveQuestion = options.onLiveQuestion;
     this.onLiveQuestionGone = options.onLiveQuestionGone;
     this.onUserMessage = options.onUserMessage;
@@ -3226,6 +3272,10 @@ var PTYManager = class {
     }
     this.lastDetectAt.set(sessionId, nowMs);
     const lines = await this.getOutputLines(sessionId, 60);
+    const phaseSession = this.sessions.get(sessionId);
+    if (phaseSession?.status === "running") {
+      this.setPhase(sessionId, phaseSession, parseAgentPhase(lines, CLAUDE_CODE_PROVIDER));
+    }
     const askFooterOnScreen = lines.some((l) => /Enter to select/i.test(l));
     if (oscPermission || hasAskFooter || askFooterOnScreen) {
       this.log.debug?.(`[pty.prompt_detect] ${sessionId.slice(0, 8)} trigger`, {
@@ -3369,12 +3419,27 @@ var PTYManager = class {
   }
   // Transition a session from "running" to "waiting_input", clear pendingReady,
   // and flush any queued input. Idempotent: callers can invoke at any chunk.
+  /**
+   * Record the agent's phase and notify only on a real change.
+   *
+   * The change guard is load-bearing, not an optimisation: the scrape pass runs
+   * on every chunk, so an unguarded setter would fire the callback — and the
+   * WS frame behind it — several times a second for the entire duration of a
+   * turn while reporting the same value.
+   */
+  setPhase(sessionId, session, phase) {
+    const next = phase ?? null;
+    if ((session.subStatus ?? null) === next) return;
+    session.subStatus = next;
+    this.onPhaseChange?.(sessionId, next);
+  }
   markReady(sessionId, session, source, reason) {
     this.clearReadyFallback(sessionId);
     session.lastActivityAt = /* @__PURE__ */ new Date();
     session.status = "waiting_input";
     session.statusSource = source;
     session.statusUpdatedAt = /* @__PURE__ */ new Date();
+    this.setPhase(sessionId, session, null);
     const elapsedMs = Date.now() - (this.firstChunkAt.get(sessionId) ?? Date.now());
     this.log.info(`[pty.ready] ${sessionId.slice(0, 8)} ${reason} (elapsed=${elapsedMs}ms)`, {
       event: "pty.ready",
@@ -3438,7 +3503,12 @@ function toPublicSession2(s) {
     ...s.statusUpdatedAt != null && { statusUpdatedAt: s.statusUpdatedAt },
     ...s.filePath != null && { filePath: s.filePath },
     ...s.sessionName != null && { sessionName: s.sessionName },
-    ...s.firstMessageText != null && { firstMessageText: s.firstMessageText }
+    ...s.firstMessageText != null && { firstMessageText: s.firstMessageText },
+    // Unconditional: this shape crosses the pty-host boundary, and a streamer
+    // re-adopting a surviving host's sessions mid-turn has no other source for
+    // the phase — no snapshot or replay event carries it, and setPhase's change
+    // guard means the host will never re-emit it for the rest of that turn.
+    subStatus: s.subStatus ?? null
   };
 }
 
@@ -7910,6 +7980,12 @@ function conversationToResumableSession(c) {
     branch: c.branch ?? void 0,
     lastOutput: "",
     elapsedMs: 0,
+    // No PTY behind a cached conversation, so there is no phase — emitted
+    // explicitly for the same reason as in managedToResponse/discoveredToResponse:
+    // the client merges session frames, so an absent key keeps the previous
+    // value and the indicator latches. `GET /api/sessions/:id` serves this
+    // shape whenever the id is a conversation rather than a live session.
+    subStatus: null,
     promptCount: c.messageCount,
     startedAt: c.lastActivity,
     completedAt: null,
@@ -11868,6 +11944,15 @@ function createLiveSessionOptions(deps) {
         seq
       });
     },
+    onPhaseChange: (sessionId, phase) => {
+      deps.sessionStore.updateManaged(sessionId, { subStatus: phase });
+      deps.wsHub.broadcastToClients(deps.sessionSubscribers.get(sessionId) ?? [], {
+        type: "session_phase",
+        sessionId,
+        phase,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    },
     onUserMessage: (sessionId, text, ts) => {
       deps.wsHub.broadcastToClients(deps.sessionSubscribers.get(sessionId) ?? [], {
         type: "user_message",
@@ -13897,6 +13982,7 @@ var SessionStore = class {
     const session = this.managed.get(sessionId);
     if (!session) return null;
     Object.assign(session, updates);
+    if (updates.status != null && updates.status !== "running") session.subStatus = null;
     return session;
   }
   removeManaged(sessionId) {
@@ -14077,6 +14163,13 @@ function managedToResponse(s, ptyAttached) {
     promptCount: s.promptCount,
     startedAt: s.startedAt.toISOString(),
     completedAt: s.completedAt?.toISOString() ?? null,
+    // Unconditional, like completedAt above — do NOT move this into the
+    // `...(x != null && { x })` block below. That guard uses loose `!=`, which
+    // catches null as well as undefined, and would turn an explicit "no phase"
+    // back into an absent key. The client merges session frames, so an absent
+    // key keeps the previous value and the indicator latches on a finished
+    // turn — the tb-mobile PR #647 bug, arriving through the serialiser.
+    subStatus: s.subStatus ?? null,
     ptyAttached,
     ...s.projectId != null && { projectId: s.projectId },
     ...s.sessionName != null && { sessionName: s.sessionName },
@@ -14127,6 +14220,10 @@ function discoveredToResponse(d, conversationId) {
     // cannot see the process's prompt state.
     lifecycle: "detached",
     lifecycleSource: "probe",
+    // No PTY here, so nothing to scrape and no phase to report. Emitted
+    // explicitly rather than omitted, for the same reason as in
+    // managedToResponse: absence must never be a third state on the wire.
+    subStatus: null,
     projectPath: d.projectPath,
     projectName: d.projectName,
     branch: d.branch,