aiden-runtime 4.1.4 → 4.1.5

package/dist/cli/v4/aidenCLI.js

@@ -1057,6 +1057,34 @@ async function buildAgentRuntime(cliOpts, opts) {
                 // diagnostics must not break the loop
             }
         },
+        // v4.1.5 Issue K — phase lifecycle hooks for the activity indicator
+        // verb mutation. Each fires at a specific point in runConversation:
+        //   - onMemoryRefreshStart: before memory I/O begins
+        //   - onPromptBuilt: after system prompt assembly
+        //   - onProviderRequestStart: just before the HTTP request opens
+        // chatSession registers handlers that call `indicator.setVerb()` so
+        // the user sees the model's actual workflow phase during the gap.
+        // All three are forwarded through `callbacks` so chatSession owns
+        // the indicator handle (created per-turn). Defensive try/catch on
+        // each — a misbehaving display sink never blocks the agent loop.
+        onMemoryRefreshStart: () => {
+            try {
+                callbacks.onMemoryRefreshStart?.();
+            }
+            catch { /* defensive */ }
+        },
+        onPromptBuilt: (info) => {
+            try {
+                callbacks.onPromptBuilt?.(info);
+            }
+            catch { /* defensive */ }
+        },
+        onProviderRequestStart: (id) => {
+            try {
+                callbacks.onProviderRequestStart?.(id);
+            }
+            catch { /* defensive */ }
+        },
         // Phase 23.4b — feed the agent's Stage-0 intent pre-arm with the
         // skill's `required_tools` from its SKILL.md frontmatter.  Returns
         // null when the skill is unknown / unloaded / empty so the agent

package/dist/cli/v4/callbacks.js

@@ -63,6 +63,29 @@ class CliCallbacks {
         this.toolRows = new Map();
         this.toolStartTimes = new Map();
         this.firstToolFiredThisTurn = false;
+        // v4.1.5 Issue K — `firePhaseVerb` is the public entry point for the
+        // AidenCLI bridge. AidenAgent fires `onMemoryRefreshStart` etc.,
+        // aidenCLI's adapter calls into one of these `onPhase…` shims, each
+        // mapping a lifecycle event to a verb string. Defensive try/catch so
+        // a misbehaving display sink can't unwind the agent loop.
+        this.onMemoryRefreshStart = () => {
+            try {
+                this.phaseVerbHook?.('refreshing memory');
+            }
+            catch { /* defensive */ }
+        };
+        this.onPromptBuilt = (_info) => {
+            try {
+                this.phaseVerbHook?.('preparing prompt');
+            }
+            catch { /* defensive */ }
+        };
+        this.onProviderRequestStart = (_providerId) => {
+            try {
+                this.phaseVerbHook?.('calling provider');
+            }
+            catch { /* defensive */ }
+        };
         /**
          * Phase 23.5 — bound to AidenAgent.onToolCall. Emits one event row
          * per tool call: prints `[running]` on `before`, mutates the bracket
@@ -91,6 +114,14 @@ class CliCallbacks {
                     this.beforeToolHook?.();
                 }
                 catch { /* defensive */ }
+                // v4.1.5+ Path A — fire the loop-trace sink BEFORE row writes.
+                // Captures every tool's call.id + name (including hidden ones
+                // suppressed from the visible trail) so the trace covers the
+                // full agent loop, not just user-visible work.
+                try {
+                    this.toolTraceBeforeHook?.(call.id, call.name);
+                }
+                catch { /* defensive */ }
                 const handle = this.display.toolRow(call.name, call.arguments);
                 this.toolRows.set(call.id, handle);
                 this.toolStartTimes.set(call.id, Date.now());
@@ -109,12 +140,25 @@ class CliCallbacks {
                     this.afterEachToolHook?.(call.name);
                 }
                 catch { /* defensive */ }
+                // v4.1.5+ Path A — loop-trace sink fires even when handle was
+                // lost (rare; happens if before/after pairing slipped) so the
+                // trace never under-counts tool calls.
+                try {
+                    this.toolTraceAfterHook?.(call.id, call.name, call.arguments);
+                }
+                catch { /* defensive */ }
                 return;
             }
             const ms = Date.now() - startedAt;
             const err = result?.error;
             if (typeof err === 'string' && err.includes('URL provenance gate')) {
                 handle.blocked();
+                // v4.1.5+ Path A — blocked path still needs the trace sink so
+                // the URL-provenance failure mode shows up in loop diagnostics.
+                try {
+                    this.toolTraceAfterHook?.(call.id, call.name, call.arguments);
+                }
+                catch { /* defensive */ }
                 return;
             }
             // v4.1.4 reply-quality polish — Part 1.6. Helper used by ALL
