aiden-runtime 4.9.0 → 4.9.1

package/README.md

@@ -94,7 +94,7 @@ Windows · Linux · WSL · macOS (API Mode)
 ![Built solo](https://img.shields.io/badge/Built-solo-B8A893?style=flat-square)
 ![By Taracod](https://img.shields.io/badge/By-Taracod-FF6B35?style=flat-square)
 ![White Lotus](https://img.shields.io/badge/Brand-White_Lotus-FFB088?style=flat-square)
-![v4.9.0](https://img.shields.io/badge/Latest-v4.9.0-4ADE80?style=flat-square)
+![v4.9.1](https://img.shields.io/badge/Latest-v4.9.1-4ADE80?style=flat-square)
 
 </div>
 

package/dist/cli/v4/aidenCLI.js

@@ -568,7 +568,7 @@ async function main(argv, opts = {}) {
     });
     program
         .command('voice [args...]')
-        .description('Voice diagnostics + one-shot TTS / transcribe (Phase v4.1-voice-cli). ' +
+        .description('Voice diagnostics + one-shot TTS / transcribe. ' +
         'Usage: aiden voice doctor | tts "<text>" | transcribe <file>')
         .allowUnknownOption()
         .action(async (args) => {
@@ -611,7 +611,7 @@ async function main(argv, opts = {}) {
     // v4.1 placeholders. (`tui` graduated to a real flag in Phase 15.)
     program
         .command('cron [args...]')
-        .description('Cron diagnostics + one-shot list / run (Phase v4.1 hardened cron). ' +
+        .description('Cron diagnostics + one-shot list / run. ' +
         'Usage: aiden cron status | list | run <id>')
         .allowUnknownOption()
         .action(async (args) => {

package/dist/cli/v4/chatSession.js

@@ -1656,6 +1656,10 @@ class ChatSession {
         // .update_check.json cache so subsequent boots stay quiet until
         // a newer release ships.
         try {
+            // v4.9.1 — modal sits BELOW the welcome banner with a blank
+            // separator. Prevents the box from visually overlapping the
+            // boot card on first-paint (smoke-reported regression).
+            display.write('\n');
             await this.maybeShowBootUpdatePrompt();
         }
         catch { /* never let the update prompt crash boot */ }
@@ -1713,13 +1717,24 @@ class ChatSession {
         });
         if (choice === 'install') {
             if (method.inProcessInstallSupported) {
-                this.opts.display.write(`Installing aiden-runtime ${status.latest}…\n`);
-                const result = await ei.executeInstall({ packageSpec: `aiden-runtime@${status.latest}` });
+                // v4.9.1 — drive a live progress bar off the executor's
+                // phase callback. The bar degrades cleanly on non-TTY, NO_COLOR,
+                // and dumb terminals — see cli/v4/ui/progressBar.ts.
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const pb = require('./ui/progressBar');
+                const bar = pb.startProgressBar({
+                    label: `Installing aiden-runtime ${status.latest}...`,
+                    phases: ['spawning', 'resolving', 'downloading', 'extracting', 'verifying', 'installed'],
+                });
+                const result = await ei.executeInstall({
+                    packageSpec: `aiden-runtime@${status.latest}`,
+                    onPhase: (p) => { bar.setPhase(p); bar.setPercent(pb.npmInstallPhasePercent(p)); },
+                });
                 if (result.success) {
-                    this.opts.display.write(`  ✓ aiden-runtime ${result.installedVersion ?? status.latest} installed.\n`);
-                    this.opts.display.dim('Restart Aiden to apply: type /quit then re-run `aiden`.');
+                    bar.complete(`aiden-runtime ${result.installedVersion ?? status.latest} installed. Restart Aiden to apply: type /quit then re-run \`aiden\`.`);
                 }
                 else {
+                    bar.fail('Install failed.');
                     this.opts.display.warn(result.error ?? 'Install failed (no error message).');
                 }
             }

package/dist/cli/v4/commands/daemon.js

@@ -104,10 +104,15 @@ async function runDaemonSubcommand(action, args, opts = {}) {
                 writeErr: err,
             });
         }
-        default:
+        default: {
             err(`Unknown daemon action: ${action}\n`);
+            const { closestAction } = await Promise.resolve().then(() => __importStar(require('../util/closestAction')));
+            const m = closestAction(action, ['install', 'uninstall', 'start', 'stop', 'restart', 'status', 'logs', 'doctor']);
+            if (m)
+                err(`Did you mean: ${m}?\n\n`);
             err('Actions: install, uninstall, start, stop, restart, status, logs, doctor\n');
             return 2;
+        }
     }
 }
 const SYSTEMD_UNIT_NAME = 'aiden.service';

package/dist/cli/v4/commands/daemonDoctor.js

@@ -89,7 +89,7 @@ function collectDoctorChecks(rootDir) {
         ORDER BY started_at DESC LIMIT 1`).get();
         if (!inc) {
             checks.push({ name: 'recent incarnation', status: 'warn',
-                detail: 'no daemon_incarnations rows (daemon never booted post-Slice-4)',
+                detail: 'no daemon_incarnations rows (daemon never started in this root)',
                 fixable: false });
         }
         else {

package/dist/cli/v4/commands/daemonStatus.js

@@ -22,44 +22,63 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.daemonStatus = void 0;
+exports.daemonStatus = exports.DAEMON_SHELL_ONLY = void 0;
+exports.dispatchDaemonSlash = dispatchDaemonSlash;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
-const daemon_1 = require("../../../core/v4/daemon");
+const daemon_1 = require("./daemon");
+const daemon_2 = require("../../../core/v4/daemon");
 const paths_1 = require("../../../core/v4/paths");
+/**
+ * v4.9.1 amendment — `/daemon` defaults to `doctor` and routes
+ * `doctor` / `logs` to the existing `runDaemonSubcommand`. The pure-
+ * REPL `/daemon status` (in-process snapshot) stays inline. Lifecycle
+ * ops shell-hint — they need terminal control we can't grant inside chat.
+ */
+exports.DAEMON_SHELL_ONLY = new Set(['install', 'uninstall', 'start', 'stop', 'restart']);
+async function dispatchDaemonSlash(opts) {
+    const a = (opts.action || 'doctor').toLowerCase();
+    if (exports.DAEMON_SHELL_ONLY.has(a)) {
+        opts.write(`⚠ /daemon ${a} not available inside chat (requires terminal control)\n`);
+        opts.write('  Quit (/quit) and run from shell:\n\n');
+        const tail = opts.args.length > 0 ? ' ' + opts.args.join(' ') : '';
+        opts.write(`    aiden daemon ${a}${tail}\n`);
+        return;
+    }
+    if (a === 'status' && opts.paintStatus) {
+        try {
+            opts.paintStatus();
+        }
+        catch (e) {
+            opts.warn(`/daemon status: failed to read state (${e instanceof Error ? e.message : String(e)})`);
+        }
+        return;
+    }
+    await opts.runDaemon(a, opts.args, { writeOut: opts.write, writeErr: opts.write });
+}
 exports.daemonStatus = {
     name: 'daemon',
-    description: 'Show daemon status (read-only). Use `aiden daemon` for lifecycle.',
+    description: 'Daemon diagnostics (doctor / status / logs).',
     category: 'system',
     icon: '⚙',
     handler: async (ctx) => {
-        const sub = (ctx.args[0] ?? 'status').toLowerCase();
-        if (sub !== 'status') {
-            ctx.display.printError('Usage: /daemon status\n' +
-                'For lifecycle commands (install / start / stop / restart / logs), use the top-level CLI:\n' +
-                '  aiden daemon install\n' +
-                '  aiden daemon start\n' +
-                '  aiden daemon stop\n' +
-                '  aiden daemon status\n' +
-                '  aiden daemon logs');
-            return {};
-        }
-        try {
-            const snapshot = readSnapshot();
-            printSnapshot(snapshot, ctx);
-        }
-        catch (e) {
-            ctx.display.warn(`/daemon status: failed to read state (${e instanceof Error ? e.message : String(e)})`);
-        }
+        await dispatchDaemonSlash({
+            action: ctx.args[0] ?? 'doctor',
+            args: ctx.args.slice(1),
+            write: (s) => ctx.display.write(s),
+            warn: (s) => ctx.display.warn(s),
+            runDaemon: daemon_1.runDaemonSubcommand,
+            paintStatus: () => printSnapshot(readSnapshot(), ctx),
+        });
         return {};
     },
 };
 // ── Snapshot collector ─────────────────────────────────────────────────────
 function readSnapshot() {
     const aidenRoot = (0, paths_1.resolveAidenRoot)();
-    const dbPath = (0, daemon_1.daemonDbPath)(aidenRoot);
-    const lockPath = (0, daemon_1.daemonRuntimeLockPath)(aidenRoot);
+    const dbPath = (0, daemon_2.daemonDbPath)(aidenRoot);
+    const lockPath = (0, daemon_2.daemonRuntimeLockPath)(aidenRoot);
     // ── Liveness via the in-process bootstrap handle first, then fall
     // back to the runtime.lock PID check (covers the case where the
     // daemon is another process and we're a REPL inspecting its db).
@@ -67,11 +86,11 @@ function readSnapshot() {
     let instanceId = null;
     let port = null;
     let uptimeMs = null;
-    const handle = (0, daemon_1.getDaemonHandle)();
+    const handle = (0, daemon_2.getDaemonHandle)();
     if (handle?.active && handle.instanceId) {
         running = true;
         instanceId = handle.instanceId;
-        port = (0, daemon_1.getDaemonConfig)().port;
+        port = (0, daemon_2.getDaemonConfig)().port;
         if (handle.instanceTracker) {
             // instanceTracker has a `getStartedAt` if exposed; otherwise
             // derive from daemon_instances row below.
@@ -105,7 +124,7 @@ function readSnapshot() {
             dailyBudget: null,
         };
     }
-    const db = (0, daemon_1.openDaemonDb)(dbPath);
+    const db = (0, daemon_2.openDaemonDb)(dbPath);
     // Uptime from the instance row when we have an instanceId.
     if (running && instanceId) {
         try {

package/dist/cli/v4/commands/help.js

@@ -76,6 +76,9 @@ exports.SUBSECTION_MAP = {
     recovery: 'System',
     // v4.6 ONB1 slice 10 — new-user guided tour.
     walkthrough: 'System',
+    // v4.9.1 amendment — REPL surfaces for memory + hooks (daemon already mapped).
+    memory: 'System',
+    hooks: 'System',
     // ── Authentication ──
     auth: 'Authentication',
     // ── Help ──

package/dist/cli/v4/commands/hooks.js

@@ -23,6 +23,39 @@
  * directory and runs a rescan, but NEVER auto-trusts anything (trust
  * remains an explicit, deliberate user action).
  */
+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;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -78,10 +111,15 @@ async function runHooksSubcommand(action, args, opts = {}) {
             case 'audit': return await cmdAudit(ctx);
             case '--help':
             case 'help': return cmdHelp(out);
-            default:
+            default: {
                 err(`Unknown hooks action: ${effective}\n`);
+                const { closestAction } = await Promise.resolve().then(() => __importStar(require('../util/closestAction')));
+                const m = closestAction(effective, ['list', 'show', 'trust', 'revoke', 'rescan', 'test', 'doctor', 'audit']);
+                if (m)
+                    err(`Did you mean: ${m}?\n\n`);
                 cmdHelp(err);
                 return 2;
+            }
         }
     }
     finally {

package/dist/cli/v4/commands/hooksSlash.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hooks = exports.HOOKS_SHELL_ONLY = void 0;
+exports.dispatchHooksSlash = dispatchHooksSlash;
+const hooks_1 = require("./hooks");
+/** Actions that need an interactive confirmation prompt. */
+exports.HOOKS_SHELL_ONLY = new Set(['trust', 'revoke']);
+async function dispatchHooksSlash(opts) {
+    const a = (opts.action || 'list').toLowerCase();
+    if (exports.HOOKS_SHELL_ONLY.has(a)) {
+        opts.write(`⚠ /hooks ${a} not available inside chat (needs confirmation prompt)\n`);
+        opts.write('  Quit (/quit) and run from shell:\n\n');
+        const tail = opts.args.length > 0 ? ' ' + opts.args.join(' ') : '';
+        opts.write(`    aiden hooks ${a}${tail}\n`);
+        return;
+    }
+    await opts.runHooks(a, opts.args, { writeOut: opts.write, writeErr: opts.write });
+}
+exports.hooks = {
+    name: 'hooks',
+    description: 'Manage hooks (list / show / rescan / test / doctor / audit).',
+    category: 'system',
+    icon: '🪝',
+    handler: async (ctx) => {
+        await dispatchHooksSlash({
+            action: ctx.args[0] ?? 'list',
+            args: ctx.args.slice(1),
+            write: (s) => ctx.display.write(s),
+            runHooks: hooks_1.runHooksSubcommand,
+        });
+        return {};
+    },
+};

package/dist/cli/v4/commands/index.js

@@ -12,7 +12,7 @@
  * and registers each on the global CommandRegistry at boot.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.allCommands = exports.walkthrough = exports.recovery = exports.spawnPause = exports.plannerGuard = exports.suggestions = exports.daemonStatus = exports.browserDepth = exports.tce = exports.sandbox = exports.update = exports.reloadSoul = exports.history = exports.show = exports.status = exports.voice = exports.channel = exports.setup = exports.cron = exports.doctor = exports.license = exports.auth = exports.plugins = exports.streaming = exports.debugPrompt = exports.identity = exports.providers = exports.quit = exports.clear = exports.verbose = exports.reasoning = exports.reloadMcp = exports.skills = exports.theme = exports.skin = exports.yolo = exports.usage = exports.compress = exports.title = exports.save = exports.personality = exports.model = exports.tools = exports.help = void 0;
+exports.allCommands = exports.hooks = exports.memory = exports.walkthrough = exports.recovery = exports.spawnPause = exports.plannerGuard = exports.suggestions = exports.daemonStatus = exports.browserDepth = exports.tce = exports.sandbox = exports.update = exports.reloadSoul = exports.history = exports.show = exports.status = exports.voice = exports.channel = exports.setup = exports.cron = exports.doctor = exports.license = exports.auth = exports.plugins = exports.streaming = exports.debugPrompt = exports.identity = exports.providers = exports.quit = exports.clear = exports.verbose = exports.reasoning = exports.reloadMcp = exports.skills = exports.theme = exports.skin = exports.yolo = exports.usage = exports.compress = exports.title = exports.save = exports.personality = exports.model = exports.tools = exports.help = void 0;
 const help_1 = require("./help");
 Object.defineProperty(exports, "help", { enumerable: true, get: function () { return help_1.help; } });
 const tools_1 = require("./tools");
@@ -106,6 +106,11 @@ Object.defineProperty(exports, "recovery", { enumerable: true, get: function ()
 // ONB1 slice 10 — new-user guided tour.
 const walkthrough_1 = require("./walkthrough");
 Object.defineProperty(exports, "walkthrough", { enumerable: true, get: function () { return walkthrough_1.walkthrough; } });
+// v4.9.1 amendment — REPL slash surfaces for memory + hooks (mirrors CLI).
+const memorySlash_1 = require("./memorySlash");
+Object.defineProperty(exports, "memory", { enumerable: true, get: function () { return memorySlash_1.memory; } });
+const hooksSlash_1 = require("./hooksSlash");
+Object.defineProperty(exports, "hooks", { enumerable: true, get: function () { return hooksSlash_1.hooks; } });
 /** All built-in system commands, in canonical order. */
 exports.allCommands = [
     help_1.help,
@@ -158,6 +163,9 @@ exports.allCommands = [
     recovery_1.recovery,
     // ONB1 slice 10 — new-user guided tour.
     walkthrough_1.walkthrough,
+    // v4.9.1 amendment — REPL slash surfaces mirroring CLI subcommands.
+    memorySlash_1.memory,
+    hooksSlash_1.hooks,
     clear_1.clear,
     quit_1.quit,
 ];

package/dist/cli/v4/commands/memory.js

@@ -155,10 +155,15 @@ async function runMemorySubcommand(action, args, opts = {}) {
         case 'review': return cmdReview(args, paths, opts, out, err, json);
         case '--help':
         case 'help': return cmdHelp(out);
-        default:
+        default: {
             err(`Unknown memory action: ${effective}\n`);
+            const { closestAction } = await Promise.resolve().then(() => __importStar(require('../util/closestAction')));
+            const m = closestAction(effective, ['list', 'show', 'add', 'remove', 'edit', 'backup', 'restore', 'diff', 'namespaces', 'pending', 'approve', 'reject', 'review']);
+            if (m)
+                err(`Did you mean: ${m}?\n\n`);
             cmdHelp(err);
             return 2;
+        }
     }
 }
 function cmdHelp(write) {

package/dist/cli/v4/commands/memorySlash.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memory = exports.MEMORY_SHELL_ONLY = void 0;
+exports.dispatchMemorySlash = dispatchMemorySlash;
+const memory_1 = require("./memory");
+/** Actions that need the full CLI surface (confirmation / destructive). */
+exports.MEMORY_SHELL_ONLY = new Set(['remove', 'restore']);
+/**
+ * Pure dispatch — exported for tests + reuse. Either prints a shell
+ * hint OR delegates to the provided `runMemory` runner. Side effects
+ * confined to the supplied `write` sink.
+ */
+async function dispatchMemorySlash(opts) {
+    const a = (opts.action || 'list').toLowerCase();
+    if (exports.MEMORY_SHELL_ONLY.has(a)) {
+        opts.write(`⚠ /memory ${a} not available inside chat (destructive operation)\n`);
+        opts.write('  Quit (/quit) and run from shell:\n\n');
+        const tail = opts.args.length > 0 ? ' ' + opts.args.join(' ') : '';
+        opts.write(`    aiden memory ${a}${tail}\n`);
+        return;
+    }
+    await opts.runMemory(a, opts.args, { writeOut: opts.write, writeErr: opts.write });
+}
+exports.memory = {
+    name: 'memory',
+    description: 'Manage memory (list / show / add / namespaces / pending / approve / review).',
+    category: 'system',
+    icon: '🧠',
+    handler: async (ctx) => {
+        await dispatchMemorySlash({
+            action: ctx.args[0] ?? 'list',
+            args: ctx.args.slice(1),
+            write: (s) => ctx.display.write(s),
+            runMemory: memory_1.runMemorySubcommand,
+        });
+        return {};
+    },
+};

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

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/ui/progressBar.ts — v4.9.1 reusable progress animation.
+ * Auto-detects TTY / NO_COLOR / TERM=dumb / CI to pick render mode
+ * (block glyphs vs `#-`, color vs plain, animated vs once-per-second
+ * non-TTY lines). Cursor hidden during animation, restored on exit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectRenderMode = detectRenderMode;
+exports.renderLine = renderLine;
+exports.startProgressBar = startProgressBar;
+exports.npmInstallPhasePercent = npmInstallPhasePercent;
+exports.detectNpmPhase = detectNpmPhase;
+const DEFAULT_WIDTH = 28;
+const DEFAULT_TICK_MS = 100;
+/** Minimum elapsed before we paint anything — avoids flicker on sub-300ms ops. */
+const PAINT_AFTER_MS = 300;
+const ANSI_HIDE_CURSOR = '\x1b[?25l';
+const ANSI_SHOW_CURSOR = '\x1b[?25h';
+const ANSI_CLEAR_LINE = '\r\x1b[2K';
+const ANSI_BRAND = '\x1b[38;2;255;107;53m'; // RGB 255,107,53 (Aiden orange)
+const ANSI_MUTED = '\x1b[38;2;106;106;106m';
+const ANSI_SUCCESS = '\x1b[38;2;127;194;139m';
+const ANSI_ERROR = '\x1b[38;2;224;90;90m';
+const ANSI_RESET = '\x1b[0m';
+/** Detect the right render mode from TTY + env. Pure function. */
+function detectRenderMode(isTTY, env = process.env) {
+    if (!isTTY)
+        return { color: false, blocks: false, animated: false };
+    const noColor = env.NO_COLOR !== undefined && env.NO_COLOR !== '';
+    const dumb = env.TERM === 'dumb' || env.CI === 'true' || env.CI === '1';
+    return {
+        color: !noColor && !dumb,
+        blocks: !dumb,
+        animated: true,
+    };
+}
+/**
+ * Build the rendered line (without trailing newline). Pure so tests
+ * can assert byte-for-byte without timing.
+ */
+function renderLine(opts) {
+    const pct = Math.max(0, Math.min(100, Math.round(opts.percent)));
+    const filled = Math.round((pct / 100) * opts.width);
+    const empty = opts.width - filled;
+    const full = opts.mode.blocks ? '█' : '#';
+    const blank = opts.mode.blocks ? '░' : '-';
+    const elapsed = `${(opts.elapsedMs / 1000).toFixed(1)}s`;
+    const bar = full.repeat(filled) + blank.repeat(empty);
+    if (opts.mode.color) {
+        return `${ANSI_BRAND}[${bar}]${ANSI_RESET} ${pct}%  ${ANSI_MUTED}${opts.phase}${ANSI_RESET}  ${ANSI_MUTED}${elapsed}${ANSI_RESET}`;
+    }
+    return `[${bar}] ${pct}%  ${opts.phase}  ${elapsed}`;
+}
+/**
+ * Start a progress bar. Returns a controller object. Never throws —
+ * any I/O failure on output degrades the bar to a silent no-op while
+ * still honoring `complete` / `fail` semantics for the caller.
+ */
+function startProgressBar(opts) {
+    const width = opts.width ?? DEFAULT_WIDTH;
+    const out = opts.out ?? process.stdout;
+    const env = opts.env ?? process.env;
+    const tickMs = opts.tickMs ?? DEFAULT_TICK_MS;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const isTTY = opts.isTTY ?? Boolean(out.isTTY);
+    const mode = detectRenderMode(isTTY, env);
+    const startedAt = Date.now();
+    let phase = opts.phases[0] ?? '';
+    let percent = 0;
+    let painted = false;
+    let closed = false;
+    const write = (s) => {
+        try {
+            out.write(s);
+        }
+        catch { /* swallow — never break caller */ }
+    };
+    // SIGINT: restore cursor + clear the partial line before bubbling.
+    const onSigint = () => {
+        try {
+            write(ANSI_CLEAR_LINE + ANSI_SHOW_CURSOR);
+        }
+        catch { /* noop */ }
+    };
+    if (mode.animated) {
+        try {
+            process.once('SIGINT', onSigint);
+        }
+        catch { /* noop */ }
+    }
+    // Label line paints once, immediately.
+    write(`${mode.color ? ANSI_MUTED : ''}${opts.label}${mode.color ? ANSI_RESET : ''}\n`);
+    const paint = () => {
+        if (closed)
+            return;
+        const elapsedMs = Date.now() - startedAt;
+        if (elapsedMs < PAINT_AFTER_MS)
+            return;
+        const line = renderLine({ width, percent, phase, elapsedMs, mode });
+        if (mode.animated) {
+            if (!painted) {
+                write(ANSI_HIDE_CURSOR);
+                painted = true;
+            }
+            write(ANSI_CLEAR_LINE + line);
+        }
+        else {
+            write(line + '\n');
+        }
+    };
+    let timer = null;
+    if (mode.animated) {
+        timer = setInterval(paint, tickMs);
+        if (typeof timer.unref === 'function')
+            timer.unref();
+    }
+    const close = (icon, color, message) => {
+        if (closed)
+            return;
+        closed = true;
+        if (timer)
+            clearInterval(timer);
+        try {
+            process.removeListener('SIGINT', onSigint);
+        }
+        catch { /* noop */ }
+        const finalLine = mode.color
+            ? `${color}${icon}${ANSI_RESET} ${message}`
+            : `${icon} ${message}`;
+        if (mode.animated && painted)
+            write(ANSI_CLEAR_LINE);
+        write(finalLine + '\n');
+        if (mode.animated)
+            write(ANSI_SHOW_CURSOR);
+    };
+    return {
+        setPhase(name) { phase = name; if (!mode.animated)
+            paint(); },
+        setPercent(p) { percent = p; if (!mode.animated)
+            paint(); },
+        complete(message) { close('✓', ANSI_SUCCESS, message); },
+        fail(message) { close('✗', ANSI_ERROR, message); },
+    };
+}
+/** npm install phase → default percent. Best-effort bar shaping. */
+function npmInstallPhasePercent(phase) {
+    switch (phase) {
+        case 'spawning': return 3;
+        case 'resolving': return 15;
+        case 'downloading': return 50;
+        case 'extracting': return 85;
+        case 'verifying': return 97;
+        case 'installed': return 100;
+        case 'failed': return 100;
+        default: return 0;
+    }
+}
+/** Detect npm phase from a stdout/stderr line. Checks ordered for npm 9/10/11. */
+function detectNpmPhase(line) {
+    const l = line.toLowerCase();
+    if (l.includes('added ') && l.includes('package'))
+        return 'verifying';
+    if (l.includes('http fetch'))
+        return 'downloading';
+    if (l.includes('extracting') || l.includes('extract'))
+        return 'extracting';
+    if (l.includes('reify:'))
+        return 'downloading';
+    if (l.includes('resolved') || l.includes('audit'))
+        return 'resolving';
+    return null;
+}

package/dist/cli/v4/util/closestAction.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.closestAction = closestAction;
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/util/closestAction.ts — v4.9.1 amendment.
+ * Suggest the closest known action when the user mis-types a subcommand.
+ * Matches if input is a substring of a known action OR Levenshtein
+ * distance ≤ 2. Returns null when nothing is reasonably close.
+ */
+function lev(a, b) {
+    const m = a.length, n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const row = Array.from({ length: n + 1 }, (_, i) => i);
+    for (let i = 1; i <= m; i++) {
+        let prev = i - 1;
+        row[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cur = row[j];
+            row[j] = a[i - 1] === b[j - 1] ? prev : Math.min(prev, row[j - 1], row[j]) + 1;
+            prev = cur;
+        }
+    }
+    return row[n];
+}
+function closestAction(input, known) {
+    if (!input)
+        return null;
+    const lo = input.toLowerCase();
+    let best = null;
+    for (const k of known) {
+        const kl = k.toLowerCase();
+        if (kl.includes(lo) || lo.includes(kl))
+            return k;
+        const d = lev(lo, kl);
+        if (d <= 2 && (!best || d < best.d))
+            best = { name: k, d };
+    }
+    return best?.name ?? null;
+}

package/dist/core/v4/update/depWarningFilter.js

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/update/depWarningFilter.ts — v4.9.1.
+ *
+ * Strip Node `DeprecationWarning` noise (DEP0190 and friends) from
+ * npm install stderr before it reaches the user. Filtered lines are
+ * preserved in `~/.aiden/logs/update.log` so diagnostics aren't lost.
+ *
+ * Conservative match — only filters lines that BOTH look like a Node
+ * deprecation header AND name a DEP code or the trace-deprecation hint.
+ * Legitimate npm errors (EACCES, ENOTFOUND, ENOENT, etc.) pass through.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDeprecationLine = isDeprecationLine;
+exports.splitStderr = splitStderr;
+exports.logFilteredWarnings = logFilteredWarnings;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+/** True iff the line is Node-deprecation chatter we should hide. */
+function isDeprecationLine(line) {
+    // Node's deprecation banner header: "(node:NNNN) [DEP0190] DeprecationWarning: ..."
+    if (/^\s*\(node:\d+\)\s*(?:\[DEP\d+\]\s*)?DeprecationWarning:/.test(line))
+        return true;
+    // The follow-up hint Node emits underneath the header.
+    if (/Use `node --trace-deprecation/.test(line))
+        return true;
+    // Bare DEP code lines (some Node versions emit these stand-alone).
+    if (/^\s*\[DEP\d+\]/.test(line))
+        return true;
+    return false;
+}
+/**
+ * Split an stderr blob into `kept` (user-visible) and `filtered`
+ * (deprecation noise, routed to the diagnostic log).
+ */
+function splitStderr(blob) {
+    if (!blob)
+        return { kept: '', filtered: '' };
+    const lines = blob.split(/\r?\n/);
+    const kept = [];
+    const filtered = [];
+    for (const ln of lines) {
+        if (isDeprecationLine(ln))
+            filtered.push(ln);
+        else
+            kept.push(ln);
+    }
+    return { kept: kept.join('\n'), filtered: filtered.join('\n') };
+}
+/**
+ * Append filtered lines to `~/.aiden/logs/update.log` with an ISO
+ * timestamp header. Fail-open: a log-write failure must NEVER crash
+ * the install path.
+ */
+async function logFilteredWarnings(filtered, opts = {}) {
+    if (!filtered || !filtered.trim())
+        return;
+    try {
+        const root = opts.aidenRoot ?? node_path_1.default.join(node_os_1.default.homedir(), '.aiden');
+        const logDir = node_path_1.default.join(root, 'logs');
+        await node_fs_1.promises.mkdir(logDir, { recursive: true });
+        const entry = `[${new Date().toISOString()}] update.npm-deprecation:\n${filtered}\n\n`;
+        await node_fs_1.promises.appendFile(node_path_1.default.join(logDir, 'update.log'), entry, 'utf8');
+    }
+    catch { /* fail-open */ }
+}

package/dist/core/v4/update/executeInstall.js

@@ -42,11 +42,18 @@
  *   - No registry probe — call `checkForUpdate` first if you need to
  *     know whether an install is warranted.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.INSTALL_TIMEOUT_MS = void 0;
 exports.executeInstall = executeInstall;
 exports.parseInstalledVersion = parseInstalledVersion;
 const node_child_process_1 = require("node:child_process");
+const node_os_1 = __importDefault(require("node:os"));
+const depWarningFilter_1 = require("./depWarningFilter");
+const platformInstructions_1 = require("./platformInstructions");
+const progressBar_1 = require("../../../cli/v4/ui/progressBar");
 /** 90 s wall-clock cap. Generous on cold caches / slow networks. */
 exports.INSTALL_TIMEOUT_MS = 90000;
 const DEFAULT_PACKAGE_SPEC = 'aiden-runtime@latest';
@@ -64,6 +71,9 @@ async function executeInstall(opts = {}) {
     const timeoutMs = opts.timeoutMs ?? exports.INSTALL_TIMEOUT_MS;
     const packageSpec = opts.packageSpec ?? DEFAULT_PACKAGE_SPEC;
     const platform = opts.platform ?? process.platform;
+    const home = opts.home ?? node_os_1.default.homedir();
+    const env = opts.env ?? process.env;
+    const onPhase = opts.onPhase ?? ((_p) => { });
     return new Promise((resolve) => {
         const args = ['install', '-g', packageSpec];
         // v4.8.1 Slice 2 — drop `shell: true`. Node 20+ emits
@@ -78,6 +88,7 @@ async function executeInstall(opts = {}) {
         const spawnOpts = {
             stdio: ['ignore', 'pipe', 'pipe'],
         };
+        onPhase('spawning');
         let child;
         try {
             child = spawn(cmd, args, spawnOpts);
@@ -92,11 +103,23 @@ async function executeInstall(opts = {}) {
         }
         let stdoutBuf = '';
         let stderrBuf = '';
+        // v4.9.1 — parse phase signal off each chunk.
+        const tryEmitPhase = (chunk) => {
+            for (const ln of chunk.split(/\r?\n/)) {
+                const p = (0, progressBar_1.detectNpmPhase)(ln);
+                if (p)
+                    onPhase(p);
+            }
+        };
         child.stdout?.on('data', (chunk) => {
-            stdoutBuf += chunk.toString();
+            const s = chunk.toString();
+            stdoutBuf += s;
+            tryEmitPhase(s);
         });
         child.stderr?.on('data', (chunk) => {
-            stderrBuf += chunk.toString();
+            const s = chunk.toString();
+            stderrBuf += s;
+            tryEmitPhase(s);
         });
         // Timeout — kill the child + resolve as a failure with the captured
         // output so the user sees what npm was doing.
@@ -121,7 +144,11 @@ async function executeInstall(opts = {}) {
         child.on('close', (code) => {
             clearTimeout(timer);
             const stdout = stdoutBuf;
-            const stderr = stderrBuf;
+            // v4.9.1 — strip Node DEP* noise from stderr before any surfacing
+            // to the user. Filtered lines land in ~/.aiden/logs/update.log.
+            const { kept: stderr, filtered } = (0, depWarningFilter_1.splitStderr)(stderrBuf);
+            if (filtered)
+                void (0, depWarningFilter_1.logFilteredWarnings)(filtered);
             const exitCode = code ?? -1;
             if (timedOut) {
                 resolve({
@@ -134,14 +161,16 @@ async function executeInstall(opts = {}) {
             }
             // Permission-denied: surface platform-specific remediations.
             if (isPermissionDenied(stdout, stderr, exitCode)) {
+                onPhase('failed');
                 resolve({
                     success: false,
-                    error: permissionDeniedMessage(platform),
+                    error: permissionDeniedMessage(platform, home, env),
                     stdout, stderr, exitCode,
                 });
                 return;
             }
             if (exitCode !== 0) {
+                onPhase('failed');
                 resolve({
                     success: false,
                     error: `Install failed (npm exit ${exitCode}). ` +
@@ -153,6 +182,7 @@ async function executeInstall(opts = {}) {
             }
             // Success — parse installed version from npm output. Pattern:
             // "+ aiden-runtime@4.1.3" or "added 1 package ... aiden-runtime@4.1.3"
+            onPhase('installed');
             const installedVersion = parseInstalledVersion(stdout) ?? parseInstalledVersion(stderr) ?? undefined;
             resolve({
                 success: true,
@@ -190,38 +220,14 @@ function isPermissionDenied(stdout, stderr, exitCode) {
     return false;
 }
 /**
- * Build the platform-specific copy-paste remediation. Provides three
- * distinct paths — system-wide-with-elevation (Windows admin),
- * sudo (macOS/Linux), or user-local-prefix (cross-platform) — so the
- * user has options without us trying to self-escalate to UAC/sudo
- * from inside the running REPL.
+ * v4.9.1 — Build the platform-specific copy-paste remediation. Delegates
+ * to `platformInstructions.ts` for the heavy lifting so the same builder
+ * powers both EPERM remediation + stale-prefix warnings + the future
+ * `aiden update --setup-user-prefix` helper.
  */
-function permissionDeniedMessage(platform) {
-    const userLocal = 'Or use a user-local npm prefix to avoid privileges entirely:\n' +
-        '              npm config set prefix ~/.npm-global\n' +
-        '              export PATH=~/.npm-global/bin:$PATH    # add to your shell profile\n' +
-        '              npm install -g aiden-runtime@latest';
-    if (platform === 'win32') {
-        return [
-            'Install failed: permission denied (npm needs Administrator for global install).',
-            '',
-            'To update manually:',
-            '  Windows:  Open PowerShell as Administrator, then:',
-            '              npm install -g aiden-runtime@latest',
-            '',
-            userLocal,
-        ].join('\n');
-    }
-    // darwin / linux / others — sudo path.
-    return [
-        'Install failed: permission denied (npm needs sudo for global install).',
-        '',
-        'To update manually:',
-        '  macOS / Linux:',
-        '              sudo npm install -g aiden-runtime@latest',
-        '',
-        userLocal,
-    ].join('\n');
+function permissionDeniedMessage(platform, home, env) {
+    const instr = (0, platformInstructions_1.permissionDeniedInstructions)({ platform, home, env });
+    return [instr.headline, '', ...instr.steps].join('\n');
 }
 /**
  * Find the installed version in npm output. Two common patterns:

package/dist/core/v4/update/platformInstructions.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/update/platformInstructions.ts — v4.9.1.
+ *
+ * Per-platform copy-paste remediation text for:
+ *   - EPERM / EACCES during global npm install
+ *   - Stale / risky npm prefix detection
+ *
+ * Branches purely on `process.platform` (and `$SHELL` for unix shell-
+ * rc-file recommendations). Shell syntax MUST be correct per-platform:
+ * PowerShell on Windows, bash/zsh on Unix. Cross-contamination is a
+ * regression (the v4.9.0 bug we're hot-fixing).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectShell = detectShell;
+exports.permissionDeniedInstructions = permissionDeniedInstructions;
+exports.detectStalePrefix = detectStalePrefix;
+/**
+ * Detect the user's interactive shell on POSIX. Returns the basename
+ * (`zsh` / `bash` / `sh`) or null when undetectable. Pure — env is
+ * injected so tests pin a value.
+ */
+function detectShell(env = process.env) {
+    const sh = env.SHELL;
+    if (!sh)
+        return null;
+    const last = sh.split(/[\\/]/).pop() || '';
+    return last.toLowerCase() || null;
+}
+/** rc-file path the user should edit, per shell. POSIX only. */
+function rcFileFor(shell, home) {
+    if (shell === 'zsh')
+        return `${home}/.zshrc`;
+    if (shell === 'bash')
+        return `${home}/.bashrc   (or ~/.bash_profile on macOS)`;
+    return `${home}/.profile`;
+}
+/**
+ * Build the EPERM/EACCES remediation. Two options per platform —
+ * elevation (one-time) and user-local prefix (permanent, no privs).
+ */
+function permissionDeniedInstructions(opts) {
+    const env = opts.env ?? process.env;
+    if (opts.platform === 'win32') {
+        return {
+            headline: 'Install failed: permission denied. npm needs Administrator for a global install on Windows.',
+            shell: 'powershell',
+            steps: [
+                'Option 1 — Run once with elevated privileges:',
+                '  • Open PowerShell as Administrator (right-click → "Run as administrator")',
+                '  • npm install -g aiden-runtime@latest',
+                '',
+                'Option 2 — Permanent: switch npm to a user-local prefix (no admin needed ever again):',
+                '  • npm config set prefix "$env:USERPROFILE\\AppData\\Roaming\\npm"',
+                '  • [Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\\AppData\\Roaming\\npm;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")',
+                '  • Close + reopen PowerShell, then:  npm install -g aiden-runtime@latest',
+            ],
+        };
+    }
+    // POSIX: darwin / linux / *bsd / etc.
+    const shell = detectShell(env);
+    const rcFile = rcFileFor(shell, opts.home);
+    return {
+        headline: `Install failed: permission denied. npm needs sudo for a global install on ${opts.platform}.`,
+        shell: shell ?? undefined,
+        rcFile,
+        steps: [
+            'Option 1 — Run once with elevated privileges:',
+            '  • sudo npm install -g aiden-runtime@latest',
+            '',
+            'Option 2 — Permanent: switch npm to a user-local prefix (no sudo needed ever again):',
+            `  • npm config set prefix "${opts.home}/.npm-global"`,
+            `  • echo 'export PATH="${opts.home}/.npm-global/bin:$PATH"' >> ${rcFile}`,
+            `  • source ${rcFile}`,
+            '  • npm install -g aiden-runtime@latest',
+        ],
+    };
+}
+/**
+ * Stale / risky prefix detection. Returns a warning when the npm
+ * `prefix` config points at a location that needs elevation OR is
+ * known to cause permission churn. `null` when the prefix is safe.
+ *
+ * `writable` is the result of a `fs.access` check the caller does
+ * before invoking us (we don't want to do filesystem I/O in a pure
+ * builder — caller controls the side effect).
+ */
+function detectStalePrefix(opts) {
+    const env = opts.env ?? process.env;
+    const p = opts.prefix;
+    // Windows risk: Program Files.
+    if (opts.platform === 'win32') {
+        if (/^[a-zA-Z]:\\Program Files/i.test(p)) {
+            return {
+                warning: `npm prefix is "${p}" — global installs here require Administrator every time.`,
+                switchSteps: [
+                    'Switch to a user-local prefix to avoid the prompt forever:',
+                    '  • npm config set prefix "$env:USERPROFILE\\AppData\\Roaming\\npm"',
+                    '  • [Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\\AppData\\Roaming\\npm;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")',
+                    '  • Close + reopen PowerShell.',
+                ],
+            };
+        }
+        return null;
+    }
+    // POSIX risk: /usr or /usr/local without write access.
+    const risky = p === '/usr' || p === '/usr/local' || p.startsWith('/usr/');
+    if (risky && !opts.writable) {
+        const shell = detectShell(env);
+        const rcFile = rcFileFor(shell, opts.home);
+        return {
+            warning: `npm prefix is "${p}" — global installs here require sudo every time.`,
+            switchSteps: [
+                'Switch to a user-local prefix to avoid sudo forever:',
+                `  • npm config set prefix "${opts.home}/.npm-global"`,
+                `  • echo 'export PATH="${opts.home}/.npm-global/bin:$PATH"' >> ${rcFile}`,
+                `  • source ${rcFile}`,
+            ],
+        };
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiden-runtime",
-  "version": "4.9.0",
+  "version": "4.9.1",
   "publishConfig": {
     "access": "public"
   },