@askdkc/dsh-cli 0.11.7 → 0.12.0

package/node_modules/dsh-working-activity/src/status.ts

@@ -0,0 +1,1474 @@
+/**
+ * Pure activity state machine for the working-activity status line. Consumes
+ * session events (turn/step/tool/stream) plus agent running/idle transitions
+ * and renders a human-readable status line at any wall-clock instant. No I/O,
+ * no timers, no cordis — deterministic given the event stream and a clock.
+ * @module @deepseek-ai/dsh-working-activity/status
+ */
+
+import type { ActivityEvent, WaitingReason } from './activity-event.js'
+import {
+  actionFor, compactPhrase, continuePhrase, donePhrase, failPhrase, fmtDuration,
+  holidayPhrase, isGitTool, isNight, isWeekend, mixSlot, modelQuip, overflowPhrase, rarePhrase,
+  RARE_CHANCE, thinkingPhrase, toolOpeningPhrase, weekendPhrase, waitingPhrase, waitingReasonPhrase,
+  type PhraseSlot,
+} from './phrases.js'
+import { feedSessionEvent } from './compat/session-events.js'
+import { detectInputLanguage, isLang, langNow, t, terminalProgressLang, withProgressLang, type Lang } from './lang.js'
+
+/** Public status phases a UI can render. */
+export type ActivityPhase = 'idle' | 'waiting' | 'thinking' | 'tool' | 'done'
+
+/**
+ * Compatibility handle for {@link ActivityTracker.snapshot} output.
+ *
+ * The snapshot shape is private to this module; this number is the only part a
+ * consumer may rely on. Bump it whenever the emitted shape changes, so a
+ * persisted projection checkpoint from an older build is discarded (the host
+ * refolds the log) instead of being misread as the new shape.
+ */
+export const TRACKER_SNAPSHOT_VERSION = 6
+
+/** One snapshot of the model's activity, renderable by any UI. */
+export interface ActivityState {
+  /** Which activity phase the model is in right now. */
+  readonly phase: ActivityPhase
+  /** Full human-readable status line (plain text, no ANSI). */
+  readonly line: string
+  /** Short label of the current work (tool action or stage), when any. */
+  readonly label?: string
+  /** Detail fragment (path / command / search pattern), when any. */
+  readonly detail?: string
+  /** The playful phrase currently shown. */
+  readonly phrase?: string
+  /** Tools completed in the current turn. */
+  readonly toolCount: number
+  /** Wall-clock milliseconds since the current turn started (0 when idle). */
+  readonly turnElapsedMs: number
+  /** Wall-clock time the current phase started, for animations. */
+  readonly phaseStartedAt: number
+}
+
+/** Per-turn thinking/tooling split, exposed for done summaries and stats. */
+export interface TurnStats {
+  /** Milliseconds the model was thinking (between turn start and first tool / turn end). */
+  readonly thinkingMs: number
+  /** Milliseconds spent inside tool executions. */
+  readonly toolMs: number
+  /** Tools completed in the turn. */
+  readonly toolCount: number
+}
+
+/** Easter-egg toggles for the thinking phrase (pi extension parity). */
+export interface TrackerFeatures {
+  /** Rare 1/150 easter eggs. */
+  readonly rareEggs?: boolean
+  /** Weekend greetings on Sat/Sun. */
+  readonly weekend?: boolean
+  /** Date-matched holiday / Lunar New Year copy. */
+  readonly holidays?: boolean
+  /** Night-owl copy between 00:00 and 06:00. */
+  readonly nightPhrases?: boolean
+  /** Consecutive-tool streak badge. */
+  readonly combo?: boolean
+  /** Playful failure copy when the turn's last tool failed. */
+  readonly failPhrases?: boolean
+  /** Quips on a model route change. */
+  readonly modelQuips?: boolean
+  /** Comeback quip after the user interrupts. */
+  readonly continuePhrases?: boolean
+}
+
+/** Configuration knobs for the state machine (subset of plugin Config). */
+export interface TrackerConfig {
+  /** Detect progress language from accepted user messages, per session. */
+  readonly inputLanguage?: boolean
+  /** Existing projection language supplier, used outside input-following mode. */
+  readonly language?: () => Lang
+  /** Playful copy pool on/off; false renders plain functional labels. */
+  readonly phrases: boolean
+  /** Maximum characters of a detail fragment (paths/commands). */
+  readonly detailLimit: number
+  /** Hide the status line while idle. */
+  readonly showIdle: boolean
+  /** Easter-egg toggles; absent flags default to on. */
+  readonly features?: TrackerFeatures
+  /** User custom phrases appended to the base thinking pool. */
+  readonly customPhrases?: readonly string[]
+  /** Show an estimated tokens/s prefix while streaming (pi parity). */
+  readonly showTokPerSec?: boolean
+  /** Work reminder after this many turn-hours (0 = off). */
+  readonly workRemindAt?: number
+}
+
+/** A tool execution in flight. */
+interface ActiveTool {
+  readonly callId: string
+  readonly name: string
+  action: string
+  readonly detail: string
+  readonly isGit: boolean
+  readonly startedAt: number
+  /** Whether the tool failed; set on tool/result while the card lingers. */
+  failed: boolean
+  /** tool/result time when settled, else undefined. */
+  endedAt?: number
+}
+
+/** A tool that finished but keeps its card in the replay queue. */
+interface DoneTool {
+  readonly name: string
+  action: string
+  readonly detail: string
+  readonly failed: boolean
+  readonly endedAt: number
+  /** How long the tool ran; shown while the settled line lingers. */
+  readonly durationMs: number
+}
+
+/**
+ * The wire shape of {@link ActivityTracker.snapshot} — module-private on
+ * purpose. Consumers hand the value straight back to
+ * {@link ActivityTracker.restore}; `snapshot()` is typed as `unknown` so the
+ * field list never becomes published API that has to be kept stable.
+ */
+interface TrackerSnapshotShape {
+  readonly version: number
+  readonly progressLang: Lang
+  readonly phase: ActivityPhase
+  readonly phaseStartedAt: number
+  readonly turnStartedAt: number
+  readonly thinkingStartedAt: number
+  readonly thinkingMs: number
+  readonly toolMs: number
+  readonly toolCount: number
+  readonly activeTools: readonly ActiveTool[]
+  readonly doneQueue: readonly DoneTool[]
+  /** Thinking phases entered this turn — the rare egg shows in the first one. */
+  readonly thinkingPhases: number
+  /** When the turn's first tool started (drives the thinking→doing opening line). */
+  readonly firstToolStartedAt: number
+  readonly waitingFirstToken: boolean
+  readonly narratedText: string | null
+  readonly lastChunkAt: number
+  readonly recentStream: string
+  readonly turnTokens: number
+  readonly donePrefix: string
+  readonly pendingPhrase: string | null
+  readonly pendingUntil: number
+  readonly gitBranch: string | null
+  /** Last announced model route, so a restored tracker keeps the dedupe. */
+  readonly model: string | null
+  readonly streak: number
+  readonly lastToolEndAt: number
+  readonly maxStreak: number
+  readonly subagentCount: number
+  /** Current stall, or null (`WaitingReason` for the reason). */
+  readonly waitingReason: WaitingReason | null
+  /** When the current stall began (0 with none). */
+  readonly waitingReasonAt: number
+  readonly tokBuf: number
+  readonly tokWindowStart: number
+}
+
+/** Format one tool into its display fragment (`跑个命令 npm test`). */
+function toolFragment(tool: { action: string; detail: string }): string {
+  return tool.detail.length === 0 ? tool.action : `${tool.action} ${tool.detail}`
+}
+
+/** The phase vocabulary, for snapshot shape validation (see {@link ActivityTracker.restore}). */
+const PHASES: readonly ActivityPhase[] = ['idle', 'waiting', 'thinking', 'tool', 'done']
+
+/** Whether `value` is one of {@link PHASES}. */
+function isPhase(value: unknown): value is ActivityPhase {
+  return PHASES.includes(value as ActivityPhase)
+}
+
+/**
+ * Duration label for a settled tool: sub-second tools read in milliseconds.
+ *
+ * The shared `fmtDuration` is second-granular, which renders the measured
+ * median tool (87 ms) as a meaningless `0s` — the settled line exists to make
+ * that work visible, so it has to say how long it took.
+ * @param ms - Tool duration in milliseconds.
+ */
+function durationLabel(ms: number): string {
+  // Floor, not round: 999.6 ms is "999ms", not a "1000ms" that never happened.
+  return ms < 1000 ? `${Math.max(0, Math.floor(ms))}ms` : fmtDuration(ms)
+}
+
+/** Simple non-ANSI string shortener by grapheme count. */
+function shorten(value: string, limit: number): string {
+  const graphemes = Array.from(value)
+  if (graphemes.length <= limit) return value
+  return `${graphemes.slice(0, Math.max(0, limit - 1)).join('')}…`
+}
+
+/**
+ * Flatten model-written text for the single-line render path.
+ *
+ * The line is composed from text the model wrote (its `⏵` narration, the path
+ * or command inside a tool call), and it is displayed by a terminal and by the
+ * Web UI. So this is where that text stops being able to do anything but be
+ * read: complete ANSI/OSC sequences go first (stripping only their control
+ * bytes would leave `[31m` residue behind), every remaining C0/C1 control char
+ * becomes a space — a `\n` inside a multi-line shell command would otherwise
+ * split the status line in two — and whitespace collapses, because a render
+ * path is one line by definition.
+ * @param value - Raw model-written fragment.
+ * @returns the fragment, safe and single-line.
+ */
+function sanitizeFragment(value: string): string {
+  return value
+    .replace(/\u001B\][^\u0007]*(?:\u0007|\u001B\\)/gu, '')
+    .replace(/\u001B\[[0-?]*[ -/]*[@-~]/gu, '')
+    // eslint-disable-next-line no-control-regex -- deliberate: model text is untrusted render input
+    .replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+/**
+ * Extract a displayable detail fragment from a tool call's parsed arguments.
+ * @param toolName - Registry tool name.
+ * @param args - Parsed tool arguments (lossless JSON by registry contract).
+ */
+export function detailFor(toolName: string, args: Readonly<Record<string, unknown>> | undefined, limit: number): string {
+  if (args === undefined) return ''
+  const pickString = (...keys: readonly string[]): string => {
+    for (const key of keys) {
+      const value = args[key]
+      if (typeof value === 'string' && value.trim().length > 0) return sanitizeFragment(value)
+    }
+    return ''
+  }
+  const normalized = toolName.toLowerCase()
+  if (normalized === 'mcp' || normalized.startsWith('mcp__') || normalized.includes('__')) {
+    const action = pickString('action', 'tool', 'server', 'connect', 'describe')
+    return shorten(action, limit)
+  }
+  const path = pickString('path', 'file', 'file_path', 'filepath', 'target')
+  if (path.length > 0) return shorten(path, limit)
+  const command = pickString('command', 'cmd', 'cmdline')
+  if (command.length > 0) return shorten(command, limit)
+  const pattern = pickString('pattern', 'query', 'search')
+  if (pattern.length > 0) return shorten(pattern, limit)
+  const url = pickString('url')
+  if (url.length > 0) return shorten(url, limit)
+  if (/^(?:subagent|agent|task)$/i.test(toolName)) {
+    const description = pickString('description')
+    if (description.length > 0) return shorten(description, limit)
+    const prompt = pickString('prompt')
+    if (prompt.length > 0) return shorten(prompt, limit)
+  }
+  const named = pickString('name', 'server', 'tool', 'id', 'goal')
+  if (named.length > 0) return shorten(named, limit)
+  return ''
+}
+
+/**
+ * Track one agent's activity from its durable session events. Events from
+ * other sessions are ignored (the owning plugin feeds only the agent it
+ * displays). The tracker is deliberately single-agent: multi-session UIs
+ * instantiate one tracker per agent.
+ */
+export class ActivityTracker {
+  private progressLang: Lang = terminalProgressLang()
+  private phase: ActivityPhase = 'idle'
+  private phaseStartedAt = 0
+  private turnStartedAt = 0
+  private thinkingStartedAt = 0
+  private thinkingMs = 0
+  private toolMs = 0
+  private toolCount = 0
+  /** When the turn's first tool started; 0 until it does (see {@link toolOpening}). */
+  private firstToolStartedAt = 0
+  private activeTools = new Map<string, ActiveTool>()
+  private doneQueue: DoneTool[] = []
+  private thinkingPhases = 0
+  private waitingFirstToken = false
+  /** Latest `⏵` self-narration line extracted from the stream, or null. */
+  private narratedText: string | null = null
+  /** Wall-clock time of the most recent stream delta (narration freshness). */
+  private lastChunkAt = 0
+  /** Rolling window of VISIBLE text deltas, for `⏵` extraction (see onEvent). */
+  private recentStream = ''
+  /** Total tokens reported across the turn's assistant messages. */
+  private turnTokens = 0
+  /** Completion prefix drawn ONCE at turn end so the done line stays stable. */
+  private donePrefix = t('done-prefix')
+  /** One-off copy pinned by an external event (interrupt / model switch /
+   *  compaction / work reminder), shown until it expires. */
+  private pendingPhrase: string | null = null
+  private pendingUntil = 0
+  /** Git branch of the session cwd (fed by the host, best-effort). */
+  private gitBranch: string | undefined
+  /** Last model route announced, so a repeated selection stays quiet. */
+  private model: string | undefined
+  /** Consecutive fast tool streak (combo). */
+  private streak = 0
+  private lastToolEndAt = 0
+  private maxStreak = 0
+  /** Subagent (agent/task) calls in the current turn. */
+  private subagentCount = 0
+  /**
+   * Why the turn is stalled, when it is (retry / approval / compaction).
+   *
+   * A stall is state, not decoration: "waiting on the model" and "the model is
+   * waiting on YOU" need different copy, so it outranks the phrase pools and
+   * survives `phrases: false`.
+   */
+  private waitingReason: WaitingReason | undefined
+  /** When the current stall began (seeds its copy; 0 with no stall). */
+  private waitingReasonAt = 0
+  /** Streaming token estimate for the tps prefix. */
+  private tokBuf = 0
+  private tokWindowStart = 0
+
+  /**
+   * @param config - Behavioral knobs.
+   * @param now - Wall-clock supplier (injectable for tests).
+   * @param customActions - Exact-name custom action pools for {@link actionFor}.
+   */
+  constructor(
+    private readonly config: TrackerConfig,
+    private readonly now: () => number = Date.now,
+    private readonly customActions?: Readonly<Record<string, readonly string[]>>,
+  ) {}
+
+  /** The locale used by this session's line. Existing modes still follow /lang. */
+  language(): Lang {
+    return this.config.inputLanguage ? this.progressLang : (this.config.language?.() ?? langNow())
+  }
+
+  /** Agent transitioned to running/idle. */
+  onAgentStatus(status: 'idle' | 'running'): void {
+    if (status === 'idle') {
+      // The turn end already moved us to the done phase; idle only clears the
+      // lingering done card after its display window.
+      if (this.phase !== 'done') this.phase = 'idle'
+      return
+    }
+    if (this.phase === 'idle') {
+      this.phase = 'waiting'
+      this.phaseStartedAt = this.now()
+      this.waitingFirstToken = true
+    }
+  }
+
+  /** The user interrupted the running turn: show a comeback quip next. */
+  onInterrupted(): void {
+    if (!this.config.phrases) return
+    if ((this.config.features ?? {}).continuePhrases === false) return
+    this.pendingPhrase = continuePhrase()
+    this.pendingUntil = this.now() + PENDING_MS
+  }
+
+  /**
+   * The model was switched: quip for the new model id.
+   *
+   * Repeats are ignored. A `model/selection` event is logged whenever the host
+   * validates a selection — including a re-selection of the current model and
+   * every replay of the log — and re-announcing the same model would replace
+   * whatever the line is saying with a stale quip.
+   */
+  onModelSwitch(modelId: string): void {
+    if (modelId === this.model) return
+    this.model = modelId
+    if (!this.config.phrases) return
+    if ((this.config.features ?? {}).modelQuips === false) return
+    const quip = modelQuip(modelId)
+    if (quip !== null) {
+      this.pendingPhrase = quip
+      this.pendingUntil = this.now() + PENDING_MS
+    }
+  }
+
+  /** A context compaction finished (or overflowed): quip about it. */
+  onCompact(kind: 'done' | 'overflow'): void {
+    // The compaction stall (if any) is over either way.
+    if (this.waitingReason === 'compaction') this.clearWaitingReason()
+    if (!this.config.phrases) return
+    this.pendingPhrase = kind === 'overflow' ? overflowPhrase() : compactPhrase()
+    this.pendingUntil = this.now() + PENDING_MS
+  }
+
+  /** Feed the session cwd's git branch (best-effort, host-resolved). */
+  onGitBranch(branch: string | undefined): void {
+    this.gitBranch = branch
+  }
+
+  /**
+   * Consume one normalized activity event. This is the state machine's only
+   * input: host payload shapes are normalized in `src/compat/*` first, so a
+   * host-line drift never reaches this switch.
+   */
+  onEvent(event: ActivityEvent): void {
+    if (event.kind === 'user-prompt') {
+      if (this.config.inputLanguage) {
+        const next = detectInputLanguage(event.text)
+        if (next !== undefined && next !== this.progressLang) {
+          this.progressLang = next
+          withProgressLang(next, () => {
+            for (const tool of this.activeTools.values()) {
+              tool.action = this.config.phrases ? actionFor(tool.name, this.customActions) : tool.name
+            }
+            for (const tool of this.doneQueue) {
+              tool.action = this.config.phrases ? actionFor(tool.name, this.customActions) : tool.name
+            }
+            this.donePrefix = t('done-prefix')
+          })
+          this.pendingPhrase = null
+        }
+      }
+      return
+    }
+    withProgressLang(this.language(), () => this.applyEvent(event))
+  }
+
+  private applyEvent(event: ActivityEvent): void {
+    switch (event.kind) {
+      case 'turn-start': {
+        const at = event.at
+        this.turnStartedAt = at
+        this.thinkingStartedAt = at
+        this.thinkingMs = 0
+        this.toolMs = 0
+        this.toolCount = 0
+        this.turnTokens = 0
+        this.activeTools.clear()
+        this.doneQueue = []
+        this.waitingFirstToken = true
+        this.narratedText = null
+        this.lastChunkAt = 0
+        this.recentStream = ''
+        // Eggs are once-per-turn and derived from the turn's seed, so a fresh
+        // turn only needs its phase counter cleared.
+        this.thinkingPhases = 0
+        this.firstToolStartedAt = 0
+        // Per-turn stats reset; the pending quip (interrupt/model/compact)
+        // survives across the turn boundary so it shows on the next think.
+        this.streak = 0
+        this.maxStreak = 0
+        this.subagentCount = 0
+        this.clearWaitingReason()
+        this.tokBuf = 0
+        this.tokWindowStart = at
+        this.setPhase('waiting', at)
+        return
+      }
+      case 'step-start':
+        // No phase change of its own: a step without streamed output stays
+        // waiting until its first delta promotes it.
+        return
+      case 'stream-start':
+        // A new attempt must not inherit the previous attempt's provisional
+        // text: the narration buffer and the token estimate are attempt-scoped.
+        // The phase is untouched — the first delta promotes waiting → thinking.
+        this.recentStream = ''
+        this.narratedText = null
+        this.tokBuf = 0
+        this.lastChunkAt = 0
+        return
+      case 'stream-delta': {
+        const at = event.at
+        this.lastChunkAt = at
+        // Output is flowing again — whatever stalled the turn is over.
+        this.clearWaitingReason()
+        if (this.waitingFirstToken) {
+          this.waitingFirstToken = false
+          // A delta that arrives while a tool runs must not steal the phase:
+          // models may stream text after a tool call inside the same attempt,
+          // and the tool is what the user is actually waiting on. The tool
+          // result hands the phase back to thinking on its own.
+          if (this.activeTools.size === 0) {
+            this.setPhase('thinking', at)
+            this.thinkingStartedAt = at
+          }
+        }
+        // Streaming token estimate for the tps prefix (pi parity).
+        this.tokBuf += estimateTokens(event.text)
+        // Only VISIBLE output narrates. The injected contract asks for the `⏵`
+        // line at the beginning of the *response body*, and the durable path
+        // (`assistant-settled`) already reads text blocks only — folding
+        // reasoning deltas in here made the line quote the model's private
+        // thinking back at the user. Reported live: the status line showed a
+        // half sentence from reasoning, because thinking about this very
+        // format means writing `⏵` about it.
+        if (event.stream !== 'text') return
+        this.recentStream = (this.recentStream + event.text).slice(-STREAM_BUFFER_CHARS)
+        const narration = extractNarration(this.recentStream)
+        if (narration !== null) this.narratedText = narration
+        return
+      }
+      case 'stream-reset': {
+        // An abandoned attempt (or a partial settlement) must not leave its
+        // provisional narration or token estimate behind for the next attempt.
+        this.recentStream = ''
+        this.narratedText = null
+        this.tokBuf = 0
+        this.lastChunkAt = 0
+        this.waitingFirstToken = true
+        if (this.activeTools.size === 0) this.setPhase('waiting', event.at)
+        return
+      }
+      case 'assistant-settled': {
+        const usage = event.usage
+        if (usage !== undefined) {
+          this.turnTokens += usage.inputTokens + usage.outputTokens
+            + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0)
+        }
+        // The settled text is where a projection (or a replayed log) recovers
+        // the narration: frames are live-only, this event is durable.
+        if (event.text !== undefined) {
+          const narration = extractNarration(event.text)
+          if (narration !== null) {
+            this.narratedText = narration
+            this.lastChunkAt = event.at
+          }
+        }
+        return
+      }
+      case 'tool-start': {
+        const at = event.at
+        if (this.phase === 'thinking' || this.phase === 'waiting') {
+          this.thinkingMs += at - this.thinkingStartedAt
+        }
+        // The turn's first tool is where "thinking" turns into "doing": its
+        // opening line is derived from this instant (see toolOpening).
+        if (this.firstToolStartedAt === 0) this.firstToolStartedAt = at
+        // Combo streak: consecutive tools within COMBO_GAP_MS count up.
+        this.streak = (this.lastToolEndAt > 0 && at - this.lastToolEndAt <= COMBO_GAP_MS)
+          ? this.streak + 1
+          : 1
+        if (this.streak > this.maxStreak) this.maxStreak = this.streak
+        if (/^(?:subagent|agent|task)$/i.test(event.name)) this.subagentCount += 1
+        const parsed = parseArguments(event.arguments)
+        const action = this.config.phrases ? actionFor(event.name, this.customActions) : event.name
+        const detail = detailFor(event.name, parsed, this.config.detailLimit)
+        const active: ActiveTool = {
+          callId: event.callId,
+          name: event.name,
+          action,
+          detail,
+          isGit: isGitTool(event.name, parsed),
+          startedAt: at,
+          failed: false,
+        }
+        this.activeTools.set(event.callId, active)
+        this.setPhase('tool', at)
+        return
+      }
+      case 'tool-end': {
+        const at = event.at
+        const callId = event.callId
+        const active = this.activeTools.get(callId)
+        if (active === undefined) return
+        active.failed = event.failed
+        active.endedAt = at
+        this.toolMs += at - active.startedAt
+        this.toolCount += 1
+        this.lastToolEndAt = at
+        this.doneQueue.push({
+          name: active.name,
+          action: active.action,
+          detail: active.detail,
+          failed: active.failed,
+          endedAt: at,
+          // Kept so the settled line can show how long it took: on real
+          // sessions the median tool is 87 ms, so the duration is most of what
+          // there is to read.
+          durationMs: Math.max(0, at - active.startedAt),
+        })
+        if (this.doneQueue.length > DONE_QUEUE_MAX) this.doneQueue.shift()
+        this.activeTools.delete(callId)
+        // An approval-parked tool resolved the moment it settled.
+        if (this.waitingReason === 'approval') this.clearWaitingReason()
+        if (this.activeTools.size === 0) {
+          // Back to thinking (or a trailing done card if the turn just closed).
+          this.setPhase('thinking', at)
+          this.thinkingStartedAt = at
+        }
+        return
+      }
+      case 'turn-end': {
+        const at = event.at
+        if (this.activeTools.size > 0) {
+          // Tools still running at turn end: count their elapsed time as tool time.
+          for (const tool of this.activeTools.values()) {
+            this.toolMs += Math.max(0, at - tool.startedAt)
+          }
+          this.activeTools.clear()
+        } else if (this.phase === 'thinking' || this.phase === 'waiting') {
+          this.thinkingMs += Math.max(0, at - this.thinkingStartedAt)
+        }
+        // Draw the completion prefix ONCE so repeated renders of the done line
+        // stay stable (a fresh random per render would make it flicker). The
+        // pools are language-aware, so the line matches the language the turn
+        // ended in.
+        const lastTool = this.doneQueue.at(-1)
+        if (this.config.phrases) {
+          this.donePrefix = lastTool?.failed
+            ? ((this.config.features ?? {}).failPhrases !== false ? failPhrase() : t('done-prefix'))
+            : donePhrase()
+        } else {
+          this.donePrefix = t('done-prefix')
+        }
+        if (event.interrupted === true) this.onInterrupted()
+        this.clearWaitingReason()
+        this.setPhase('done', at)
+        return
+      }
+      case 'route-change':
+        this.onModelSwitch(event.model)
+        return
+      case 'compaction':
+        this.onCompact(event.overflow === true ? 'overflow' : 'done')
+        return
+      case 'waiting-reason':
+        this.waitingReason = event.reason
+        this.waitingReasonAt = event.at
+        return
+      case 'waiting-cleared':
+        this.clearWaitingReason()
+        return
+      case 'agent-status':
+        this.onAgentStatus(event.status)
+        return
+      default:
+        return
+    }
+  }
+
+  /**
+   * Feed one raw durable session event.
+   * @deprecated Host-shape input kept for one release so an already-published
+   * consumer that drives this tracker itself (dsh-TUI ≤ 0.11.x calls this
+   * method) keeps working across the upgrade. New code normalizes through
+   * `src/compat/*` and calls {@link onEvent}. The parameter type is inferred
+   * from the compat function on purpose — this module must not import a DSH
+   * type.
+   * @param event - Raw durable session event.
+   */
+  onSessionEvent(event: Parameters<typeof feedSessionEvent>[1]): void {
+    feedSessionEvent(this, event)
+  }
+
+  /** Render the current status snapshot at a wall-clock instant. */
+  render(nowMs: number = this.now()): ActivityState {
+    return withProgressLang(this.language(), () => this.renderCurrent(nowMs))
+  }
+
+  private renderCurrent(nowMs: number): ActivityState {
+    switch (this.phase) {
+      case 'idle':
+        return {
+          phase: 'idle',
+          line: '',
+          toolCount: 0,
+          turnElapsedMs: 0,
+          phaseStartedAt: this.phaseStartedAt,
+        }
+      case 'done': {
+        const summary = this.doneSummary(nowMs)
+        return {
+          phase: 'done',
+          line: summary.line,
+          toolCount: this.toolCount,
+          turnElapsedMs: this.turnElapsedMs(nowMs),
+          phaseStartedAt: this.phaseStartedAt,
+          ...(summary.phrase === undefined ? {} : { phrase: summary.phrase }),
+        }
+      }
+      case 'tool': {
+        const tool = this.primaryTool()
+        if (tool === undefined) {
+          return this.renderThinking(nowMs)
+        }
+        const fragment = toolFragment(tool)
+        // Same granularity as the settled line: a fast tool's counter would
+        // otherwise sit at `0s` for its whole (measured 87 ms median) life.
+        const elapsed = durationLabel(Math.max(0, nowMs - tool.startedAt))
+        const git = tool.isGit
+          ? (this.gitBranch !== undefined ? ` · git ${this.gitBranch}` : ' · git')
+          : ''
+        const combo = (this.config.features ?? {}).combo !== false && this.streak >= COMBO_SHOW_AT
+          ? ` · ${t('tool-streak', { count: this.streak })}`
+          : ''
+        // An approval-parked tool says so even in minimal mode: this is the one
+        // state where the user, not the model, is the one being waited on.
+        const approval = this.waitingReason === 'approval' ? ` · ${t('tool-waiting-approval')}` : ''
+        const narration = this.freshNarration(nowMs)
+        // The turn's first tool opens with a short "thought it through, getting
+        // to work" line, prepended so the tool's own copy stays readable.
+        const opening = this.toolOpening(nowMs)
+        const prefix = opening === '' ? '' : `${opening} · `
+        const line = narration === null
+          ? `${prefix}${fragment} · ${elapsed}${git}${combo}${approval}`
+          : `⏵ ${narration} · ${prefix}${fragment} · ${elapsed}${git}${combo}${approval}`
+        return {
+          phase: 'tool',
+          line,
+          label: tool.action,
+          detail: tool.detail,
+          ...(narration === null ? (opening === '' ? {} : { phrase: opening }) : { phrase: narration }),
+          toolCount: this.toolCount,
+          turnElapsedMs: this.turnElapsedMs(nowMs),
+          phaseStartedAt: this.phaseStartedAt,
+        }
+      }
+      case 'waiting':
+      case 'thinking': {
+        const rendered = this.renderThinking(nowMs)
+        if (this.phase === 'waiting') {
+          return { ...rendered, phase: 'waiting' }
+        }
+        return rendered
+      }
+    }
+  }
+
+  /** Per-turn thinking/tooling split for stats consumers. */
+  stats(): TurnStats {
+    return {
+      thinkingMs: this.thinkingMs,
+      toolMs: this.toolMs,
+      toolCount: this.toolCount,
+    }
+  }
+
+  /**
+   * Opaque, JSON-safe snapshot of this tracker's complete state.
+   *
+   * A persisted projection checkpoint has to resume folding **without**
+   * replaying a session's whole log, so the state machine must be able to hand
+   * its state out and take it back. The shape is not public API: pass the value
+   * straight back to {@link ActivityTracker.restore}. {@link TRACKER_SNAPSHOT_VERSION}
+   * is the compatibility handle between the two.
+   * @returns every field the fold depends on, as JSON-safe values.
+   */
+  snapshot(): unknown {
+    const data: TrackerSnapshotShape = {
+      version: TRACKER_SNAPSHOT_VERSION,
+      progressLang: this.progressLang,
+      phase: this.phase,
+      phaseStartedAt: this.phaseStartedAt,
+      turnStartedAt: this.turnStartedAt,
+      thinkingStartedAt: this.thinkingStartedAt,
+      thinkingMs: this.thinkingMs,
+      toolMs: this.toolMs,
+      toolCount: this.toolCount,
+      activeTools: [...this.activeTools.values()],
+      doneQueue: this.doneQueue,
+      thinkingPhases: this.thinkingPhases,
+      firstToolStartedAt: this.firstToolStartedAt,
+      waitingFirstToken: this.waitingFirstToken,
+      narratedText: this.narratedText,
+      lastChunkAt: this.lastChunkAt,
+      recentStream: this.recentStream,
+      turnTokens: this.turnTokens,
+      donePrefix: this.donePrefix,
+      pendingPhrase: this.pendingPhrase,
+      pendingUntil: this.pendingUntil,
+      gitBranch: this.gitBranch ?? null,
+      model: this.model ?? null,
+      streak: this.streak,
+      lastToolEndAt: this.lastToolEndAt,
+      maxStreak: this.maxStreak,
+      subagentCount: this.subagentCount,
+      waitingReason: this.waitingReason ?? null,
+      waitingReasonAt: this.waitingReasonAt,
+      tokBuf: this.tokBuf,
+      tokWindowStart: this.tokWindowStart,
+    }
+    return data
+  }
+
+  /**
+   * Rebuild a tracker from {@link snapshot} output.
+   *
+   * The behavioral knobs are not part of the snapshot, so they are passed in
+   * again; everything the fold accumulates is restored. Mutable entries are
+   * cloned, so the restored tracker can never write back into the value the
+   * caller still holds as a checkpoint.
+   * @param config - Behavioral knobs.
+   * @param now - Wall-clock supplier.
+   * @param customActions - Custom action pools.
+   * @param payload - A value previously returned by `snapshot()`.
+   * @returns an equivalent tracker that can keep folding.
+   * @throws when the payload is not a snapshot of {@link TRACKER_SNAPSHOT_VERSION}
+   * — a caller holding a stale checkpoint must refold the log rather than render
+   * a state it cannot interpret.
+   */
+  static restore(
+    config: TrackerConfig,
+    now: () => number = Date.now,
+    customActions?: Readonly<Record<string, readonly string[]>>,
+    payload?: unknown,
+  ): ActivityTracker {
+    const data = payload as TrackerSnapshotShape | undefined
+    // The shape guards are deliberately cheap (phase + the two anchor clocks):
+    // they catch the torn-write / hand-edited cache cases a version number
+    // alone cannot, so a corrupt-but-current-version checkpoint fails HERE —
+    // where the projection can catch it and refold — instead of mid-render.
+    if (data === undefined || data === null || typeof data !== 'object'
+      || data.version !== TRACKER_SNAPSHOT_VERSION
+      || !isLang(data.progressLang)
+      || !isPhase(data.phase)
+      || typeof data.phaseStartedAt !== 'number'
+      || typeof data.turnStartedAt !== 'number') {
+      throw new Error(
+        `working-activity: unsupported tracker snapshot (expected version ${TRACKER_SNAPSHOT_VERSION})`,
+      )
+    }
+    const tracker = new ActivityTracker(config, now, customActions)
+    tracker.progressLang = data.progressLang
+    tracker.phase = data.phase
+    tracker.phaseStartedAt = data.phaseStartedAt
+    tracker.turnStartedAt = data.turnStartedAt
+    tracker.thinkingStartedAt = data.thinkingStartedAt
+    tracker.thinkingMs = data.thinkingMs
+    tracker.toolMs = data.toolMs
+    tracker.toolCount = data.toolCount
+    tracker.activeTools = new Map(data.activeTools.map(tool => [tool.callId, { ...tool }]))
+    tracker.doneQueue = data.doneQueue.map(tool => ({ ...tool }))
+    tracker.thinkingPhases = data.thinkingPhases
+    tracker.firstToolStartedAt = data.firstToolStartedAt
+    tracker.waitingFirstToken = data.waitingFirstToken
+    tracker.narratedText = data.narratedText
+    tracker.lastChunkAt = data.lastChunkAt
+    tracker.recentStream = data.recentStream
+    tracker.turnTokens = data.turnTokens
+    tracker.donePrefix = data.donePrefix
+    tracker.pendingPhrase = data.pendingPhrase
+    tracker.pendingUntil = data.pendingUntil
+    tracker.gitBranch = data.gitBranch ?? undefined
+    tracker.model = data.model ?? undefined
+    tracker.streak = data.streak
+    tracker.lastToolEndAt = data.lastToolEndAt
+    tracker.maxStreak = data.maxStreak
+    tracker.subagentCount = data.subagentCount
+    tracker.waitingReason = data.waitingReason ?? undefined
+    tracker.waitingReasonAt = data.waitingReasonAt
+    tracker.tokBuf = data.tokBuf
+    tracker.tokWindowStart = data.tokWindowStart
+    return tracker
+  }
+
+  /**
+   * The next instant at which {@link render} can produce a different line, or
+   * `undefined` when the line stays exactly as it is until another event
+   * arrives.
+   *
+   * A status line does not need a heartbeat: it needs to be redrawn when
+   * something it displays moves. Those movements are all known here — the
+   * elapsed second, the phrase rotation, a narration or tok/s window closing,
+   * and the done card swapping its tool fragment for the summary — so a caller
+   * can sleep exactly that long instead of polling. Idle and settled lines
+   * return `undefined`: nothing about them changes on its own, so they need no
+   * timer at all. Transitions on a longer horizon than the displayed second
+   * (the work reminder, for one) need no candidate of their own: the elapsed
+   * counter redraws long before them.
+   *
+   * The value is a lower bound on the next visible change, so waking at it can
+   * only be early, never late.
+   * @param nowMs - Wall-clock instant to measure from.
+   * @returns the next wake instant in epoch milliseconds, or `undefined`.
+   */
+  nextWakeAt(nowMs: number = this.now()): number | undefined {
+    switch (this.phase) {
+      case 'idle':
+        return undefined
+      case 'done': {
+        // The done line shows the last tool's fragment for a short window and
+        // then the summary; after that it is static until the next turn.
+        const last = this.doneQueue.at(-1)
+        if (last === undefined) return undefined
+        const swapAt = last.endedAt + DONE_FRAGMENT_MS
+        return nowMs < swapAt ? swapAt : undefined
+      }
+      case 'tool': {
+        const tool = this.primaryTool()
+        // `render` falls back to the thinking line when no tool is tracked.
+        if (tool === undefined) return this.liveWakeAt(nowMs, this.thinkingStartedAt)
+        return minWake(
+          secondBoundary(tool.startedAt, nowMs),
+          this.narrationWakeAt(nowMs),
+          this.tpsWakeAt(nowMs),
+        )
+      }
+      case 'waiting':
+      case 'thinking':
+        return this.liveWakeAt(nowMs, this.turnStartedAt)
+    }
+  }
+
+  /**
+   * Wake instant for a live phase that displays the turn's elapsed second: the
+   * next whole second, whichever of the other displayed windows closes first,
+   * and the phrase rotation — or the expiry of a one-off quip, which the render
+   * after it replaces.
+   * @param nowMs - Wall-clock instant to measure from.
+   * @param elapsedFrom - Instant the displayed second counter counts from.
+   */
+  private liveWakeAt(nowMs: number, elapsedFrom: number): number | undefined {
+    return minWake(
+      secondBoundary(elapsedFrom, nowMs),
+      this.rotationWakeAt(nowMs),
+      this.narrationWakeAt(nowMs),
+      this.tpsWakeAt(nowMs),
+    )
+  }
+
+  /** When the displayed phrase is replaced: a rotation, or a quip expiring. */
+  private rotationWakeAt(nowMs: number): number | undefined {
+    if (!this.config.phrases) return undefined
+    // An expired quip is no longer displayed (see pendingPhraseAt), so the
+    // wake falls through to the pool rotation — returning its past expiry
+    // would arm a zero-delay timer that re-arms forever.
+    if (this.pendingPhrase !== null && nowMs < this.pendingUntil) return this.pendingUntil
+    // The next window boundary of the phase's own pool. Derived rather than
+    // remembered: a read must never be what advances the copy (see phraseForSlot).
+    const rotateMs = this.rarePool() ? RARE_ROTATE_MS : PHRASE_ROTATE_MS
+    return this.phraseAnchorAt() + (this.phraseSlot(nowMs, rotateMs) + 1) * rotateMs
+  }
+
+  /** When the currently displayed narration expires, if one is displayed. */
+  private narrationWakeAt(nowMs: number): number | undefined {
+    if (this.freshNarration(nowMs) === null) return undefined
+    return this.lastChunkAt + NARRATE_GRACE_MS
+  }
+
+  /** When the displayed tok/s estimate ages out, if one is displayed. */
+  private tpsWakeAt(nowMs: number): number | undefined {
+    if (this.config.showTokPerSec !== true || this.tokBuf <= 0) return undefined
+    if (this.tpsPrefix(nowMs) === '') return undefined
+    return this.lastChunkAt + TPS_WINDOW_MS
+  }
+
+  private renderThinking(nowMs: number): ActivityState {
+    const thinkingMs = this.phase === 'waiting'
+      ? 0
+      : this.thinkingMs + Math.max(0, nowMs - this.thinkingStartedAt)
+    const elapsed = fmtDuration(this.turnElapsedMs(nowMs))
+    const elapsedLine = t('line-elapsed', { elapsed })
+    // A tool that just settled keeps its own copy on screen for a beat. Measured
+    // on real sessions: the median tool lasts 87 ms and 73% last under 500 ms, so
+    // without this the tool line is a single frame nobody can read. It outranks
+    // the narration for its window — the narration is usually the same `⏵` line
+    // from before the tool, while this one is the news.
+    const settled = this.settledToolLine(nowMs)
+    if (settled !== null) return settled
+    const narration = this.freshNarration(nowMs)
+    if (narration !== null) {
+      return {
+        phase: this.phase,
+        line: `⏵ ${narration} · ${elapsedLine}`,
+        phrase: narration,
+        toolCount: this.toolCount,
+        turnElapsedMs: this.turnElapsedMs(nowMs),
+        phaseStartedAt: this.phaseStartedAt,
+      }
+    }
+    // A stall outranks the copy pools (and survives minimal mode): the pool
+    // says "still queuing", which reads as model latency — a retry or a parked
+    // approval is a different fact the user cannot act on unless it is said.
+    const stall = this.stallPhrase()
+    if (stall !== null) {
+      return {
+        phase: this.phase,
+        line: `${stall} · ${elapsedLine}`,
+        phrase: stall,
+        toolCount: this.toolCount,
+        turnElapsedMs: this.turnElapsedMs(nowMs),
+        phaseStartedAt: this.phaseStartedAt,
+      }
+    }
+    if (this.config.phrases) {
+      const pending = this.pendingPhraseAt(nowMs)
+      // Waiting (pre-first-token) draws from the waiting pool; thinking draws
+      // the egg-aware lively pool (holiday / rare / weekend / night). The pool
+      // follows the CURRENT phase and the window follows the phase's own start,
+      // so neither the copy nor the cadence depends on how often this is read.
+      const rotateMs = this.rarePool() ? RARE_ROTATE_MS : PHRASE_ROTATE_MS
+      const phrase = pending ?? this.phraseForSlot(this.phraseSlot(nowMs, rotateMs), rotateMs, nowMs)
+      // The indicator animation (whale etc.) already signals activity, so the
+      // pi DOT_FRAMES ellipsis breathing is dropped for the DSH line.
+      const tps = this.tpsPrefix(nowMs)
+      return {
+        phase: this.phase,
+        line: `${tps}${phrase} · ${elapsedLine}`,
+        phrase,
+        toolCount: this.toolCount,
+        turnElapsedMs: this.turnElapsedMs(nowMs),
+        phaseStartedAt: this.phaseStartedAt,
+      }
+    }
+    const label = this.phase === 'waiting' ? t('waiting-label') : t('thinking-label')
+    return {
+      phase: this.phase,
+      line: `${label} · ${elapsedLine}`,
+      label,
+      toolCount: this.toolCount,
+      turnElapsedMs: this.turnElapsedMs(nowMs),
+      phaseStartedAt: this.phaseStartedAt,
+    }
+  }
+
+  /**
+   * The live narration this tracker is currently showing, if any.
+   *
+   * A projection folds DURABLE events only, so a live host that also sees
+   * stream frames has to hand the frame-derived narration to the projected
+   * value separately (see `ActivityProjectionOptions.live`); this is that
+   * payload, and `undefined` means "nothing live to overlay".
+   */
+  liveNarration(): { readonly narration: string; readonly lastChunkAt: number } | undefined {
+    if (this.narratedText === null) return undefined
+    return { narration: this.narratedText, lastChunkAt: this.lastChunkAt }
+  }
+
+  /**
+   * Show `narration` as if it had just streamed in.
+   *
+   * Used by the live overlay: the projected state carries no frames, so the
+   * host paints the freshest narration it has over the folded value.
+   */
+  applyLiveNarration(narration: string, at: number): void {
+    this.narratedText = narration
+    this.lastChunkAt = at
+  }
+
+  /**
+   * The "thought it through, getting to work" line for the turn's first tool.
+   *
+   * Shown as a prefix for a short window after that tool starts, then gone: it
+   * marks the thinking→doing boundary once per turn, and being derived (like
+   * every other phrase) it neither rotates nor repeats within the window.
+   * @param nowMs - Wall-clock instant to test.
+   * @returns the opening copy, or '' when the window is closed.
+   */
+  private toolOpening(nowMs: number): string {
+    if (!this.config.phrases) return ''
+    if (this.firstToolStartedAt === 0) return ''
+    if (nowMs - this.firstToolStartedAt >= TOOL_OPENING_MS) return ''
+    return toolOpeningPhrase({ seed: this.turnStartedAt, slot: 0 })
+  }
+
+  /**
+   * The just-finished tool, while its copy is still worth reading.
+   *
+   * Derived from the last settled tool's end time, so it neither lingers past
+   * its window nor depends on how often the line is read. `✓` marks it as
+   * settled, so it cannot be mistaken for the running-tool line.
+   * @param nowMs - Wall-clock instant to test.
+   * @returns the settled-tool state, or null when the window is closed.
+   */
+  private settledToolLine(nowMs: number): ActivityState | null {
+    if (!this.config.phrases) return null
+    const last = this.doneQueue.at(-1)
+    if (last === undefined) return null
+    const age = nowMs - last.endedAt
+    if (age < 0 || age >= TOOL_LINGER_MS) return null
+    const fragment = toolFragment(last)
+    return {
+      phase: this.phase === 'waiting' ? 'thinking' : this.phase,
+      line: `✓ ${fragment} · ${durationLabel(last.durationMs)}`,
+      label: last.action,
+      detail: last.detail,
+      phrase: last.action,
+      toolCount: this.toolCount,
+      turnElapsedMs: this.turnElapsedMs(nowMs),
+      phaseStartedAt: this.phaseStartedAt,
+    }
+  }
+
+  /**
+   * The pending one-off quip (interrupt / model / compact), while fresh.
+   *
+   * A pure read: an expired quip is simply not returned (the field is
+   * overwritten by the next one), and the work reminder has its own derived
+   * window — the old version wrote here (`pendingPhrase = null`,
+   * `reminded = true`), which a projection's throwaway restore discarded, so
+   * the reminder re-fired on EVERY read and pinned the line for the rest of
+   * the turn.
+   */
+  private pendingPhraseAt(nowMs: number): string | null {
+    if (this.pendingPhrase !== null && nowMs < this.pendingUntil) return this.pendingPhrase
+    return this.workReminderAt(nowMs)
+  }
+
+  /**
+   * The work reminder, purely derived from elapsed time.
+   *
+   * Shown for {@link PENDING_MS} of wall time each time another `workRemindAt`
+   * hours of continuous work accumulate (`hours % workRemindAt` is the distance
+   * into the current bucket). No state: repeated reads agree, a resumed
+   * checkpoint renders the same answer, and the reminder returns every bucket
+   * instead of once per process.
+   */
+  private workReminderAt(nowMs: number): string | null {
+    const remindAt = this.config.workRemindAt ?? 0
+    if (remindAt <= 0) return null
+    const hours = this.turnElapsedMs(nowMs) / 3_600_000
+    if (hours < remindAt) return null
+    const intoBucketMs = (hours % remindAt) * 3_600_000
+    if (intoBucketMs >= PENDING_MS) return null
+    return t('work-remind', { hours: Math.floor(hours) })
+  }
+
+  /** Estimated tokens/s while the stream is fresh (pi parity, opt-in). */
+  private tpsPrefix(nowMs: number): string {
+    if (!this.config.showTokPerSec || this.tokBuf <= 0) return ''
+    if (nowMs - this.lastChunkAt > TPS_WINDOW_MS) return ''
+    const windowSec = Math.max(1, (nowMs - this.tokWindowStart) / 1000)
+    const tps = Math.round(this.tokBuf / windowSec)
+    return tps > 0 ? `~${tps} tok/s · ` : ''
+  }
+
+  private doneSummary(nowMs: number): { line: string; phrase?: string } {
+    const { thinkingMs, toolMs, toolCount } = this.stats()
+    const tokens = this.turnTokens > 0 ? ` · 🔥 ${fmtTokens(this.turnTokens)}` : ''
+    const sub = this.subagentCount > 0 ? ` · ${t('subagent-count', { count: this.subagentCount })}` : ''
+    const combo = (this.config.features ?? {}).combo !== false && this.maxStreak >= COMBO_SHOW_AT
+      ? ` · ${t('tool-streak', { count: this.maxStreak })}`
+      : ''
+    const tools = t(toolCount === 1 ? 'tool-count-one' : 'tool-count-many', { count: toolCount })
+    // Sub-second splits read in milliseconds for the same reason a settled
+    // tool does: a quick turn would otherwise summarize as 想0s 干0s.
+    const summary = t('done-summary', {
+      tools,
+      thinking: durationLabel(thinkingMs),
+      tooling: durationLabel(toolMs),
+    })
+    if (!this.config.phrases) {
+      return { line: `${t('done-prefix')} · ${summary}${sub}${combo}${tokens}` }
+    }
+    const last = this.doneQueue.at(-1)
+    if (last !== undefined && nowMs - last.endedAt < DONE_FRAGMENT_MS) {
+      const fragment = toolFragment(last)
+      return { line: `${this.donePrefix} · ${fragment} · ${tools}${sub}${combo}${tokens}`, phrase: this.donePrefix }
+    }
+    return { line: `${this.donePrefix} · ${summary}${sub}${combo}${tokens}`, phrase: this.donePrefix }
+  }
+
+  /** The fresh self-narration line, or null once the stream has been quiet. */
+  private freshNarration(nowMs: number): string | null {
+    if (this.narratedText === null) return null
+    if (nowMs - this.lastChunkAt > NARRATE_GRACE_MS) return null
+    return this.narratedText
+  }
+
+  private primaryTool(): ActiveTool | undefined {
+    let primary: ActiveTool | undefined
+    for (const tool of this.activeTools.values()) {
+      if (primary === undefined || tool.startedAt < primary.startedAt) primary = tool
+    }
+    return primary
+  }
+
+  private turnElapsedMs(nowMs: number): number {
+    return this.turnStartedAt === 0 ? 0 : Math.max(0, nowMs - this.turnStartedAt)
+  }
+
+  /** Drop the current stall, whatever it was. */
+  private clearWaitingReason(): void {
+    this.waitingReason = undefined
+    this.waitingReasonAt = 0
+  }
+
+  /**
+   * Copy for the current stall, or null when the turn is not stalled.
+   *
+   * Deterministic per stall — seeded by the turn and the stall's start, so
+   * every read of one stall shows the same line (a per-read re-roll is the
+   * flicker bug the slot scheme exists to prevent).
+   */
+  private stallPhrase(): string | null {
+    if (this.waitingReason === undefined) return null
+    return waitingReasonPhrase(this.waitingReason, {
+      seed: this.turnStartedAt + this.waitingReasonAt,
+      slot: 0,
+    })
+  }
+
+  /**
+   * How the current line is derived — the debug trace behind the optional
+   * `debugLog`, so "why did it say THAT" is answerable from a file instead of
+   * from memory.
+   * @param nowMs - Wall-clock instant to describe.
+   * @returns the derivation inputs of the current render.
+   */
+  describe(nowMs: number = this.now()): Record<string, unknown> {
+    const rotateMs = this.rarePool() ? RARE_ROTATE_MS : PHRASE_ROTATE_MS
+    return {
+      phase: this.phase,
+      phraseSlot: this.phraseSlot(nowMs, rotateMs),
+      rotateMs,
+      rarePool: this.rarePool(),
+      thinkingPhases: this.thinkingPhases,
+      waitingReason: this.waitingReason ?? null,
+      pendingPhrase: this.pendingPhrase ?? null,
+      narration: this.narratedText ?? null,
+      toolCount: this.toolCount,
+      turnElapsedMs: this.turnElapsedMs(nowMs),
+    }
+  }
+
+  private setPhase(phase: ActivityPhase, atMs: number): void {
+    // A phase change switches copy pools at once — the phrase is derived from
+    // the CURRENT phase, so nothing from the previous phase can linger.
+    if (phase === 'thinking' && this.phase !== 'thinking') this.thinkingPhases += 1
+    this.phase = phase
+    this.phaseStartedAt = atMs
+  }
+
+  /**
+   * The instant the current phrase's rotation window starts from.
+   *
+   * The phase's own start, so entering a phase immediately shows that phase's
+   * copy; a phase still needs a turn to belong to, hence the fallback.
+   */
+  private phraseAnchorAt(): number {
+    return this.phaseStartedAt > 0 ? this.phaseStartedAt : this.turnStartedAt
+  }
+
+  /** The rotation window index of the current phase at `nowMs`. */
+  private phraseSlot(nowMs: number, rotateMs: number): number {
+    return Math.max(0, Math.floor((nowMs - this.phraseAnchorAt()) / rotateMs))
+  }
+
+  /**
+   * Whether this phase draws from the rare pool.
+   *
+   * Once per turn, in the turn's FIRST thinking phase, decided by the seed — a
+   * per-read dice roll would pop an egg in and out of the line (the egg's own
+   * display window then lasts for the whole phase).
+   */
+  private rarePool(): boolean {
+    const features = this.config.features ?? {}
+    if (features.rareEggs === false) return false
+    if (this.phase !== 'thinking' || this.thinkingPhases !== 1) return false
+    return mixSlot(this.turnStartedAt, 0x5EED) % Math.round(1 / RARE_CHANCE) === 0
+  }
+
+  /**
+   * The phrase for one rotation window — a PURE function of the state and `nowMs`.
+   *
+   * This used to be stateful (`previousPhrase` + `phraseChangedAt` mutated on
+   * render). That works for a long-lived in-process tracker, but a projected
+   * value is read far more often than it is written: the read renders a
+   * throwaway copy, so every read rolled a new phrase (measured: three different
+   * phrases in three consecutive 500 ms reads) and a phase change could carry the
+   * previous phase's pool in. Deriving from (phase, phase start, seed, slot)
+   * makes a read idempotent and keeps the pools apart by construction.
+   */
+  private phraseForSlot(slot: number, rotateMs: number, nowMs: number): string {
+    const at: PhraseSlot = { seed: this.turnStartedAt, slot }
+    const features = this.config.features ?? {}
+    // The RENDER instant, not the tracker's clock supplier: one render, one
+    // time source. Night/holiday copy used to read `this.now()` while the
+    // elapsed read `nowMs`, so rendering "as of" another instant (a test, a
+    // historical value) picked copy from a different moment than it displayed.
+    const now = new Date(nowMs)
+    if (this.phase === 'waiting') return waitingPhrase(undefined, at)
+    // Eggs belong to the turn's first thinking window — the waiting phase is
+    // usually over before a window elapses, so a greeting shown there would
+    // flash by. Order matches the pi extension: holiday → rare → weekend, and
+    // "first thinking phase, first window" is what makes them once per turn.
+    if (this.thinkingPhases === 1 && slot === 0) {
+      if (features.holidays !== false) {
+        const holiday = holidayPhrase(now, at)
+        if (holiday !== null) return holiday
+      }
+      if (this.rarePool()) return rarePhrase(undefined, at)
+      if (features.weekend !== false && isWeekend(now)) return weekendPhrase(undefined, at)
+    }
+    if (this.rarePool()) return rarePhrase(undefined, at)
+    // The long-thinking tiers are chosen at the WINDOW's start, not at the
+    // instant of the read: a tier boundary crossed mid-window would otherwise
+    // swap the copy seconds into a window the reader is still on.
+    const windowStart = this.phraseAnchorAt() + slot * rotateMs
+    const thinkingAtWindowStart = Math.max(0, windowStart - this.thinkingStartedAt)
+    return thinkingPhrase(
+      this.thinkingStartedAt === 0 ? this.thinkingMs : thinkingAtWindowStart,
+      undefined,
+      features.nightPhrases !== false && isNight(now.getHours()),
+      this.config.customPhrases,
+      at,
+    )
+  }
+}
+
+/** Earliest of the candidate wake instants, ignoring the absent ones. */
+function minWake(...candidates: readonly (number | undefined)[]): number | undefined {
+  let earliest: number | undefined
+  for (const candidate of candidates) {
+    if (candidate === undefined) continue
+    if (earliest === undefined || candidate < earliest) earliest = candidate
+  }
+  return earliest
+}
+
+/**
+ * The next whole second after `nowMs`, counted from `from`. The line renders
+ * elapsed time with second resolution, so this is the finest cadence a live
+ * phase can actually show.
+ * @param from - Instant the displayed counter counts from.
+ * @param nowMs - Current instant.
+ */
+function secondBoundary(from: number, nowMs: number): number {
+  const elapsed = Math.max(0, nowMs - from)
+  return from + (Math.floor(elapsed / 1000) + 1) * 1000
+}
+
+/**
+ * How long one phrase stays on screen.
+ *
+ * This is the pi extension's cadence, unchanged: the copy was never rotating
+ * too fast — it was being re-rolled on every read (see phraseForSlot), which is
+ * what read as flicker. With the read made pure, one phrase per window is
+ * exactly what a reader sees, and 4 s is the pace that felt right.
+ */
+const PHRASE_ROTATE_MS = 4000
+/** Rare easter-egg phrases linger longer, since they are a one-off per turn. */
+const RARE_ROTATE_MS = 7500
+/** One-off quips (interrupt / model / compact) display window. */
+const PENDING_MS = 6000
+/** How long the thinking→doing opening line rides the turn's first tool. */
+const TOOL_OPENING_MS = 2500
+/**
+ * How long a settled tool keeps its own line before the copy returns to phrases.
+ *
+ * Real-session measurement: median tool 87 ms, 73% under 500 ms — shorter than a
+ * single client re-read, so without a linger the tool line is unreadable.
+ */
+const TOOL_LINGER_MS = 2500
+/** Tools closer than this count as one combo streak. */
+const COMBO_GAP_MS = 10_000
+/** Streak at which the combo badge shows. */
+const COMBO_SHOW_AT = 2
+/** The tps estimate stays fresh this long after the last chunk. */
+const TPS_WINDOW_MS = 3500
+/** Cap on replayed done cards; older entries drop. */
+const DONE_QUEUE_MAX = 6
+/** Show the last tool's fragment in the done line for this long after it ends. */
+const DONE_FRAGMENT_MS = 3000
+/** Rolling stream buffer size for `⏵` narration extraction. */
+const STREAM_BUFFER_CHARS = 300
+/** A narration stays visible this long after the stream went quiet. */
+const NARRATE_GRACE_MS = 5000
+
+/** Narration budget in display columns: 40 CJK chars ≈ 12 English words. */
+const NARRATION_MAX_COLUMNS = 80
+
+/** A CJK/full-width code point renders 2 terminal columns; the rest render 1. */
+function isWide(cp: number): boolean {
+  return (
+    (cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+    (cp >= 0x2e80 && cp <= 0xa4cf) || // CJK radicals, kana, Yi
+    (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+    (cp >= 0xf900 && cp <= 0xfaff) || // CJK compatibility ideographs
+    (cp >= 0xfe30 && cp <= 0xfe4f) || // CJK compatibility forms
+    (cp >= 0xff00 && cp <= 0xff60) || // full-width forms
+    (cp >= 0xffe0 && cp <= 0xffe6) || // full-width signs
+    (cp >= 0x20000 && cp <= 0x3fffd) // CJK extensions
+    // Emoji occupy two columns in every mainstream terminal; counting them as
+    // one let an "80-column" narration run ~40 columns over budget (the pools
+    // carry 🧧 🐳 🎃).
+    || (cp >= 0x1f000 && cp <= 0x1faff) // cards, emoji, symbols, pictographs
+  )
+}
+
+/** Cut before `max` columns, backing off to the last word or clause boundary. */
+function cutToWidth(text: string, max: number): string {
+  let width = 0
+  let cut = text.length
+  const chars = [...text]
+  for (let i = 0; i < chars.length; i++) {
+    const w = isWide(chars[i]!.codePointAt(0)!) ? 2 : 1
+    if (width + w > max) {
+      cut = chars.slice(0, i).join('').length
+      break
+    }
+    width += w
+  }
+  if (cut === text.length) return text
+  // Back off to a soft boundary so English words survive intact; dense CJK has
+  // none and hard-cuts at the budget like the original fixed 40-char capture.
+  const head = text.slice(0, cut)
+  const soft = Math.max(
+    head.lastIndexOf(' '),
+    head.lastIndexOf('\t'),
+    head.lastIndexOf('，'),
+    head.lastIndexOf('、'),
+    head.lastIndexOf(';'),
+    head.lastIndexOf('；'),
+    head.lastIndexOf(','),
+  )
+  return soft > 0 ? head.slice(0, soft) : head
+}
+
+/**
+ * Extract the latest `⏵` self-narration line from a stream buffer.
+ *
+ * The marker has to START a line. The injected contract asks for one standalone
+ * line, so a `⏵` inside a sentence is the model *mentioning* the format rather
+ * than narrating with it — measured on a live session, where the line quoted a
+ * fragment out of the middle of the model's own prose.
+ *
+ * The text is model output destined for a terminal, so it is flattened here:
+ * an ESC or a newline carried by a delta must not reach the screen (see
+ * {@link sanitizeFragment}).
+ * @param buffer - Rolling window of the visible streamed text.
+ * @returns the narration, or null when the buffer carries none.
+ */
+export function extractNarration(buffer: string): string | null {
+  const matches = [...buffer.matchAll(/(?:^|\n)⏵[ \t]*([^\n⏵]*)/g)]
+  const matched = matches[matches.length - 1]?.[1]
+  if (matched === undefined) return null
+  const latest = sanitizeFragment(matched)
+  if (!latest) return null
+
+  // A missing newline must not turn the rest of the response into status text.
+  // Stop at sentence ends and clause delimiters, while leaving dotted
+  // identifiers such as `ink.tsx`, `agent.ctx` and `README.MD` intact. A dot
+  // ends a sentence only before whitespace, the end, or a Title-case word
+  // (`safely.The`); dot-uppercase-uppercase stays an extension (`.MD`).
+  const boundary = latest.search(/[。．!?！？;；]|\.(?=\s|$|[A-Z][a-z])/)
+  const sentence = boundary < 0 ? latest : latest.slice(0, boundary + 1)
+
+  // The budget is display width, so English and Chinese render equally long:
+  // 40 CJK characters and ~12 English words share the same line budget.
+  const text = cutToWidth(sentence, NARRATION_MAX_COLUMNS).replace(/[。．.!！,，、;；]+$/, '').trim()
+  return text.length === 0 ? null : text
+}
+
+/** Format a token count compactly (`12.3k`, `1.2M`). */
+function fmtTokens(tokens: number): string {
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`
+  if (tokens >= 1000) return `${(tokens / 1000).toFixed(1)}k`
+  return String(tokens)
+}
+
+/** Coarse streaming token estimate (pi parity: CJK ×1.5, others ÷4). */
+function estimateTokens(text: string): number {
+  const compact = text.replace(/\s/g, '')
+  if (compact.length === 0) return 0
+  const cjkCount = (compact.match(/[\u3400-\u9fff]/g) ?? []).length
+  return Math.max(1, Math.ceil(cjkCount * 1.5 + (compact.length - cjkCount) / 4))
+}
+
+/** Parse a tool call's raw arguments JSON defensively. */
+function parseArguments(raw: string): Readonly<Record<string, unknown>> | undefined {
+  if (raw.trim().length === 0) return undefined
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Readonly<Record<string, unknown>>
+    }
+    return undefined
+  } catch {
+    return undefined
+  }
+}