@@ -127,6 +171,14 @@ class CliCallbacks {
                     this.afterEachToolHook?.(call.name);
                 }
                 catch { /* defensive */ }
+                // v4.1.5+ Path A — also fire the loop-trace `after` sink so the
+                // tracer can compute duration + capture args (hidden-from-trail
+                // tools still flow through here, by design — the trace must see
+                // them to detect lookup_tool_schema / skill_view loops).
+                try {
+                    this.toolTraceAfterHook?.(call.id, call.name, call.arguments);
+                }
+                catch { /* defensive */ }
             };
             if (typeof err === 'string' && err.includes('URL provenance gate')) {
                 handle.blocked();
@@ -337,6 +389,32 @@ Reply with ONE word: safe, caution, or dangerous.`;
         this.beforeToolHook = opts.beforeTool;
         this.afterEachToolHook = opts.afterEachTool;
     }
+    /**
+     * v4.1.5 Issue K — set/clear the phase-verb sink. chatSession
+     * registers a closure that captures the per-turn indicator handle
+     * and forwards calls to `indicator.setVerb(verb)`. Cleared between
+     * turns by passing `undefined`. Optional — non-indicator callers
+     * (test harnesses with stub displays) get no-op behaviour.
+     */
+    setPhaseVerbHook(fn) {
+        this.phaseVerbHook = fn;
+    }
+    /**
+     * v4.1.5+ Path A — register a per-turn tool-trace sink for the
+     * loop-trace logger. `before` fires with the call's id+name BEFORE
+     * the row writes; `after` fires post-execution with the same id +
+     * the call's args (for skill-name extraction in trace context).
+     * Cleared between turns by passing `undefined`.
+     *
+     * Separate from `setActivityIndicatorHooks` because the activity
+     * hook is name-only and fires for visible-trail purposes; this
+     * one captures FULL call data including hidden tools (which the
+     * trail suppresses via TRAIL_HIDE_TOOLS but the trace must see).
+     */
+    setToolTraceHook(opts) {
+        this.toolTraceBeforeHook = opts.before;
+        this.toolTraceAfterHook = opts.after;
+    }
 }
 exports.CliCallbacks = CliCallbacks;
 // Tier-3.1 (v4.1-tier3.1): replaced 🟢/🟡/🔴 emoji badges with

package/dist/cli/v4/chatSession.js

@@ -69,6 +69,11 @@ exports.renderProgressBar = renderProgressBar;
 exports.formatTokens = formatTokens;
 exports.formatDuration = formatDuration;
 exports.renderMemoryConfirmations = renderMemoryConfirmations;
+// v4.1.5+ Path A: env-var-gated loop trace logger. Captures tool-call
+// sequence + system prompt + memory hashes when a turn shows loop
+// symptoms (10+ calls OR 5+ consecutive same-name). Default off via
+// `AIDEN_DEBUG_LOOP=1` env-var. Zero overhead when disabled.
+const loopTrace_1 = require("../../core/v4/loopTrace");
 const display_1 = require("./display");
 // v4.1.4 Part 1.6 — per-turn token progress bar. Fed by `onProgress`
 // events from the streaming adapter; hidden when the adapter doesn't
@@ -934,6 +939,62 @@ class ChatSession {
         const indicator = this.opts.display.activityIndicator('thinking');
         let indicatorStopped = false;
         let streamingActive = false;
+        // v4.1.5 Issue O — track whether this turn had any tool calls so
+        // we can emit a single muted rule between the tool trail and the
+        // reply header. Set true when the first tool's `before` phase
+        // fires (via the existing beforeFirstToolHook plumbing). Emitted
+        // once per turn — `separatorEmitted` gates idempotency against
+        // both streaming and non-streaming paths reaching the same hook.
+        //
+        // v4.1.5 Phase 1d (Q-OBV-b) — multi-tool separator regression:
+        // the prior v4.1.5 Phase 1c emission point was the streaming
+        // `onFirstDelta` callback, but that fires PER provider call
+        // (the agent resets `firstDeltaFired` each callProvider
+        // invocation), and on multi-tool turns where the model emits
+        // no preamble in early iterations + no preamble in the final
+        // reply iteration either, the relative ordering of "first
+        // delta" vs "first tool" could leave the flag/idempotency
+        // gate in an unexpected state. Definitive fix: tie emission
+        // to the FIRST STREAM BYTE LANDING ON SCREEN, which only
+        // happens once per turn regardless of how many provider
+        // iterations occurred. `firstStreamByteSeen` is the new gate;
+        // separator fires from inside `onDelta` BEFORE `streamPartial`
+        // writes the agent header.
+        let turnHadTools = false;
+        let separatorEmitted = false;
+        let firstStreamByteSeen = false;
+        // v4.1.5+ Path A: per-turn loop tracer (env-var gated, default off).
+        // Captures tool-call sequence + assembled system prompt + memory
+        // hashes + recent skills when a turn trips loop thresholds. The
+        // `onLoopWarning` callback surfaces a one-line dim hint to the
+        // user when consecutive-same-tool count crosses 8 — gives them a
+        // chance to Ctrl+C before the agent burns more budget.
+        const loopTracer = new loopTrace_1.LoopTracer({
+            paths: this.opts.paths,
+            providerId: this.currentProviderId,
+            modelId: this.currentModelId,
+            onLoopWarning: (line) => {
+                try {
+                    this.opts.display.dim(line);
+                }
+                catch { /* defensive */ }
+            },
+        });
+        if (loopTracer.isEnabled()) {
+            loopTracer.setHistory(baseHistory);
+        }
+        const emitToolReplySeparator = () => {
+            if (separatorEmitted || !turnHadTools)
+                return;
+            separatorEmitted = true;
+            // Same chrome pattern as the existing pre-turn rule (line ~1100)
+            // and the post-reply rule (line ~1297): two-space indent + the
+            // body-width muted rule + newline. The 2-space indent is the
+            // legacy convention used by adjacent rules; the v4.1.5 frame
+            // gutter (3) is consciously NOT applied here so all three rules
+            // in a turn share one left edge.
+            this.opts.display.write(`  ${this.opts.display.rule()}\n`);
+        };
         const stopIndicatorOnce = () => {
             if (indicatorStopped)
                 return;
@@ -946,12 +1007,55 @@ class ChatSession {
                 this.opts.callbacks.setActivityIndicatorHooks?.({});
             }
             catch { /* defensive */ }
+            // v4.1.5 Issue K — also clear the phase-verb sink so lifecycle
+            // events fired during async cleanup don't try to update a
+            // stopped indicator.
+            try {
+                this.opts.callbacks.setPhaseVerbHook?.(undefined);
+            }
+            catch { /* defensive */ }
+            // v4.1.5+ Path A — clear the loop-trace sink so subsequent
+            // turns don't fire into a stale tracer. Note: this clears the
+            // HOOK, not the tracer's accumulated state — finalize() still
+            // runs at end-of-try below to write the snapshot if thresholds
+            // tripped.
+            try {
+                this.opts.callbacks.setToolTraceHook?.({});
+            }
+            catch { /* defensive */ }
         };
+        // v4.1.5 Issue K — wire the per-turn phase-verb sink. Each
+        // AidenAgent lifecycle event (memory refresh start, prompt built,
+        // provider request start) flows through CliCallbacks and lands
+        // here as a verb string ("refreshing memory" / "preparing prompt"
+        // / "calling provider"). The closure captures the per-turn
+        // indicator handle so verb mutations stay scoped to this turn.
+        this.opts.callbacks.setPhaseVerbHook?.((verb) => {
+            if (indicatorStopped)
+                return;
+            indicator.setVerb(verb);
+        });
+        // v4.1.5+ Path A — wire the loop-trace sink. Fires for EVERY tool
+        // call (including hidden ones) so the trace captures the full
+        // agent loop. Defensive — when AIDEN_DEBUG_LOOP is unset, the
+        // tracer's `startTool`/`endTool` short-circuit immediately.
+        this.opts.callbacks.setToolTraceHook?.({
+            before: (id, name) => loopTracer.startTool(id, name),
+            after: (id, name, args) => loopTracer.endTool(id, name, args),
+        });
         // Phase 23.5 carried forward: stop the indicator the moment the
         // first tool row prints — the row itself is the activity surface
         // during a tool. Part 1.6 then resumes via `afterEachTool` so the
         // post-tool gap has its own indicator paint.
-        this.opts.callbacks.setBeforeFirstToolHook?.(stopIndicatorOnce);
+        //
+        // v4.1.5 Issue O — also flip `turnHadTools = true` so the
+        // separator emits before the reply header. Single hook captures
+        // "any tool ran this turn" cleanly (it only fires for the FIRST
+        // tool of the turn — subsequent tools don't re-trigger).
+        this.opts.callbacks.setBeforeFirstToolHook?.(() => {
+            turnHadTools = true;
+            stopIndicatorOnce();
+        });
         // Part 1.6: pause/resume hooks around every tool row. The
         // `beforeTool` hook fires before EACH tool row writes (not just
         // the first), so multi-tool sequences also keep the indicator
@@ -991,10 +1095,32 @@ class ChatSession {
                     ? () => {
                         stopIndicatorOnce();
                         streamingActive = true;
+                        // v4.1.5 Phase 1d (Q-OBV-b) — separator emission MOVED
+                        // out of onFirstDelta because that callback fires per
+                        // provider-call iteration (firstDeltaFired resets each
+                        // callProvider invocation). The separator-emit now
+                        // lives in onDelta below, gated by `firstStreamByteSeen`
+                        // which only flips once per turn.
                     }
                     : undefined,
                 onDelta: streamingEnabled
                     ? (text) => {
+                        // v4.1.5 Phase 1d (Q-OBV-b) — definitive separator
+                        // emission point. This is the FIRST text byte landing
+                        // on screen this turn. Fires the muted rule BEFORE
+                        // streamPartial writes the `┃ Aiden` header so the
+                        // visual order is:
+                        //   ┊ tool rows...
+                        //   ────────────  ← separator
+                        //   ┃ Aiden
+                        //   {text}
+                        // Idempotent via `firstStreamByteSeen` + the
+                        // `separatorEmitted` flag inside emitToolReplySeparator.
+                        // No-op when no tool fired (turnHadTools=false).
+                        if (!firstStreamByteSeen) {
+                            firstStreamByteSeen = true;
+                            emitToolReplySeparator();
+                        }
                         // v4.1.4 Part 1.6: bar lives ABOVE streamed text. Hide
                         // it before each delta writes so the stream output
                         // doesn't land on the bar's line. The bar repaints on
@@ -1055,6 +1181,11 @@ class ChatSession {
             // When streaming was active and emitted the final content already,
             // skip the markdown re-render — we'd otherwise duplicate text.
             if (result.finalContent && !streamingActive) {
+                // v4.1.5 Issue O — non-streaming reply path. Emit the muted
+                // rule between the tool trail and the agent header before
+                // the one-shot reply lands. Idempotent + tool-gated by
+                // `emitToolReplySeparator`.
+                emitToolReplySeparator();
                 this.opts.display.write(this.opts.display.agentTurn(result.finalContent));
             }
             if (this.sessionId) {
@@ -1068,6 +1199,18 @@ class ChatSession {
             // post-turn status footer.
             this.opts.display.write(`  ${this.opts.display.rule()}\n`);
             this.renderStatusLine();
+            // v4.1.5+ Path A — finalize the loop trace. No-op if the env
+            // var is unset OR if the turn didn't trip any threshold. When
+            // it DOES emit, the snapshot path goes to a dim status line so
+            // the user (and any teammate they're sharing the log with)
+            // knows where to grab the diagnostic file.
+            try {
+                const snapPath = await loopTracer.finalize();
+                if (snapPath) {
+                    this.opts.display.dim(`[loop-trace] wrote ${snapPath}`);
+                }
+            }
+            catch { /* defensive */ }
         }
         catch (err) {
             stopIndicatorOnce();
@@ -1116,6 +1259,16 @@ class ChatSession {
             }
             this.setStatusState({ kind: 'ready' });
             this.lastTurnElapsedMs = Date.now() - turnStartedAt;
+            // v4.1.5+ Path A — finalize the loop trace on the error path
+            // too. Loop patterns that ended in an error are exactly the
+            // ones most worth capturing for diagnosis.
+            try {
+                const snapPath = await loopTracer.finalize();
+                if (snapPath) {
+                    this.opts.display.dim(`[loop-trace] wrote ${snapPath}`);
+                }
+            }
+            catch { /* defensive */ }
         }
     }
     // ── Startup card (Phase 26.2.4: neofetch-style sectioned) ──────────

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.4';
-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).
@@ -47,7 +47,7 @@ Voice:
 
 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.
 
@@ -318,6 +318,78 @@ 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/progressBar.js

@@ -52,8 +52,22 @@ const display_1 = require("../display");
  */
 const BAR_CELLS = 10;
 /** Glyphs. Chosen for clean visual weight at the standard mono font. */
-const FILLED = '▰';
-const EMPTY = '▱';
+// 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
@@ -89,19 +103,38 @@ function createProgressBar(out, skin) {
         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;
-        // `\r\x1b[K` — carriage return + erase to end of line, then
-        // rewrite. Same single-line overwrite pattern as the activity
-        // indicator and tool-row live tick.
-        out.write(`\r\x1b[K${buildLine()}`);
-        printed = true;
+        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('\r\x1b[K');
+            out.write(ANSI_UP_ERASE);
     };
     return {
         update(n, max) {