@askdkc/dsh-cli 0.11.7 → 0.12.0

package/node_modules/dsh-working-activity/lib/types/status.js

@@ -0,0 +1,1306 @@
+/**
+ * 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 { actionFor, compactPhrase, continuePhrase, donePhrase, failPhrase, fmtDuration, holidayPhrase, isGitTool, isNight, isWeekend, mixSlot, modelQuip, overflowPhrase, rarePhrase, RARE_CHANCE, thinkingPhrase, toolOpeningPhrase, weekendPhrase, waitingPhrase, waitingReasonPhrase, } from './phrases.js';
+import { feedSessionEvent } from './compat/session-events.js';
+import { detectInputLanguage, isLang, langNow, t, terminalProgressLang, withProgressLang } from './lang.js';
+/**
+ * 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;
+/** Format one tool into its display fragment (`跑个命令 npm test`). */
+function toolFragment(tool) {
+    return tool.detail.length === 0 ? tool.action : `${tool.action} ${tool.detail}`;
+}
+/** The phase vocabulary, for snapshot shape validation (see {@link ActivityTracker.restore}). */
+const PHASES = ['idle', 'waiting', 'thinking', 'tool', 'done'];
+/** Whether `value` is one of {@link PHASES}. */
+function isPhase(value) {
+    return PHASES.includes(value);
+}
+/**
+ * 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) {
+    // 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, limit) {
+    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) {
+    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, args, limit) {
+    if (args === undefined)
+        return '';
+    const pickString = (...keys) => {
+        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 {
+    config;
+    now;
+    customActions;
+    progressLang = terminalProgressLang();
+    phase = 'idle';
+    phaseStartedAt = 0;
+    turnStartedAt = 0;
+    thinkingStartedAt = 0;
+    thinkingMs = 0;
+    toolMs = 0;
+    toolCount = 0;
+    /** When the turn's first tool started; 0 until it does (see {@link toolOpening}). */
+    firstToolStartedAt = 0;
+    activeTools = new Map();
+    doneQueue = [];
+    thinkingPhases = 0;
+    waitingFirstToken = false;
+    /** Latest `⏵` self-narration line extracted from the stream, or null. */
+    narratedText = null;
+    /** Wall-clock time of the most recent stream delta (narration freshness). */
+    lastChunkAt = 0;
+    /** Rolling window of VISIBLE text deltas, for `⏵` extraction (see onEvent). */
+    recentStream = '';
+    /** Total tokens reported across the turn's assistant messages. */
+    turnTokens = 0;
+    /** Completion prefix drawn ONCE at turn end so the done line stays stable. */
+    donePrefix = t('done-prefix');
+    /** One-off copy pinned by an external event (interrupt / model switch /
+     *  compaction / work reminder), shown until it expires. */
+    pendingPhrase = null;
+    pendingUntil = 0;
+    /** Git branch of the session cwd (fed by the host, best-effort). */
+    gitBranch;
+    /** Last model route announced, so a repeated selection stays quiet. */
+    model;
+    /** Consecutive fast tool streak (combo). */
+    streak = 0;
+    lastToolEndAt = 0;
+    maxStreak = 0;
+    /** Subagent (agent/task) calls in the current turn. */
+    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`.
+     */
+    waitingReason;
+    /** When the current stall began (seeds its copy; 0 with no stall). */
+    waitingReasonAt = 0;
+    /** Streaming token estimate for the tps prefix. */
+    tokBuf = 0;
+    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(config, now = Date.now, customActions) {
+        this.config = config;
+        this.now = now;
+        this.customActions = customActions;
+    }
+    /** The locale used by this session's line. Existing modes still follow /lang. */
+    language() {
+        return this.config.inputLanguage ? this.progressLang : (this.config.language?.() ?? langNow());
+    }
+    /** Agent transitioned to running/idle. */
+    onAgentStatus(status) {
+        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() {
+        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) {
+        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) {
+        // 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) {
+        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) {
+        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));
+    }
+    applyEvent(event) {
+        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 = {
+                    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) {
+        feedSessionEvent(this, event);
+    }
+    /** Render the current status snapshot at a wall-clock instant. */
+    render(nowMs = this.now()) {
+        return withProgressLang(this.language(), () => this.renderCurrent(nowMs));
+    }
+    renderCurrent(nowMs) {
+        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() {
+        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() {
+        const data = {
+            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, now = Date.now, customActions, payload) {
+        const data = payload;
+        // 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 = this.now()) {
+        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.
+     */
+    liveWakeAt(nowMs, elapsedFrom) {
+        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. */
+    rotationWakeAt(nowMs) {
+        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. */
+    narrationWakeAt(nowMs) {
+        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. */
+    tpsWakeAt(nowMs) {
+        if (this.config.showTokPerSec !== true || this.tokBuf <= 0)
+            return undefined;
+        if (this.tpsPrefix(nowMs) === '')
+            return undefined;
+        return this.lastChunkAt + TPS_WINDOW_MS;
+    }
+    renderThinking(nowMs) {
+        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() {
+        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, at) {
+        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.
+     */
+    toolOpening(nowMs) {
+        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.
+     */
+    settledToolLine(nowMs) {
+        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.
+     */
+    pendingPhraseAt(nowMs) {
+        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.
+     */
+    workReminderAt(nowMs) {
+        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). */
+    tpsPrefix(nowMs) {
+        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 · ` : '';
+    }
+    doneSummary(nowMs) {
+        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. */
+    freshNarration(nowMs) {
+        if (this.narratedText === null)
+            return null;
+        if (nowMs - this.lastChunkAt > NARRATE_GRACE_MS)
+            return null;
+        return this.narratedText;
+    }
+    primaryTool() {
+        let primary;
+        for (const tool of this.activeTools.values()) {
+            if (primary === undefined || tool.startedAt < primary.startedAt)
+                primary = tool;
+        }
+        return primary;
+    }
+    turnElapsedMs(nowMs) {
+        return this.turnStartedAt === 0 ? 0 : Math.max(0, nowMs - this.turnStartedAt);
+    }
+    /** Drop the current stall, whatever it was. */
+    clearWaitingReason() {
+        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).
+     */
+    stallPhrase() {
+        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 = this.now()) {
+        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),
+        };
+    }
+    setPhase(phase, atMs) {
+        // 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.
+     */
+    phraseAnchorAt() {
+        return this.phaseStartedAt > 0 ? this.phaseStartedAt : this.turnStartedAt;
+    }
+    /** The rotation window index of the current phase at `nowMs`. */
+    phraseSlot(nowMs, rotateMs) {
+        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).
+     */
+    rarePool() {
+        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.
+     */
+    phraseForSlot(slot, rotateMs, nowMs) {
+        const at = { 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) {
+    let earliest;
+    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, nowMs) {
+    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) {
+    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, max) {
+    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) {
+    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) {
+    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) {
+    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) {
+    if (raw.trim().length === 0)
+        return undefined;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}