aiden-runtime 4.8.1 → 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.6.1](https://img.shields.io/badge/Latest-v4.6.1-4ADE80?style=flat-square)
+![v4.9.1](https://img.shields.io/badge/Latest-v4.9.1-4ADE80?style=flat-square)
 
 </div>
 
@@ -134,6 +134,46 @@ Drop a file in `~/Documents/inbox/anything.txt` and Aiden acts on it. The agent
 
 <br>
 
+## What's new in v4.9.0
+
+Aiden v4.9.0 ships three new feature families:
+
+- **Memory** — three-namespace persistent memory (memory/user/project) with CLI + auto-review
+- **Hooks** — secure subprocess hook system (observe/decide/transform) with full audit trail
+- **Strategic substrate** — UUIDv7 IDs, W3C trace propagation, durable runs, idempotency, crash recovery
+
+Plus theme system, MCP integration (Claude Desktop / Cursor / VS Code), and substantial UI polish.
+
+See [CHANGELOG.md](./CHANGELOG.md) for details.
+
+<br>
+
+## What's new in v4.8
+
+**Aiden's UI got an identity, and pasting actually works now.**
+
+### v4.8.1 — Paste handling + visual polish
+
+- **Robust paste handling.** Stateful parser across stdin chunk boundaries, 800ms watchdog for missing paste-end markers, degraded marker form normalisation, universal CRLF/CR → LF, and timing-based accumulation that catches line-by-line paste delivery. Works across Windows ConPTY, SSH without `-t`, tmux/screen passthrough, and VS Code's integrated terminal. Typed prefix is preserved when paste arrives mid-input.
+- **Markdown tables render as proper grids.** Proportional column-width distribution with header-floor minimums so short labels never wrap mid-word. Model nudged via prompt to prefer sectioned lists for very wide comparisons.
+- **Version reporting reads runtime `package.json`.** Boot card and `/version` no longer report stale numbers after `/update install`.
+- **`/update install` cleanups.** Dropped the Node 20+ deprecation warning. Install progress shown via sliding-shimmer indicator. Install-method detection broadened to Windows user-mode globals.
+- **Loading indicator + spacing.** Indicator aligned at col 2 matching other surfaces; conditional erase preserves clean 1-blank rhythm between turns.
+- **Status bar timer glyph (`⌛`).** Visible at all terminal widths (mid + compact tiers previously dropped it).
+- **Single approval panel** per `file_write` (no duplicate event-row + panel stack).
+
+### v4.8.0 — Events backbone + visual identity
+
+- **Watch the agent work.** Seven `ui_*` events (`ui_task_update`, `ui_task_done`, `ui_command_result`, `ui_test_result`, `ui_approval_request`, `ui_toast`, `ui_artifact_created`) let the model emit structured progress signals instead of writing them as prose. The REPL paints them as inline rows separate from the reply text. System prompt nudges the model to fire events during multi-step work.
+- **Aiden-native visual chrome.** Orange `│` panel bars with asymmetric top-divider chrome (no closing corners). Token-sourced design system (`cli/v4/design/tokens.ts`) — palette, glyphs, spacing in one place.
+- **Packed status bar.** Cyan model name · amber token ratio · semantic-tiered context bar (`●●●●●●○○○○`) · purple turn counter · teal `⌛` per-turn timer · state dot. Progressive disclosure on narrower terminals.
+- **Sliding-block loading indicator.** 4-cell `█` segment slides L→R on a muted `─` track at 250ms/cell.
+- **Onboarding refresh.** 24-bit ANSI AIDEN banner, capability-bullet disclaimer, 10-cell progress bar in the loading sequence, rounded heavy-frame "Built solo" card.
+- **Markdown polish.** Code blocks get a top-divider with brand-orange language label. Bullet lists use `●`/`○`; task lists use `✔️`/`○`.
+- **ChatGPT Plus + gpt-5 routing fix.** Auxiliary cheap-LLM calls (`risk_assess`, `compression`, `session_summary`, `skill_describe`) route through Groq + `llama-3.1-8b-instant` by default, falling back to the parent provider only when Groq isn't configured. Fixes the v4.6.x bug where every auxiliary call returned 400 from the Codex backend.
+
+<br>
+
 ## What's new in v4.6
 
 **Aiden now spawns workers and learns from itself.**
@@ -296,6 +336,47 @@ export AIDEN_DEFAULT_PROVIDER=groq
 export AIDEN_DEFAULT_MODEL=llama-3.3-70b-versatile
 ```
 
+### Recommended models
+
+| Use case | Best models |
+|---|---|
+| **General-purpose / quality** | Claude Sonnet 4.6 / Opus, GPT-5, Gemini 2.5 Pro |
+| **Speed + free tier** | Groq Llama 3.3 70B, Cerebras Llama 3.3 70B |
+| **Fully local** | Ollama with Qwen 2.5 32B, Llama 3.3 70B, or DeepSeek R1 |
+| **Open weights via subscription** | Nous Portal (Hermes-3-405B) |
+| **Long context** | Gemini 2.5 Pro (2M tokens) |
+
+> 💡 **Quality scales with model capability.** Aiden's output quality depends heavily on the model you pick. For real work, prefer the highest-capability model your budget allows — Claude Sonnet 4.6, GPT-5, or Gemini 2.5 Pro. Smaller models work for simple tasks but agentic loops benefit from stronger reasoning.
+
+> 💡 **ChatGPT Plus / Claude Pro subscribers**: use the OAuth flow instead of an API key. Pick `chatgpt-plus` or `claude-pro` as your provider during `/model` setup, then sign in via browser. No separate API costs — uses your existing subscription's model allowances.
+
+<br>
+
+## Skills
+
+Aiden ships with 74 bundled skills and supports installing more from the community registry.
+
+### What are skills?
+
+Skills are composable workflows. Each skill has a `SKILL.md` prompt, optional helper scripts, and declared tool requirements. Examples: GitHub PR/issue automation, NSE/Upstox/Zerodha trading flows, Censys/Shodan lookups, Windows Defender management.
+
+### Managing skills
+
+| Action | Command |
+|---|---|
+| List installed skills | `/skills` |
+| Browse the community registry | Visit [skills.taracod.com](https://skills.taracod.com) |
+| Install a skill from registry | `/skills install <name>` |
+| Remove a skill | `/skills remove <name>` |
+| Reload skills (after edits) | `/skills reload` |
+
+### Contributing skills
+
+Skills live in [`skills/`](skills/) under Apache-2.0. PRs welcome. Each skill needs:
+- A `SKILL.md` describing what it does and when to use it
+- Optional `tools.json` declaring required tools
+- Optional helper scripts in `lib/`
+
 <br>
 
 ## Configuration
@@ -485,6 +566,12 @@ Aiden can touch your files, run shell commands, and access the web. It's autonom
 
 **Built solo. Started as a hobby project. Still rough in spots. Getting better every week.**
 
+### Welcome
+
+- **Contributors** — bug reports, skill submissions, provider adapters, and documentation PRs are all welcome. See [Contributing](#contributing) above for the workflow.
+- **Sponsors / investors** — Aiden is built by one person funding it from client work. If you'd like to help Aiden grow faster, reach out at [contact@taracod.com](mailto:contact@taracod.com) or sponsor via [Razorpay](https://razorpay.me/@whitelotus9625).
+- **Beta testers** — try it on your workflow, file issues, share what works and what doesn't. Honest feedback shapes the roadmap.
+
 ---
 
 <div align="center">

package/dist/cli/v4/aidenCLI.js

@@ -472,10 +472,37 @@ async function main(argv, opts = {}) {
         });
         process.exit(code);
     });
+    // v4.9.0 Slice 9 — memory CLI surface.
+    program
+        .command('memory [action] [args...]')
+        .description('Manage MEMORY.md + USER.md + project memory. Actions: list (default), show, add, remove, edit, backup, restore, diff, namespaces, pending, approve, reject, review.')
+        .allowUnknownOption()
+        .action(async (action, posArgs) => {
+        const { runMemorySubcommand } = await Promise.resolve().then(() => __importStar(require('./commands/memory')));
+        const code = await runMemorySubcommand(action ?? 'list', posArgs ?? [], {
+            writeOut: opts.writeOut,
+        });
+        process.exit(code);
+    });
+    // v4.9.0 Slice 12b — hooks CLI surface.
+    program
+        .command('hooks [action] [args...]')
+        .description('Manage hook subsystem. Actions: list (default), show, trust, revoke, rescan, test, doctor, audit.')
+        .allowUnknownOption()
+        .action(async (action, posArgs) => {
+        const { runHooksSubcommand } = await Promise.resolve().then(() => __importStar(require('./commands/hooks')));
+        const code = await runHooksSubcommand(action ?? 'list', posArgs ?? [], {
+            writeOut: opts.writeOut,
+        });
+        process.exit(code);
+    });
     // v4.5 Phase 4b — daemon supervisor commands.
     program
         .command('daemon <action> [args...]')
-        .description('Manage the v4.5 daemon. Actions: install, uninstall, start, stop, restart, status, logs.')
+        .description('Manage the Aiden daemon. Actions: install, uninstall, start, stop, restart, status, logs, doctor.')
+        // v4.9.0 Slice 8 — `aiden daemon doctor --json` / `--fix`. Allow
+        // unknown flags so the subcommand can parse them via posArgs.
+        .allowUnknownOption()
         .action(async (action, posArgs) => {
         const { runDaemonSubcommand } = await Promise.resolve().then(() => __importStar(require('./commands/daemon')));
         const code = await runDaemonSubcommand(action, posArgs ?? [], {
@@ -518,9 +545,11 @@ async function main(argv, opts = {}) {
         process.exit(code);
     });
     program
-        .command('mcp <action>')
-        .description('MCP server mode (Phase v4.1-mcp). Actions: serve, status, tools.')
-        .action(async (action) => {
+        .command('mcp <action> [target] [extraArgs...]')
+        .description('MCP server mode + client config. Actions: serve | status | tools | init <client> | doctor <client> | repair <client> | uninstall <client>. ' +
+        'Clients: claude (Claude Desktop), cursor, vscode.')
+        .allowUnknownOption()
+        .action(async (action, target, extraArgs = []) => {
         if (opts.runMcpHook) {
             await opts.runMcpHook(action);
             return;
@@ -531,13 +560,15 @@ async function main(argv, opts = {}) {
         const code = await runMcpSubcommand(action, {
             writeOut: opts.writeOut,
             writeErr: (t) => process.stderr.write(t),
+            args: extraArgs,
+            target,
         });
         if (code !== 0)
             process.exit(code);
     });
     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) => {
@@ -580,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

@@ -98,6 +98,8 @@ const node_path_1 = __importDefault(require("node:path"));
 const bracketedPaste_1 = require("./bracketedPaste");
 const pasteCompression_1 = require("./pasteCompression");
 const pasteIntercept_1 = require("./pasteIntercept");
+// v4.9.0 Slice 1a — theme hot-reload watcher.
+const themeWatcher_1 = require("../../core/v4/theme/themeWatcher");
 const shellInterpolation_1 = require("./shellInterpolation");
 const resizeGuard_1 = require("./resizeGuard");
 /**
@@ -425,6 +427,16 @@ class ChatSession {
         const restorePasteInterceptor = this.opts.promptApi
             ? () => { }
             : (0, pasteIntercept_1.installPasteInterceptor)(process.stdin);
+        // v4.9.0 Slice 1a — start the theme hot-reload watcher. Honours
+        // `~/.aiden/theme.yaml` if it exists; otherwise no-op until the
+        // user creates one. Disposed in the `finally` block alongside
+        // the paste interceptor.
+        if (this.opts.paths && !this.opts.promptApi) {
+            try {
+                (0, themeWatcher_1.startThemeWatcher)(require('node:path').join(this.opts.paths.root, 'theme.yaml'));
+            }
+            catch { /* watcher start failure must not crash REPL */ }
+        }
         // Tier-3-essentials: hard-clear the screen on terminal resize so
         // dropdown re-renders + previous prompt frames don't ghost into
         // the new viewport. No-op on non-TTY / MCP serve mode.
@@ -529,6 +541,12 @@ class ChatSession {
                     // commands; the footer belongs to agent turns only.
                     continue;
                 }
+                // v4.9.0 pre-ship UI: BOTTOM rule of the prompt zone. The TOP
+                // rule fires at `printTurnSeparator()` above (iter > 1). This
+                // bottom rule fires only when actual content goes to the LLM —
+                // slash commands + empty input + /quit all `continue` above and
+                // never reach this line, matching the task's edge-case spec.
+                this.opts.display.write(`  ${this.opts.display.rule()}\n`);
                 await this.runAgentTurn(input);
             }
         }
@@ -542,6 +560,10 @@ class ChatSession {
             if (pasteEnabled)
                 (0, bracketedPaste_1.disableBracketedPaste)(stdout);
             restorePasteInterceptor();
+            try {
+                (0, themeWatcher_1.stopThemeWatcher)();
+            }
+            catch { /* defensive */ }
             restoreResizeGuard();
         }
     }
@@ -1362,8 +1384,10 @@ class ChatSession {
                 _deferredTip = null;
             }
             // Tier-3.1a: dim full-width rule between the agent reply and the
-            // post-turn status footer.
-            this.opts.display.write(`  ${this.opts.display.rule()}\n`);
+            // post-turn status footer. v4.9.0 pre-ship UI: prepend a blank
+            // line so the response zone gets breathing room above the rule
+            // — matches the `\n\n` blank already below `▎ Aiden` header.
+            this.opts.display.write(`\n  ${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
@@ -1632,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 */ }
@@ -1648,15 +1676,16 @@ class ChatSession {
             }
         }
         catch { /* never let a missing marker crash boot */ }
-        // Bottom prompt hint — final line of the boot card.
-        // v4.8.0 Slice 10d — full-width muted `─` divider between the
-        // boot card (parchment / capability card / two-column block) and
-        // the input hint prevents the boot chrome from merging visually
-        // with the active prompt. Pattern: blank · rule · blank · hint.
-        display.write('\n');
-        display.write(`  ${display.rule()}\n`);
+        // v4.9.0 pre-ship UI: hint moved BEFORE the closing rule so the
+        // rule sits adjacent to the active prompt (it becomes the visual
+        // top of the prompt zone). New order: blank · hint · blank · rule.
+        // Banner content ends with the hint; the rule below it brackets
+        // the user-input zone together with the new bottom-rule emission
+        // in the REPL loop.
         display.write('\n');
         display.write(display.bottomPromptHint() + '\n');
+        display.write('\n');
+        display.write(`  ${display.rule()}\n`);
     }
     /**
      * v4.5 update system — orchestrates the boot prompt. Lazy-imports
@@ -1688,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

@@ -27,6 +27,39 @@
  * variance + admin requirements make the install footprint too risky
  * for an auto-installer. The docs cover pm2 + foreground patterns.
  */
