aiden-runtime 4.1.3 → 4.1.5

package/dist/cli/v4/defaultSoul.js

@@ -30,8 +30,8 @@ exports.PREVIOUS_BUNDLED_SOULS = exports.DEFAULT_SOUL_MD = exports.BUNDLED_SOUL_
 // <act_dont_ask>. ensureSoulMdSeeded compares this against the user's
 // on-disk SOUL.md to decide whether to silent-replace (matches a prior
 // bundled default) or preserve+notify (user-edited).
-exports.BUNDLED_SOUL_VERSION = 'v4.1.2';
-exports.DEFAULT_SOUL_MD = `You are Aiden — a local-first AI agent built by Taracod.
+exports.BUNDLED_SOUL_VERSION = 'v4.1.5';
+exports.DEFAULT_SOUL_MD = `You are Aiden — a local-first AI agent built by Shiva Deore at Taracod.
 
 Identity:
 - You run on the user's machine, native Windows/Linux/macOS (not WSL2).
@@ -40,13 +40,14 @@ Identity:
 - You have 40 tools spanning files, browser, terminal, web, memory.
 
 Voice:
-- Direct. No fluff. Match the user's energy.
+- Match the user's energy. When the user asks a thoughtful question (opinion, exploration, comparison), engage thoughtfully. When the user asks transactionally, stay tight.
+- On thoughtful questions, share the reasoning before the answer — what you considered, what you discarded, why.
 - Honest above all — if you didn't do something, say so. If you're not sure, say so.
 - You never claim to "have run" a tool unless the trace shows it.
 
 Behavior:
 - Default to action over discussion. The user wants results.
-- When asked who you are, identify as Aiden. Not "a large language model."
+- When asked who you are, identify as Aiden, built by Shiva Deore at Taracod. Not "a large language model."
 - When asked what you can do, mention specific skills/tools, not generic capabilities.
 - If user mentions trading/NSE/markets, you have specialized skills for that.
 
@@ -254,5 +255,143 @@ Limits:
 - You're a CLI agent in v4.0.0. No voice, no scheduled jobs, no messaging gateway yet — those are v4.1.
 - You can't bypass approval prompts for dangerous commands.
 - You don't lie to look smart. If you don't know, you say so.
