wotann 0.5.0

package/dist/ui/sound.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Sound cues — Wave 6-OO TUI v2 Phase 2 optional audible feedback.
+ *
+ * ── Why this exists ───────────────────────────────────────────────
+ * Some users — particularly those running long-form agent loops in
+ * the background — want an audible nudge when the assistant
+ * finishes or hits an error. We can't render real audio from a TUI
+ * (no audio driver), but every halfway-modern terminal still
+ * honours BEL (`\x07`), which usually maps to a system bell or a
+ * visual flash.
+ *
+ * ── Off by default (QB#6 — honest defaults) ───────────────────────
+ * Sound is OPT-IN. `WOTANN_SOUND_CUES=1` enables it. Defaulting
+ * sound on would surprise users in shared offices and on speakers.
+ *
+ * ── Honest no-op when stdout cannot beep ──────────────────────────
+ * - If stdout is not a TTY (pipe, log file, CI) the BEL byte is
+ *   meaningless — do nothing.
+ * - If `WOTANN_SOUND_CUES` is anything other than the literal "1",
+ *   do nothing. We do not honour "true", "yes", etc., per the
+ *   strict-string-equality bar (Session 4 quality bar #13).
+ * - If a write fails (e.g. EPIPE on a closed terminal), the
+ *   error is swallowed silently — sound is decorative, never
+ *   load-bearing.
+ *
+ * ── Per-instance state (QB#7) ─────────────────────────────────────
+ * The SoundCueController carries its own enable flag and stdout
+ * reference. Module-globals would prevent tests from running in
+ * parallel against different mock streams.
+ */
+/** Cue identifiers used by the rest of the TUI. */
+export type SoundCueKind = "session-start" | "complete" | "error" | "notice";
+/**
+ * True iff env + stdout indicate that we may safely play a cue.
+ * Pure function — does not actually emit anything.
+ */
+export declare function soundCuesEnabled(options?: {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly stdout?: NodeJS.WriteStream;
+}): boolean;
+export interface SoundCueControllerOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly stdout?: NodeJS.WriteStream;
+    /**
+     * Throttle cues fired in quick succession. Defaults to 200ms —
+     * if the same kind fires twice within that window, only the
+     * first is heard. Set to 0 to disable throttling.
+     */
+    readonly throttleMs?: number;
+}
+/**
+ * SoundCueController — a per-session sound emitter.
+ *
+ * Applications construct ONE controller at startup and call
+ * `play(kind)` whenever they want a cue. The controller checks
+ * env and stdout each time so that toggling `WOTANN_SOUND_CUES`
+ * mid-run takes effect without restarting the process.
+ */
+export declare class SoundCueController {
+    private readonly env;
+    private readonly stdout;
+    private readonly throttleMs;
+    private readonly lastFireAt;
+    constructor(options?: SoundCueControllerOptions);
+    /** Whether `play()` will actually emit anything right now. */
+    isEnabled(): boolean;
+    /**
+     * Play a cue. Returns true iff a BEL was actually written. The
+     * return value is mainly useful for tests — production callers
+     * can fire-and-forget.
+     */
+    play(kind: SoundCueKind, now?: number): boolean;
+    /** Reset throttle state. Used in tests. */
+    resetThrottle(): void;
+}
+/**
+ * Fire a sound cue using the process-default controller.
+ *
+ * Exists so simple call sites don't have to thread a controller
+ * through. For complex tests use a fresh `SoundCueController`.
+ */
+export declare function playSoundCue(kind: SoundCueKind): boolean;
+/** Reset the process-default controller (test-only utility). */
+export declare function __resetDefaultSoundController(): void;
+//# sourceMappingURL=sound.d.ts.map

package/dist/ui/sound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sound.d.ts","sourceRoot":"","sources":["../../src/ui/sound.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,mDAAmD;AACnD,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;AAa7E;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE;IACP,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;CACjC,GACL,OAAO,CAMT;AAID,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwC;gBAEvD,OAAO,GAAE,yBAA8B;IAMnD,8DAA8D;IAC9D,SAAS,IAAI,OAAO;IAIpB;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,GAAE,MAAmB,GAAG,OAAO;IAc3D,2CAA2C;IAC3C,aAAa,IAAI,IAAI;CAGtB;AAmBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAExD;AAED,gEAAgE;AAChE,wBAAgB,6BAA6B,IAAI,IAAI,CAEpD"}

package/dist/ui/sound.js

@@ -0,0 +1,126 @@
+/**
+ * Sound cues — Wave 6-OO TUI v2 Phase 2 optional audible feedback.
+ *
+ * ── Why this exists ───────────────────────────────────────────────
+ * Some users — particularly those running long-form agent loops in
+ * the background — want an audible nudge when the assistant
+ * finishes or hits an error. We can't render real audio from a TUI
+ * (no audio driver), but every halfway-modern terminal still
+ * honours BEL (`\x07`), which usually maps to a system bell or a
+ * visual flash.
+ *
+ * ── Off by default (QB#6 — honest defaults) ───────────────────────
+ * Sound is OPT-IN. `WOTANN_SOUND_CUES=1` enables it. Defaulting
+ * sound on would surprise users in shared offices and on speakers.
+ *
+ * ── Honest no-op when stdout cannot beep ──────────────────────────
+ * - If stdout is not a TTY (pipe, log file, CI) the BEL byte is
+ *   meaningless — do nothing.
+ * - If `WOTANN_SOUND_CUES` is anything other than the literal "1",
+ *   do nothing. We do not honour "true", "yes", etc., per the
+ *   strict-string-equality bar (Session 4 quality bar #13).
+ * - If a write fails (e.g. EPIPE on a closed terminal), the
+ *   error is swallowed silently — sound is decorative, never
+ *   load-bearing.
+ *
+ * ── Per-instance state (QB#7) ─────────────────────────────────────
+ * The SoundCueController carries its own enable flag and stdout
+ * reference. Module-globals would prevent tests from running in
+ * parallel against different mock streams.
+ */
+/** BEL byte — sent to stdout to ring a terminal bell. */
+const BEL_BYTE = "\x07";
+/** Strict env value that enables sound cues. */
+const ENABLE_VALUE = "1";
+/** Env var that toggles sound on. */
+const ENV_VAR = "WOTANN_SOUND_CUES";
+// ── Public detection ─────────────────────────────────────────────────
+/**
+ * True iff env + stdout indicate that we may safely play a cue.
+ * Pure function — does not actually emit anything.
+ */
+export function soundCuesEnabled(options = {}) {
+    const env = options.env ?? process.env;
+    const stdout = options.stdout ?? process.stdout;
+    if (env[ENV_VAR] !== ENABLE_VALUE)
+        return false;
+    if (!stdout.isTTY)
+        return false;
+    return true;
+}
+/**
+ * SoundCueController — a per-session sound emitter.
+ *
+ * Applications construct ONE controller at startup and call
+ * `play(kind)` whenever they want a cue. The controller checks
+ * env and stdout each time so that toggling `WOTANN_SOUND_CUES`
+ * mid-run takes effect without restarting the process.
+ */
+export class SoundCueController {
+    env;
+    stdout;
+    throttleMs;
+    lastFireAt = new Map();
+    constructor(options = {}) {
+        this.env = options.env ?? process.env;
+        this.stdout = options.stdout ?? process.stdout;
+        this.throttleMs = options.throttleMs ?? 200;
+    }
+    /** Whether `play()` will actually emit anything right now. */
+    isEnabled() {
+        return soundCuesEnabled({ env: this.env, stdout: this.stdout });
+    }
+    /**
+     * Play a cue. Returns true iff a BEL was actually written. The
+     * return value is mainly useful for tests — production callers
+     * can fire-and-forget.
+     */
+    play(kind, now = Date.now()) {
+        if (!this.isEnabled())
+            return false;
+        const last = this.lastFireAt.get(kind) ?? 0;
+        if (this.throttleMs > 0 && now - last < this.throttleMs)
+            return false;
+        this.lastFireAt.set(kind, now);
+        try {
+            this.stdout.write(BEL_BYTE);
+            return true;
+        }
+        catch {
+            // EPIPE on a closed terminal is harmless — sound is decorative.
+            return false;
+        }
+    }
+    /** Reset throttle state. Used in tests. */
+    resetThrottle() {
+        this.lastFireAt.clear();
+    }
+}
+// ── Convenience module-level helper ─────────────────────────────────
+let defaultController = null;
+/**
+ * Lazy default controller bound to `process.stdout`. Use this when
+ * you do not need to inject a custom env/stdout. Tests SHOULD
+ * construct their own SoundCueController instead — the default
+ * controller is a process-global convenience.
+ */
+function getDefaultController() {
+    if (defaultController === null) {
+        defaultController = new SoundCueController();
+    }
+    return defaultController;
+}
+/**
+ * Fire a sound cue using the process-default controller.
+ *
+ * Exists so simple call sites don't have to thread a controller
+ * through. For complex tests use a fresh `SoundCueController`.
+ */
+export function playSoundCue(kind) {
+    return getDefaultController().play(kind);
+}
+/** Reset the process-default controller (test-only utility). */
+export function __resetDefaultSoundController() {
+    defaultController = null;
+}
+//# sourceMappingURL=sound.js.map

package/dist/ui/sound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sound.js","sourceRoot":"","sources":["../../src/ui/sound.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAKH,yDAAyD;AACzD,MAAM,QAAQ,GAAG,MAAM,CAAC;AAExB,gDAAgD;AAChD,MAAM,YAAY,GAAG,GAAG,CAAC;AAEzB,qCAAqC;AACrC,MAAM,OAAO,GAAG,mBAAmB,CAAC;AAEpC,wEAAwE;AAExE;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,UAGI,EAAE;IAEN,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACvC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAChD,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,YAAY;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAChC,OAAO,IAAI,CAAC;AACd,CAAC;AAeD;;;;;;;GAOG;AACH,MAAM,OAAO,kBAAkB;IACZ,GAAG,CAAoB;IACvB,MAAM,CAAqB;IAC3B,UAAU,CAAS;IACnB,UAAU,GAA8B,IAAI,GAAG,EAAE,CAAC;IAEnE,YAAY,UAAqC,EAAE;QACjD,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;QAC/C,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,GAAG,CAAC;IAC9C,CAAC;IAED,8DAA8D;IAC9D,SAAS;QACP,OAAO,gBAAgB,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAClE,CAAC;IAED;;;;OAIG;IACH,IAAI,CAAC,IAAkB,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;QAC/C,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE;YAAE,OAAO,KAAK,CAAC;QACpC,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC,IAAI,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QACtE,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC5B,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;YAChE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,2CAA2C;IAC3C,aAAa;QACX,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;IAC1B,CAAC;CACF;AAED,uEAAuE;AAEvE,IAAI,iBAAiB,GAA8B,IAAI,CAAC;AAExD;;;;;GAKG;AACH,SAAS,oBAAoB;IAC3B,IAAI,iBAAiB,KAAK,IAAI,EAAE,CAAC;QAC/B,iBAAiB,GAAG,IAAI,kBAAkB,EAAE,CAAC;IAC/C,CAAC;IACD,OAAO,iBAAiB,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAkB;IAC7C,OAAO,oBAAoB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3C,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,6BAA6B;IAC3C,iBAAiB,GAAG,IAAI,CAAC;AAC3B,CAAC"}

package/dist/ui/statusline.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Statusline HUD — pure renderer for the CLI / TUI status line.
+ *
+ * Inspired by the claude-hud port (jarrodwatts/claude-hud) which exposes
+ * a single-line status display: mode, model, context %, cost. Other
+ * implementations (Cursor, Cline statuslines) follow the same pattern.
+ *
+ * This module ships the LOGIC ONLY. UI binding is the caller's job —
+ * the interactive REPL, `wotann status`, and external `claude-hud`-style
+ * scripts can all consume the same string.
+ *
+ * Contract:
+ *   - `renderStatusline(input)` returns a single-line string.
+ *   - Pure: same input → same output. No I/O, no globals, no terminal
+ *     width detection (caller decides truncation).
+ *   - `renderStatuslineParts(input)` returns the same data as an
+ *     ordered array of segments, so callers that want to render with
+ *     ANSI colors can wrap each segment in their own escape codes.
+ *
+ * Why a function (not a class)?
+ *   The file-organization rules require many small files and immutable
+ *   data; rendering a status string is a pure transformation, so a
+ *   class would be ceremony. The TUI keybindings module ships the same
+ *   way — pure helpers re-used across surfaces.
+ */
+/**
+ * Execution mode shown in the status line. Mirrors the modes broadcast
+ * by `wotann:execution-mode` events on the Desktop side, plus a few
+ * aliases the TUI can use directly.
+ */
+export type StatuslineMode = "interactive" | "autopilot" | "dry-run" | "review" | "audit" | "plan" | "act";
+export interface StatuslineInput {
+    /** Active mode label — drives the leading badge. */
+    readonly mode: StatuslineMode | string;
+    /** Provider/model id. Empty → renders "no model". */
+    readonly model: string;
+    /** Tokens used in the active context window. */
+    readonly contextUsed: number;
+    /** Total tokens available. ≤0 → percent omitted. */
+    readonly contextTotal: number;
+    /** Session cost in USD. <0 → cost segment omitted. */
+    readonly cost: number;
+    /**
+     * Optional separator string between segments.
+     * Defaults to " │ " (Unicode box-drawing) which matches the existing
+     * UI tokens. Pass " | " for ASCII-only terminals.
+     */
+    readonly separator?: string;
+    /**
+     * Optional provider id rendered as a parenthetical hint when present.
+     * Most callers pack provider into `model` already; this lets surfaces
+     * that track them separately keep the formatting consistent.
+     */
+    readonly provider?: string;
+}
+export interface StatuslineSegment {
+    readonly key: "mode" | "model" | "context" | "cost";
+    readonly text: string;
+    /** Severity hint — callers can map to color escapes. */
+    readonly severity: "ok" | "warn" | "critical";
+}
+/**
+ * Build the ordered segment list. Callers that want ANSI colors can
+ * walk this list and apply escape codes per-key. The default
+ * `renderStatusline` joins segment text with the separator.
+ */
+export declare function renderStatuslineParts(input: StatuslineInput): readonly StatuslineSegment[];
+/**
+ * Render the statusline as a single string suitable for direct
+ * terminal display. Plain text only — no ANSI escapes, so callers
+ * that want color should walk `renderStatuslineParts` instead.
+ */
+export declare function renderStatusline(input: StatuslineInput): string;
+//# sourceMappingURL=statusline.d.ts.map

package/dist/ui/statusline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statusline.d.ts","sourceRoot":"","sources":["../../src/ui/statusline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,WAAW,GACX,SAAS,GACT,QAAQ,GACR,OAAO,GACP,MAAM,GACN,KAAK,CAAC;AAEV,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAAC;IACvC,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oDAAoD;IACpD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,IAAI,GAAG,MAAM,GAAG,UAAU,CAAC;CAC/C;AA0CD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,iBAAiB,EAAE,CAkC1F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAK/D"}

package/dist/ui/statusline.js

@@ -0,0 +1,111 @@
+/**
+ * Statusline HUD — pure renderer for the CLI / TUI status line.
+ *
+ * Inspired by the claude-hud port (jarrodwatts/claude-hud) which exposes
+ * a single-line status display: mode, model, context %, cost. Other
+ * implementations (Cursor, Cline statuslines) follow the same pattern.
+ *
+ * This module ships the LOGIC ONLY. UI binding is the caller's job —
+ * the interactive REPL, `wotann status`, and external `claude-hud`-style
+ * scripts can all consume the same string.
+ *
+ * Contract:
+ *   - `renderStatusline(input)` returns a single-line string.
+ *   - Pure: same input → same output. No I/O, no globals, no terminal
+ *     width detection (caller decides truncation).
+ *   - `renderStatuslineParts(input)` returns the same data as an
+ *     ordered array of segments, so callers that want to render with
+ *     ANSI colors can wrap each segment in their own escape codes.
+ *
+ * Why a function (not a class)?
+ *   The file-organization rules require many small files and immutable
+ *   data; rendering a status string is a pure transformation, so a
+ *   class would be ceremony. The TUI keybindings module ships the same
+ *   way — pure helpers re-used across surfaces.
+ */
+// ── Helpers ──────────────────────────────────────────────
+const DEFAULT_SEPARATOR = " │ ";
+const WARN_PERCENT = 70;
+const CRITICAL_PERCENT = 88;
+/** Format a USD cost with sensible precision for a one-line readout. */
+function formatCost(value) {
+    if (!Number.isFinite(value) || value < 0)
+        return "—";
+    if (value === 0)
+        return "$0.00";
+    if (value >= 1)
+        return `$${value.toFixed(2)}`;
+    if (value >= 0.01)
+        return `$${value.toFixed(3)}`;
+    return `$${value.toFixed(4)}`;
+}
+/** Compute % used as an integer 0..100, clamped. */
+function percentUsed(used, total) {
+    if (total <= 0)
+        return 0;
+    const raw = Math.round((used / total) * 100);
+    if (!Number.isFinite(raw))
+        return 0;
+    return Math.max(0, Math.min(100, raw));
+}
+/** Thousands-separator formatting that doesn't depend on locale. */
+function formatTokens(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return "0";
+    return Math.round(n)
+        .toString()
+        .replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+/** Truncate to a max length without breaking the trailing punctuation. */
+function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    if (max <= 1)
+        return "…";
+    return `${value.slice(0, max - 1)}…`;
+}
+// ── Public API ───────────────────────────────────────────
+/**
+ * Build the ordered segment list. Callers that want ANSI colors can
+ * walk this list and apply escape codes per-key. The default
+ * `renderStatusline` joins segment text with the separator.
+ */
+export function renderStatuslineParts(input) {
+    const modeRaw = (input.mode ?? "").toString().trim();
+    const modeLabel = modeRaw === "" ? "ready" : modeRaw;
+    const modelRaw = (input.model ?? "").toString().trim();
+    const providerRaw = (input.provider ?? "").toString().trim();
+    const modelText = modelRaw === ""
+        ? "no model"
+        : providerRaw === ""
+            ? truncate(modelRaw, 32)
+            : `${truncate(modelRaw, 24)} (${truncate(providerRaw, 16)})`;
+    const total = Math.max(0, Math.floor(input.contextTotal ?? 0));
+    const used = Math.max(0, Math.floor(input.contextUsed ?? 0));
+    const pct = percentUsed(used, total);
+    const ctxSeverity = pct >= CRITICAL_PERCENT ? "critical" : pct >= WARN_PERCENT ? "warn" : "ok";
+    const ctxText = total <= 0
+        ? `ctx ${formatTokens(used)}`
+        : `ctx ${pct}% (${formatTokens(used)}/${formatTokens(total)})`;
+    const segments = [
+        { key: "mode", text: `[${modeLabel}]`, severity: "ok" },
+        { key: "model", text: modelText, severity: "ok" },
+        { key: "context", text: ctxText, severity: ctxSeverity },
+    ];
+    if (typeof input.cost === "number" && input.cost >= 0) {
+        segments.push({ key: "cost", text: formatCost(input.cost), severity: "ok" });
+    }
+    return segments;
+}
+/**
+ * Render the statusline as a single string suitable for direct
+ * terminal display. Plain text only — no ANSI escapes, so callers
+ * that want color should walk `renderStatuslineParts` instead.
+ */
+export function renderStatusline(input) {
+    const sep = input.separator ?? DEFAULT_SEPARATOR;
+    return renderStatuslineParts(input)
+        .map((s) => s.text)
+        .join(sep);
+}
+//# sourceMappingURL=statusline.js.map

package/dist/ui/statusline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statusline.js","sourceRoot":"","sources":["../../src/ui/statusline.ts"],"names":[],"mappings":"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"}

package/dist/ui/string-width-cache.d.ts

@@ -0,0 +1,204 @@
+/**
+ * T12.14 — Int32Array TUI string-width / column-position optimizer
+ * (~700 LOC, V9 §T12.14, line 2746).
+ *
+ * Goal:
+ *   Replace per-character `stringWidth(ch)` calls in TUI rendering with
+ *   an Int32Array-backed lookup keyed by codepoint. The Int32Array maps
+ *   codepoint → display-width so the TUI can compute column positions
+ *   without round-tripping `stringWidth` per character per frame.
+ *
+ *   Match Anthropic's leaked Claude Code internal TUI optimizer pattern
+ *   (50× speedup on emoji + CJK heavy renders).
+ *
+ * Design:
+ *   - One Int32Array sized to cover the Basic Multilingual Plane
+ *     (codepoints 0..0xFFFF). Sentinel `WIDTH_SENTINEL` (-1) means
+ *     "not yet computed"; fill on first read.
+ *   - Codepoints above the BMP fall through to the underlying
+ *     `stringWidth` impl. They occur much less often (mostly emoji) so
+ *     a small auxiliary Map is used to avoid re-parsing the same emoji
+ *     repeatedly without consuming the Int32Array's 256KB-of-memory
+ *     budget.
+ *   - The hot path is a single `cache[cp]` access plus an integer
+ *     `width === -1` branch. No string allocation, no Map lookup, no
+ *     subprocess.
+ *   - String-level helper (`cachedStringWidth`) walks the string by
+ *     codepoint (not by char unit) so surrogate pairs are summed once,
+ *     not twice.
+ *   - Column-position helper (`columnPositionsFor`) returns an
+ *     Int32Array of cumulative widths so callers can binary-search to
+ *     find the column at a given character index without rescanning.
+ *   - Cache-instance form (`StringWidthCache`) is the canonical entry
+ *     point: per-call/per-renderer state, not module-global. A
+ *     module-level singleton (`getDefaultCache`) is exposed for the
+ *     runtime to share one cache across the process when desired.
+ *
+ * Quality bars honoured:
+ *   - QB #6  honest stubs: `cachedCharWidthSafe` returns
+ *     `{ok:false, reason}` for invalid codepoints (NaN, negative,
+ *     >0x10FFFF) — never silently coerced.
+ *   - QB #7  per-call state: `StringWidthCache` is a class with
+ *     instance state; module-level singleton is opt-in via
+ *     `getDefaultCache()`.
+ *   - QB #13 env guard: never reads process.env. Caller threads
+ *     options via `StringWidthCacheOptions`.
+ *   - QB #14 commit-claim verification: tests assert numeric
+ *     equivalence with the underlying string-width package across
+ *     ASCII / CJK / emoji / surrogate-pair / mixed strings, not just
+ *     stub shapes.
+ */
+/** Highest codepoint that we directly index in the Int32Array.
+ *  0x10000 = 65536 = full BMP coverage. Memory cost: 256 KiB
+ *  (Int32Array stores 4 bytes per entry). */
+export declare const BMP_CACHE_SIZE = 65536;
+/** Highest valid Unicode codepoint. Above this is invalid. */
+export declare const MAX_CODEPOINT = 1114111;
+/** Sentinel value for "uncomputed" entries. Chosen as -1 so a single
+ *  signed-int comparison against the cache is enough. */
+export declare const WIDTH_SENTINEL = -1;
+export interface StringWidthCacheOptions {
+    /** Override the underlying string-width implementation. Tests use
+     *  this; production callers leave it undefined. */
+    readonly impl?: (s: string) => number;
+    /**
+     * When true, codepoints above the BMP also get cached (in an
+     *  auxiliary Map). Default true. Disable to keep memory tight in
+     *  long-running daemons that render many one-off emoji.
+     */
+    readonly cacheAstral?: boolean;
+    /**
+     * Maximum number of entries kept in the astral-plane Map before
+     * least-recently-inserted eviction kicks in. Caps the worst-case
+     * memory footprint when a session encounters many one-off emoji
+     * (e.g. a big paste of mixed scripts). Default 1024.
+     *
+     * The BMP cache is bounded by definition (256 KiB Int32Array) and
+     * never evicts; this only affects the astral fallback Map.
+     */
+    readonly astralMaxEntries?: number;
+    /** Optional ambiguous-is-narrow flag passed to the underlying impl.
+     *  Defaults to string-width's own default (true). */
+    readonly ambiguousIsNarrow?: boolean;
+}
+/** Default astral-Map cap. Approximately 1024 entries × ~16B/entry ≈
+ *  16 KiB worst case — small relative to the BMP table. */
+export declare const DEFAULT_ASTRAL_MAX_ENTRIES = 1024;
+export interface StringWidthCacheStats {
+    readonly bmpFilled: number;
+    readonly astralFilled: number;
+    readonly bmpHits: number;
+    readonly bmpMisses: number;
+    readonly astralHits: number;
+    readonly astralMisses: number;
+    /** Number of LRU evictions performed against the astral Map. Will
+     *  remain 0 unless the session exceeds `astralMaxEntries`. */
+    readonly astralEvictions: number;
+}
+/** Result wrapper for the safe-form helpers (QB #6). */
+export type CharWidthResult = {
+    readonly ok: true;
+    readonly width: number;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Per-instance Int32Array-backed string-width cache. Construct one
+ * per renderer (TUI, App.tsx) so caches don't bleed across unrelated
+ * sessions. Use `getDefaultCache()` for a process-wide singleton when
+ * sharing is desired.
+ */
+export declare class StringWidthCache {
+    private readonly bmp;
+    private readonly astral;
+    private readonly astralMaxEntries;
+    private readonly impl;
+    private bmpHitsCount;
+    private bmpMissesCount;
+    private bmpFilledCount;
+    private astralHitsCount;
+    private astralMissesCount;
+    private astralEvictionsCount;
+    constructor(opts?: StringWidthCacheOptions);
+    /**
+     * Width of a single codepoint. Hot path — called per-char per-frame.
+     *
+     * Defensive: NaN / negative / out-of-range codepoints fall through to
+     *  width 0 (the agreed sentinel for "not displayable"), with a
+     *  miss-count bump so observability sees the bad input. Use
+     *  `charWidthSafe` to surface the error.
+     */
+    charWidth(codepoint: number): number;
+    /**
+     * Honest-stub variant for callers that want to surface invalid
+     * codepoints. Returns `{ok:false, reason}` rather than coercing
+     * silently.
+     */
+    charWidthSafe(codepoint: number): CharWidthResult;
+    /**
+     * Total visual width of a string. Walks by codepoint so a surrogate
+     * pair contributes one width, not two.
+     */
+    stringWidth(s: string): number;
+    /**
+     * Return cumulative column positions for each codepoint in the input.
+     *
+     * The returned Int32Array has length `(codepointCount + 1)` where
+     * `result[i]` = visual column of the start of the i-th codepoint
+     * (result[0] is always 0; result[N] is the total visual width).
+     * Allows O(log N) lookup of the column a given codepoint sits in via
+     * binary search rather than rescanning.
+     */
+    columnPositionsFor(s: string): Int32Array;
+    /**
+     * Find the codepoint index that lands at (or just past) the given
+     * visual column. Useful for cursor-position math on the screen.
+     *
+     * - Returns 0 for column ≤ 0.
+     * - Returns codepoint count when column ≥ total width.
+     */
+    codepointIndexAtColumn(s: string, column: number): number;
+    /** Drop cached entries. Caller probably wants this only across
+     *  major renderer resets — the cache is otherwise self-managing. */
+    clear(): void;
+    /** Snapshot of cache stats. Useful for benchmarks + observability. */
+    stats(): StringWidthCacheStats;
+    /** Convenience: warm the cache for the printable ASCII range
+     *  (0x20..0x7E) on construction-adjacent code paths. Used by the TUI
+     *  bootstrap to avoid first-frame jank. */
+    warmAscii(): void;
+}
+/**
+ * Process-wide singleton, opt-in. Useful for the runtime when many
+ * renderers share width state and a per-instance cache would cause
+ * redundant fill work on the same codepoints.
+ *
+ * Per QB #7, callers can — and should — construct their own
+ * `new StringWidthCache()` when isolation matters (tests, sandboxed
+ * subagents). The singleton is just a convenience.
+ */
+export declare function getDefaultCache(): StringWidthCache;
+/** Reset the module-level singleton. Tests use this to keep runs
+ *  hermetic. Production callers shouldn't need it. */
+export declare function resetDefaultCache(): void;
+/**
+ * Width of a single codepoint via the default singleton. Equivalent
+ * to `getDefaultCache().charWidth(cp)`.
+ */
+export declare function cachedCharWidth(codepoint: number): number;
+/**
+ * Width of a string via the default singleton. Equivalent to
+ * `getDefaultCache().stringWidth(s)`.
+ */
+export declare function cachedStringWidth(s: string): number;
+/**
+ * Column positions of a string via the default singleton. Equivalent
+ * to `getDefaultCache().columnPositionsFor(s)`.
+ */
+export declare function cachedColumnPositionsFor(s: string): Int32Array;
+/**
+ * Locate the codepoint at a column via the default singleton.
+ */
+export declare function cachedCodepointIndexAtColumn(s: string, column: number): number;
+//# sourceMappingURL=string-width-cache.d.ts.map

package/dist/ui/string-width-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-width-cache.d.ts","sourceRoot":"","sources":["../../src/ui/string-width-cache.ts"],"names":[],"mappings":"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"}