+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 };
 };
@@ -59,10 +92,27 @@ async function runDaemonSubcommand(action, args, opts = {}) {
         case 'restart': return runRestart({ out, err });
         case 'status': return runStatus({ out, err });
         case 'logs': return runLogs({ out, err });
-        default:
+        case 'doctor': {
+            // v4.9.0 Slice 8 — substrate health diagnostic. Read-only by
+            // default; `--fix` runs safe sweeps; `--json` outputs machine-
+            // parseable shape.
+            const { runDaemonDoctor } = await Promise.resolve().then(() => __importStar(require('./daemonDoctor')));
+            return runDaemonDoctor({
+                json: args.includes('--json'),
+                fix: args.includes('--fix'),
+                writeOut: out,
+                writeErr: err,
+            });
+        }
+        default: {
             err(`Unknown daemon action: ${action}\n`);
-            err('Actions: install, uninstall, start, stop, restart, status, logs\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';
@@ -280,7 +330,7 @@ async function runInstallMacOS(io) {
 async function runInstallWindows(io) {
     io.out((0, daemon_1.windowsServiceGuidance)());
     io.out('\n');
-    io.out('See docs/v4.5/daemon-windows.md for the full walkthrough.\n');
+    io.out('See docs/daemon-windows.md for the full walkthrough.\n');
     return 0;
 }
 // ── uninstall ───────────────────────────────────────────────────────────────

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

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/commands/daemonDoctor.ts — v4.9.0 Slice 8.
+ *
+ * `aiden daemon doctor` — read-only diagnostic of substrate health.
+ * `aiden daemon doctor --json` — machine-parseable shape.
+ * `aiden daemon doctor --fix`  — runs sweeps for safely-fixable issues.
+ *
+ * Checks (in display order):
+ *   1. daemon_id file exists + parses
+ *   2. Schema at LATEST_SCHEMA_VERSION
+ *   3. Recent incarnation row present + heartbeat fresh
+ *   4. Recent crashes (24h) — warn if more than 3
+ *   5. Stuck attempts present (sweep candidates)
+ *   6. Orphan spans present (sweep candidates)
+ *   7. Idempotency table bounded (warn if > 10000 rows)
+ *   8. Pending-but-stale trigger events (claim lease expired)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectDoctorChecks = collectDoctorChecks;
+exports.runDaemonDoctor = runDaemonDoctor;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const paths_1 = require("../../../core/v4/paths");
+const identity_1 = require("../../../core/v4/identity");
+const migrations_1 = require("../../../core/v4/daemon/db/migrations");
+const stuckAttemptWatchdog_1 = require("../../../core/v4/daemon/runs/stuckAttemptWatchdog");
+const TWENTY_FOUR_HOURS_MS = 24 * 60 * 60 * 1000;
+/** Compute overall status: error if any error, warn if any warn, else ok. */
+function overall(results) {
+    if (results.some((r) => r.status === 'error'))
+        return 'error';
+    if (results.some((r) => r.status === 'warn'))
+        return 'warn';
+    return 'ok';
+}
+function tableExists(db, name) {
+    const row = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name = ?`).get(name);
+    return !!row?.name;
+}
+/**
+ * Run all checks against the daemon DB at `<root>/daemon/daemon.db`.
+ * Pure-data path; no terminal I/O. Renders happen in `runDaemonDoctor`.
+ */
+function collectDoctorChecks(rootDir) {
+    const checks = [];
+    // 1. daemon_id file
+    const idPath = (0, identity_1.daemonIdFilePath)(rootDir);
+    if (!node_fs_1.default.existsSync(idPath)) {
+        checks.push({ name: 'daemon_id file', status: 'error',
+            detail: `missing: ${idPath} (daemon never booted in this root)`,
+            fixable: false });
+    }
+    else {
+        const content = node_fs_1.default.readFileSync(idPath, 'utf8').trim();
+        checks.push({ name: 'daemon_id file', status: content.startsWith('dmn_') ? 'ok' : 'error',
+            detail: `${idPath} → ${content.slice(0, 40)}...`,
+            fixable: false });
+    }
+    // Open DB. If unavailable, remaining checks short-circuit.
+    const dbPath = node_path_1.default.join(rootDir, 'daemon', 'daemon.db');
+    if (!node_fs_1.default.existsSync(dbPath)) {
+        checks.push({ name: 'daemon DB', status: 'error',
+            detail: `missing: ${dbPath}`, fixable: false });
+        return checks;
+    }
+    const db = new better_sqlite3_1.default(dbPath, { readonly: false });
+    db.pragma('foreign_keys = ON');
+    try {
+        // 2. Schema version
+        const verRow = db.prepare(`SELECT version FROM schema_version WHERE id = 1`)
+            .get();
+        const ver = verRow?.version ?? 0;
+        checks.push({ name: 'schema version', status: ver === migrations_1.LATEST_SCHEMA_VERSION ? 'ok' : 'warn',
+            detail: `current=${ver} latest=${migrations_1.LATEST_SCHEMA_VERSION}`,
+            fixable: false });
+        // 3. Recent incarnation
+        const inc = db.prepare(`SELECT incarnation_id, started_at, ended_at, exit_reason FROM daemon_incarnations
+        ORDER BY started_at DESC LIMIT 1`).get();
+        if (!inc) {
+            checks.push({ name: 'recent incarnation', status: 'warn',
+                detail: 'no daemon_incarnations rows (daemon never started in this root)',
+                fixable: false });
+        }
+        else {
+            const closedDetail = inc.ended_at
+                ? `last incarnation ${inc.incarnation_id.slice(0, 20)}... ended_at=${inc.ended_at} reason=${inc.exit_reason}`
+                : `latest incarnation ${inc.incarnation_id.slice(0, 20)}... still open (started_at=${inc.started_at})`;
+            checks.push({ name: 'recent incarnation', status: 'ok', detail: closedDetail, fixable: false });
+        }
+        // 4. Recent crashes (24h)
+        const sinceIso = new Date(Date.now() - TWENTY_FOUR_HOURS_MS).toISOString();
+        const crashes = db.prepare(`SELECT COUNT(*) AS c FROM daemon_incarnations
+        WHERE exit_reason = 'crash' AND started_at > ?`).get(sinceIso);
+        checks.push({ name: 'recent crashes (24h)',
+            status: crashes.c === 0 ? 'ok' : crashes.c > 3 ? 'warn' : 'ok',
+            detail: `${crashes.c} crash(es) in last 24h`,
+            fixable: false });
+        // 5. Stuck attempts (require Slice 5 + 8 tables)
+        let stuckAttempts = 0;
+        if (tableExists(db, 'run_attempts')) {
+            const currentInc = inc?.incarnation_id ?? '';
+            const cutoffIso = new Date(Date.now() - 30 * 60 * 1000).toISOString();
+            stuckAttempts = db.prepare(`SELECT COUNT(*) AS c FROM run_attempts
+          WHERE status='running' AND incarnation_id != ? AND started_at < ?`).get(currentInc, cutoffIso).c;
+        }
+        checks.push({ name: 'stuck attempts',
+            status: stuckAttempts === 0 ? 'ok' : 'warn',
+            detail: `${stuckAttempts} stuck attempt(s) eligible for sweep`,
+            fixable: stuckAttempts > 0,
+            fix: stuckAttempts > 0 && inc
+                ? () => { (0, stuckAttemptWatchdog_1.sweepStuckAttempts)(db, { currentIncarnationId: inc.incarnation_id }); }
+                : undefined });
+        // 6. Orphan spans (open + non-current incarnation)
+        let orphanSpans = 0;
+        if (tableExists(db, 'spans')) {
+            const currentInc = inc?.incarnation_id ?? '';
+            orphanSpans = db.prepare(`SELECT COUNT(*) AS c FROM spans
+          WHERE status IS NULL AND ended_at IS NULL AND incarnation_id != ?`).get(currentInc).c;
+        }
+        checks.push({ name: 'orphan spans',
+            status: orphanSpans === 0 ? 'ok' : 'warn',
+            detail: `${orphanSpans} orphan span(s) eligible for sweep`,
+            fixable: orphanSpans > 0,
+            fix: orphanSpans > 0 && inc
+                ? () => { (0, stuckAttemptWatchdog_1.sweepStuckAttempts)(db, { currentIncarnationId: inc.incarnation_id }); }
+                : undefined });
+        // 7. Idempotency tables size
+        let idemRows = 0;
+        if (tableExists(db, 'run_idempotency_keys')) {
+            idemRows = db.prepare(`SELECT COUNT(*) AS c FROM run_idempotency_keys`).get().c;
+        }
+        checks.push({ name: 'run_idempotency_keys size',
+            status: idemRows < 10000 ? 'ok' : 'warn',
+            detail: `${idemRows} row(s)` + (idemRows >= 10000 ? ' — consider sweepExpired' : ''),
+            fixable: false });
+        // 8. Stale-claimed trigger events
+        let staleClaimed = 0;
+        if (tableExists(db, 'trigger_events')) {
+            staleClaimed = db.prepare(`SELECT COUNT(*) AS c FROM trigger_events
+          WHERE status='claimed' AND claim_expires_at IS NOT NULL AND claim_expires_at < ?`).get(Date.now()).c;
+        }
+        checks.push({ name: 'stale-claimed trigger events',
+            status: staleClaimed === 0 ? 'ok' : 'warn',
+            detail: `${staleClaimed} trigger_events past claim_expires_at`,
+            fixable: false });
+    }
+    finally {
+        try {
+            db.close();
+        }
+        catch { /* noop */ }
+    }
+    return checks;
+}
+/**
+ * CLI entry. Returns the desired process exit code (0=ok, 1=error,
+ * 0 for warn-only since warnings shouldn't break scripts).
+ */
+function runDaemonDoctor(opts = {}) {
+    const root = opts.rootDir ?? (0, paths_1.resolveAidenRoot)();
+    const out = opts.writeOut ?? ((s) => { process.stdout.write(s); });
+    const err = opts.writeErr ?? ((s) => { process.stderr.write(s); });
+    const checks = collectDoctorChecks(root);
+    const fixed = [];
+    if (opts.fix) {
+        for (const c of checks) {
+            if (c.fixable && c.fix) {
+                try {
+                    c.fix();
+                    fixed.push(c.name);
+                }
+                catch (e) {
+                    err(`[doctor] fix '${c.name}' failed: ${e instanceof Error ? e.message : String(e)}\n`);
+                }
+            }
+        }
+    }
+    const report = {
+        overall: overall(checks),
+        checks: checks.map((c) => ({ name: c.name, status: c.status, detail: c.detail, fixable: c.fixable })),
+        ...(opts.fix ? { fixed } : {}),
+    };
+    if (opts.json) {
+        out(JSON.stringify(report, null, 2) + '\n');
+    }
+    else {
+        const sym = (s) => s === 'ok' ? '[ok]  ' : s === 'warn' ? '[warn]' : '[err] ';
+        out(`aiden daemon doctor — ${report.overall.toUpperCase()}\n`);
+        out(`root: ${root}\n\n`);
+        for (const c of report.checks) {
+            out(`  ${sym(c.status)} ${c.name}: ${c.detail}\n`);
+        }
+        if (opts.fix && fixed.length > 0) {
+            out(`\nfixed: ${fixed.join(', ')}\n`);
+        }
+        else if (opts.fix) {
+            out(`\nno fixable issues found\n`);
+        }
+    }
+    return report.overall === 'error' ? 1 : 0;
+}