+`,
+    // v4.1.2 default — shipped through v4.1.3 (no SOUL change in v4.1.3).
+    // v4.1.4 rewrites the Voice block to make conciseness conditional:
+    // thoughtful questions get thoughtful engagement, transactional
+    // questions stay tight. Adds an explicit reasoning-visibility line.
+    // Users on the v4.1.2 / v4.1.3 install have this verbatim text on
+    // disk; silent-upgrade picks them up here.
+    `You are Aiden — a local-first AI agent built by Taracod.
+
+Identity:
+- You run on the user's machine, native Windows/Linux/macOS (not WSL2).
+- You have 72 bundled skills + access to install more via skills.sh.
+- You remember past sessions via persistent storage.
+- You have 40 tools spanning files, browser, terminal, web, memory.
+
+Voice:
+- Direct. No fluff. Match the user's energy.
+- Honest above all — if you didn't do something, say so. If you're not sure, say so.
+- You never claim to "have run" a tool unless the trace shows it.
+
+Behavior:
+- Default to action over discussion. The user wants results.
+- When asked who you are, identify as Aiden. Not "a large language model."
+- When asked what you can do, mention specific skills/tools, not generic capabilities.
+- If user mentions trading/NSE/markets, you have specialized skills for that.
+
+<act_dont_ask>
+When a request has an obvious default interpretation, act on it
+immediately instead of asking for clarification. Examples:
+- "play me a popular song" / "play X on youtube" → load skill_view(media-search)
+  and follow it. Substitute fuzzy phrases ("popular song") with a specific
+  chart-topper BEFORE searching, then open_url a /watch?v= URL once.
+  NEVER search verbatim "popular song" — that returns articles, not music.
+- "what files are in my Downloads?" → file_list on Downloads. Don't ask
+  "which user?" — it's the current user.
+- "is port 443 open?" → check this machine. Don't ask "open where?"
+Only ask for clarification when the ambiguity genuinely changes which
+tool you would call.
+</act_dont_ask>
+
+<prerequisite_checks>
+Before acting, check whether prerequisite discovery, lookup, or
+context-gathering steps are needed. If a step depends on output from a
+prior step, resolve that dependency first. Don't skip prerequisite
+steps just because the final action seems obvious.
+</prerequisite_checks>
+
+<missing_context>
+If required context is missing, do NOT guess or hallucinate. Use the
+appropriate lookup tool when missing information is retrievable
+(file_read, file_list, web_search, fetch_url, session_search,
+system_info). Ask a clarifying question ONLY when no tool can resolve
+the ambiguity.
+</missing_context>
+
+<keep_going>
+Work autonomously until the task is fully resolved. Don't stop with a
+plan — execute it. Multi-step tasks (open browser → search → click
+result; or list files → read each → summarise) are expected; chain
+the tool calls within a single turn instead of returning halfway and
+asking the user what to do next.
+</keep_going>
+
+Limits:
+- You can't bypass approval prompts for dangerous commands.
+- You don't lie to look smart. If you don't know, you say so.
+`,
+    // v4.1.4 default — Voice rewrite ("Match the user's energy. When the
+    // user asks a thoughtful question…") + EXECUTION_DISCIPLINE_PROSE
+    // softening. Identity attribution still "built by Taracod" only —
+    // v4.1.5 adds "Shiva Deore at" to both identity lines. Users who
+    // installed any v4.1.4.x build have this verbatim text on disk;
+    // silent-upgrade picks them up here.
+    //
+    // CATCH-UP NOTE: this entry was inadvertently omitted from the
+    // v4.1.4 ship (the snapshot appended at that time matched v4.1.2's
+    // Voice block, not the v4.1.4 rewrite). v4.1.5 appends it so the
+    // migration path catches v4.1.4 installs correctly.
+    `You are Aiden — a local-first AI agent built by Taracod.
+
+Identity:
+- You run on the user's machine, native Windows/Linux/macOS (not WSL2).
+- You have 72 bundled skills + access to install more via skills.sh.
+- You remember past sessions via persistent storage.
+- You have 40 tools spanning files, browser, terminal, web, memory.
+
+Voice:
+- Match the user's energy. When the user asks a thoughtful question (opinion, exploration, comparison), engage thoughtfully. When the user asks transactionally, stay tight.
+- On thoughtful questions, share the reasoning before the answer — what you considered, what you discarded, why.
+- Honest above all — if you didn't do something, say so. If you're not sure, say so.
+- You never claim to "have run" a tool unless the trace shows it.
+
+Behavior:
+- Default to action over discussion. The user wants results.
+- When asked who you are, identify as Aiden. Not "a large language model."
+- When asked what you can do, mention specific skills/tools, not generic capabilities.
+- If user mentions trading/NSE/markets, you have specialized skills for that.
+
+<act_dont_ask>
+When a request has an obvious default interpretation, act on it
+immediately instead of asking for clarification. Examples:
+- "play me a popular song" / "play X on youtube" → load skill_view(media-search)
+  and follow it. Substitute fuzzy phrases ("popular song") with a specific
+  chart-topper BEFORE searching, then open_url a /watch?v= URL once.
+  NEVER search verbatim "popular song" — that returns articles, not music.
+- "what files are in my Downloads?" → file_list on Downloads. Don't ask
+  "which user?" — it's the current user.
+- "is port 443 open?" → check this machine. Don't ask "open where?"
+Only ask for clarification when the ambiguity genuinely changes which
+tool you would call.
+</act_dont_ask>
+
+<prerequisite_checks>
+Before acting, check whether prerequisite discovery, lookup, or
+context-gathering steps are needed. If a step depends on output from a
+prior step, resolve that dependency first. Don't skip prerequisite
+steps just because the final action seems obvious.
+</prerequisite_checks>
+
+<missing_context>
+If required context is missing, do NOT guess or hallucinate. Use the
+appropriate lookup tool when missing information is retrievable
+(file_read, file_list, web_search, fetch_url, session_search,
+system_info). Ask a clarifying question ONLY when no tool can resolve
+the ambiguity.
+</missing_context>
+
+<keep_going>
+Work autonomously until the task is fully resolved. Don't stop with a
+plan — execute it. Multi-step tasks (open browser → search → click
+result; or list files → read each → summarise) are expected; chain
+the tool calls within a single turn instead of returning halfway and
+asking the user what to do next.
+</keep_going>
+
+Limits:
+- You can't bypass approval prompts for dangerous commands.
+- You don't lie to look smart. If you don't know, you say so.
 `,
 ];

package/dist/cli/v4/display/frame.js

@@ -0,0 +1,234 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/display/frame.ts — Phase v4.1.4 reply-quality polish (Part 1.5).
+ *
+ * Single source of truth for the reply-frame math: terminal width,
+ * left gutter, body width, indent-by-depth, and ANSI-aware soft wrap.
+ *
+ * Before this module the same width formula
+ * (`Math.min(out.columns ?? 80, 100)`) lived at 4 different sites with
+ * inconsistent offsets, no shared floor, and no actual wrap engine —
+ * `marked-terminal` has `reflowText: false` so long prose just spilled
+ * to terminal-natural wrap (continuation lines at column 0, not at the
+ * gutter). frame.ts replaces all four with one formula and one wrapper.
+ *
+ * Public surface:
+ *   - GUTTER             3-col left gutter (assistant body)
+ *   - BODY_WIDTH_MAX     100 (tunable cap; export so future skin/theme
+ *                        work can override without touching consumers)
+ *   - getTerminalCols()  live `process.stdout.columns` with 80 fallback
+ *   - getBodyWidth()     `max(20, cols - gutter - 2)` capped at
+ *                        `BODY_WIDTH_MAX - gutter - 2`
+ *   - getIndent(depth)   `' '.repeat(GUTTER + depth*2)` — gutter +
+ *                        depth-aware. depth=0 = bare gutter, depth=1 =
+ *                        gutter+2, etc.
+ *   - wrap(text, opts)   ANSI-aware soft wrap via wrap-ansi defaults
+ *                        `{ trim: false, hard: true }`. Returns string
+ *                        with embedded `\n` per wrap point.
+ *   - applyFrame(body)   convenience: indents every line of `body` by
+ *                        GUTTER. No wrap (caller pre-wraps to bodyWidth).
+ *
+ * Wrap engine: wrap-ansi@9 (ESM-only). Loaded via cached dynamic
+ * `import()` so a CJS TypeScript build can still consume it. Until the
+ * first wrap finishes resolving, `wrap()` falls back to a passthrough
+ * that preserves the input verbatim — wrong visual but never incorrect
+ * data. Boot-time prime via `primeFrameAsync()` (best-effort) so the
+ * first user-visible wrap call already has the module loaded.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BODY_WIDTH_MIN = exports.BODY_WIDTH_MAX = exports.GUTTER = void 0;
+exports.getTerminalCols = getTerminalCols;
+exports.getBodyWidth = getBodyWidth;
+exports.getIndent = getIndent;
+exports.primeFrameAsync = primeFrameAsync;
+exports.wrap = wrap;
+exports.applyFrame = applyFrame;
+exports._resetForTests = _resetForTests;
+exports._injectWrapForTests = _injectWrapForTests;
+// ── Tunable constants ─────────────────────────────────────────────────
+/**
+ * Left gutter for assistant body. 3 columns matches the visual rhythm
+ * established by the boot card, tool trail, and status footer once
+ * Part 1.5 lands. Was 2 before this slice — bumped one column so the
+ * body breathes against the left edge.
+ */
+exports.GUTTER = 3;
+/**
+ * Maximum body width before the visual frame stops growing. Wide
+ * terminals (150+ cols) get a body capped at this minus gutter+2
+ * because long lines (~120 chars) are harder to read than mid-length
+ * (~70-90 chars). Tunable: skin or theme code can override.
+ */
+exports.BODY_WIDTH_MAX = 100;
+/**
+ * Hard floor on body width. Below this we render at 20 cols and let
+ * the terminal-natural wrap pick up the rest — better than crashing
+ * with a negative-width wrap-ansi call on a 5-col terminal.
+ */
+exports.BODY_WIDTH_MIN = 20;
+// ── Width helpers ─────────────────────────────────────────────────────
+/**
+ * Live terminal column count. Reads `process.stdout.columns` on every
+ * call so resize events propagate without us needing a cache. Falls
+ * back to 80 when the stream is non-TTY or hasn't reported a size yet
+ * (pipes, CI logs, MCP serve).
+ *
+ * `out` override exists for testability — display.test.ts injects a
+ * fake stream with explicit `columns` to assert various widths.
+ */
+function getTerminalCols(out = process.stdout) {
+    const c = out.columns;
+    if (typeof c !== 'number' || !Number.isFinite(c) || c < 1)
+        return 80;
+    return c;
+}
+/**
+ * Computed body width — the safe horizontal space inside the frame.
+ * Math: `min(BODY_WIDTH_MAX, cols) - GUTTER - 2`. The trailing `-2`
+ * leaves visual breathing room on the right margin (mirrors the boot
+ * card / tool-row right-pad convention). Floored at BODY_WIDTH_MIN so
+ * pathological narrow terminals still get a usable wrap.
+ */
+function getBodyWidth(out = process.stdout) {
+    const cols = Math.min(getTerminalCols(out), exports.BODY_WIDTH_MAX);
+    const raw = cols - exports.GUTTER - 2;
+    return Math.max(exports.BODY_WIDTH_MIN, raw);
+}
+/**
+ * Indent string for the given nesting depth. Depth 0 = bare gutter
+ * (3 spaces). Each additional level adds 2 spaces. Used by list,
+ * blockquote, and code-block renderers so every element shares one
+ * indent algebra.
+ */
+function getIndent(depth = 0) {
+    const d = Math.max(0, Math.floor(depth));
+    return ' '.repeat(exports.GUTTER + d * 2);
+}
+let cachedWrap = null;
+let primePromise = null;
+/**
+ * Best-effort load of wrap-ansi. Idempotent. Safe to call from boot.
+ * Returns a promise that resolves once the module is loaded (or
+ * rejects silently — wrap() will just keep using the passthrough).
+ */
+function primeFrameAsync() {
+    if (cachedWrap)
+        return Promise.resolve();
+    if (primePromise)
+        return primePromise;
+    primePromise = (async () => {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const mod = await Promise.resolve().then(() => __importStar(require('wrap-ansi')));
+            const fn = (mod.default ?? mod);
+            if (typeof fn === 'function')
+                cachedWrap = fn;
+        }
+        catch {
+            // Swallow — fallback is a passthrough, never crashes.
+        }
+    })();
+    return primePromise;
+}
+// Kick off the import at module load. Best effort — if it fails (e.g.
+// missing dep, broken install) we degrade to passthrough.
+primeFrameAsync();
+/**
+ * ANSI-aware soft wrap. Defaults `{ trim: false, hard: true }`:
+ *   - trim: false → preserves leading/trailing whitespace on each
+ *     visual line (important for code-block indent + alignment).
+ *   - hard: true  → break extremely long words mid-character at width
+ *     instead of overflowing. Code blocks especially need this.
+ *
+ * Pure with respect to ANSI: escape sequences pass through wrap-ansi
+ * untouched and don't count toward the column budget.
+ *
+ * Synchronous. When wrap-ansi hasn't finished loading yet (the rare
+ * boot-race window), returns `text` unchanged. The user sees the
+ * un-wrapped paint exactly once; by the next render the cache is hot.
+ */
+function wrap(text, cols, options = {}) {
+    const w = cachedWrap;
+    if (!w)
+        return text;
+    const opts = { trim: options.trim ?? false, hard: options.hard ?? true };
+    try {
+        return w(text, cols, opts);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * Indent every line of `body` by the bare gutter. Empty lines are
+ * passed through unindented so blank visual rows don't carry
+ * trailing whitespace into the transcript.
+ *
+ * Caller is responsible for pre-wrapping to `getBodyWidth()` — this
+ * function is purely the indent step, not the wrap step. Keeping them
+ * separate so callers that already have their own indent (lists,
+ * code blocks) can opt out of this and still consume `wrap()`.
+ */
+function applyFrame(body) {
+    const ind = getIndent(0);
+    return body
+        .split('\n')
+        .map((ln) => (ln.length === 0 ? '' : `${ind}${ln}`))
+        .join('\n');
+}
+/**
+ * Test reset — drops the cached wrap function so a fresh prime can be
+ * forced. Used by unit tests to exercise the fallback path AND to
+ * confirm post-prime behaviour.
+ */
+function _resetForTests() {
+    cachedWrap = null;
+    primePromise = null;
+}
+/**
+ * Test injection — set the wrap function explicitly. Used by tests
+ * that want deterministic behaviour without depending on dynamic
+ * `import()` resolution timing.
+ */
+function _injectWrapForTests(fn) {
+    cachedWrap = fn;
+}

package/dist/cli/v4/display/progressBar.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/display/progressBar.ts — Phase v4.1.4 Part 1.6.
+ *
+ * Per-turn token progress bar. Renders `▰▰▰▰▰▱▱▱▱▱  412/4096 tokens`
+ * on a single line below the activity indicator (or in place of it,
+ * once the stream takes over). Event-driven: each `update(n, max)`
+ * call redraws the bar with the new counter — no `setInterval`,
+ * because the source of truth is the adapter's incremental
+ * `progress` stream events, which already fire at the granularity
+ * the model produces tokens.
+ *
+ * Honest degradation: if the adapter never calls `update()`, the bar
+ * never paints. No client-side estimation (per v4.1.4 spec — token
+ * count only, no time-based fakery).
+ *
+ * Visual:
+ *
+ *     ▰▰▰▰▰▱▱▱▱▱  412/4096 tokens
+ *     │└────┬───┘  └────┬─────┘
+ *     │     │           └── current/max (compact via formatCompactTokens)
+ *     │     └── 10 cells, filled ratio ∝ outputTokens/maxTokens
+ *     └── leading gutter aligns with frame
+ *
+ * Bar cells:
+ *   - filled: ▰ (U+25B0, dark shade block-fill)
+ *   - empty:  ▱ (U+25B1, light shade)
+ *
+ * Cursor invariant on render: bar OWNS one line. After each `update`
+ * the cursor sits at column 0 of the bar line (single-line `\r\x1b[K`
+ * overwrite pattern, same as activityIndicator). Callers that want to
+ * write OTHER content below MUST call `hide()` first.
+ *
+ * Non-TTY: completely silent — pipes/CI/MCP serve mode get clean
+ * output by default. The handle still accepts updates so callers
+ * don't need to branch on TTY-ness.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProgressBar = createProgressBar;
+const frame_1 = require("./frame");
+const display_1 = require("../display");
+/**
+ * Number of bar cells. 10 cells gives clean fractions (every 10% of
+ * fill ratio == one cell). Wider bars feel noisy at the standard
+ * frame width (75 visible cols on an 80-col terminal).
+ */
+const BAR_CELLS = 10;
+/** Glyphs. Chosen for clean visual weight at the standard mono font. */
+// v4.1.5 Phase 1d (Q-P1) — glyph palette switch.
+//
+// Was `▰` (U+25B0 BLACK RECTANGLE) + `▱` (U+25B1 WHITE RECTANGLE),
+// from Unicode's "Geometric Shapes" block. NOT in CP437; Windows
+// legacy console fonts (Lucida Console / Consolas defaults) render
+// them as tofu boxes. User visual smoke confirmed the regression
+// on Windows Terminal + ConPTY combinations.
+//
+// New: `▓` (U+2593 DARK SHADE) + `░` (U+2591 LIGHT SHADE), from
+// Unicode's "Block Elements" block AND CP437 — universally
+// supported on every Windows console going back to DOS. Same shade
+// family the existing `statusFooter` (display.ts:773) has shipped
+// with since v3 without ever being garbled. Cleaner palette
+// coherence across all bar surfaces.
+const FILLED = '▓';
+const EMPTY = '░';
+/**
+ * Create a progress-bar handle bound to a writable stream + skin.
+ * The bar paints on the next `update` call — there's no initial
+ * paint at creation time, because we don't know the token counts yet.
+ *
+ * `out` is the stream to write on (usually `process.stdout` via
+ * `Display.out`). `skin` is the active skin engine. Both are captured
+ * by closure — the handle survives skin swaps for the rest of the turn.
+ */
+function createProgressBar(out, skin) {
+    const isTty = !!out.isTTY;
+    let outputTokens = 0;
+    let maxTokens = undefined;
+    let printed = false;
+    let hidden = false;
+    let lastPaintTokens = -1;
+    const buildLine = () => {
+        // Fill ratio: 0..1, then snap to a cell count 0..BAR_CELLS.
+        const denom = maxTokens && maxTokens > 0 ? maxTokens : 0;
+        const ratio = denom > 0 ? Math.min(1, outputTokens / denom) : 0;
+        const filled = Math.min(BAR_CELLS, Math.round(ratio * BAR_CELLS));
+        const empty = BAR_CELLS - filled;
+        const bar = skin.applyColors(FILLED.repeat(filled), 'brand') +
+            skin.applyColors(EMPTY.repeat(empty), 'muted');
+        // Label: compact "412/4096 tokens". If no maxTokens, render
+        // "412 tokens" (denominator unknown). The model name doesn't
+        // belong here — that's the status footer's job post-turn.
+        const left = (0, display_1.formatCompactTokens)(outputTokens);
+        const right = denom > 0 ? (0, display_1.formatCompactTokens)(denom) : '?';
+        const label = denom > 0
+            ? skin.applyColors(`${left}/${right} tokens`, 'muted')
+            : skin.applyColors(`${left} tokens`, 'muted');
+        const gutter = (0, frame_1.getIndent)(0);
+        return `${gutter}${bar}  ${label}`;
+    };
+    // v4.1.5 Part 1a — Issue M (Windows ConPTY buffering fix).
+    //
+    // Mirrors the activityIndicator pattern: the bar OWNS one terminal
+    // row. Every paint ends with `\n` so the buffer flushes; the cursor
+    // sits on the row BELOW the bar while it's visible. Erase walks
+    // up + clears the bar's row, leaving the cursor at col 0 of the
+    // now-empty row for the caller's next write. See activityIndicator
+    // for the full rationale (Windows ConPTY buffers no-newline writes
+    // until a `\n` arrives — without this, long-running stream paints
+    // never visually appeared).
+    const ANSI_UP_ERASE = '\x1b[1A\x1b[2K';
+    const paint = () => {
+        if (!isTty || hidden)
+            return;
+        if (printed) {
+            // Subsequent paint: walk up to the bar's row, clear it, rewrite,
+            // drop a newline so the cursor lands on the row BELOW the bar.
+            out.write(`${ANSI_UP_ERASE}${buildLine()}\n`);
+        }
+        else {
+            // First paint: just write the bar + `\n`. Cursor moves to the
+            // row below, ready for subsequent walk-up-and-erase ticks.
+            out.write(`${buildLine()}\n`);
+            printed = true;
+        }
+        lastPaintTokens = outputTokens;
+    };
+    const erase = () => {
+        // Walk up to the bar's row and clear it. No trailing `\n` — the
+        // caller will write content here and include its own newline.
+        if (isTty && printed)
+            out.write(ANSI_UP_ERASE);
+    };
+    return {
+        update(n, max) {
+            if (hidden)
+                return;
+            // Coerce + clamp. Non-finite or negative inputs are ignored —
+            // never crash the stream consumer with a malformed event.
+            if (typeof n === 'number' && Number.isFinite(n) && n >= 0) {
+                outputTokens = Math.floor(n);
+            }
+            if (typeof max === 'number' && Number.isFinite(max) && max > 0) {
+                maxTokens = Math.floor(max);
+            }
+            // Dedup: skip the repaint if the visible state didn't change.
+            // Anthropic emits message_delta events with the SAME running
+            // counter when no new tokens were produced; without this
+            // gate we'd flicker on every duplicate.
+            if (outputTokens === lastPaintTokens && printed)
+                return;
+            paint();
+        },
+        hide() {
+            if (hidden)
+                return;
+            hidden = true;
+            erase();
+        },
+        isHidden() { return hidden; },
+        getTokens() {
+            return { output: outputTokens, max: maxTokens };
+        },
+    };
+}