wotann 0.5.0 → 0.5.39

package/dist/index.js

@@ -13,6 +13,8 @@ import { execFileNoThrow } from "./utils/execFileNoThrow.js";
 import { setupProxyFromEnv } from "./utils/proxy-setup.js";
 import { resolveWotannHome, resolveWotannHomeSubdir } from "./utils/wotann-home.js";
 import { installProcessHandlers } from "./utils/process-handlers.js";
+import { resolveDaemonSocketPath } from "./daemon/transport/socket-path.js";
+import { buildShellCommand } from "./utils/platform.js";
 // V9 Wave 6-RR (SB-9): install uncaughtException + unhandledRejection
 // handlers BEFORE any subsystem boots. Without this, a single async
 // rejection silently exits the CLI under Node ≥15 default behavior with
@@ -25,6 +27,12 @@ installProcessHandlers({ tag: "wotann-cli" });
 // No-op when no proxy env var is set; never crashes startup on bad proxy URLs.
 setupProxyFromEnv();
 const VERSION = (() => {
+    // Prefer build-time injection (SEA, dev builds, anything bundled).
+    if (typeof __WOTANN_VERSION__ === "string" && __WOTANN_VERSION__.length > 0) {
+        return __WOTANN_VERSION__;
+    }
+    // Runtime fallback — node_modules install where `import.meta.url`
+    // resolves correctly relative to package.json.
     try {
         const here = dirname(fileURLToPath(import.meta.url));
         const pkgPath = resolve(here, "..", "package.json");
@@ -154,19 +162,19 @@ program
             process.exit(1);
         }
     }
-    // D12: When the daemon is running, launch the thin-client TUI instead of
-    // standing up a fresh 408-module runtime in-process. Cold start drops
-    // from ~2-5 s to ~150 ms. `--no-thin` (or WOTANN_THIN=0) opts out.
-    const optThin = process.env["WOTANN_THIN"];
-    const forceFullRuntime = optThin === "0" || process.argv.includes("--no-thin");
-    if (!forceFullRuntime && !options.pipe) {
-        const { launchOrFallback, detectDaemon } = await import("./cli/thin-client.js");
-        if (await detectDaemon()) {
-            const launched = await launchOrFallback();
-            if (launched)
-                return; // thin TUI rendered and exited
-            // else fall through to full runtime
-        }
+    // Full runtime is the default. Thin-client TUI is opt-in via
+    // `--thin` or `WOTANN_THIN=1` and provides a much faster cold start
+    // (~150 ms vs ~2-5 s) by talking to a running daemon over IPC
+    // instead of standing up a fresh 408-module runtime in-process.
+    // If thin is requested but no daemon socket exists, launchOrFallback
+    // returns false and we fall through to the full runtime silently.
+    const requestedThin = process.env["WOTANN_THIN"] === "1" || process.argv.includes("--thin");
+    if (requestedThin && !options.pipe) {
+        const { launchOrFallback } = await import("./cli/thin-client.js");
+        const launched = await launchOrFallback();
+        if (launched)
+            return; // thin TUI rendered and exited
+        // else fall through to full runtime
     }
     const [{ render }, ReactModule, { WotannApp }] = await Promise.all([
         import("ink"),
@@ -226,10 +234,23 @@ program
     .description("Generate iOS pairing details from the running daemon")
     .action(async () => {
     const { KairosIPCClient } = await import("./daemon/kairos-ipc.js");
-    const ipcClient = new KairosIPCClient();
-    const daemonAvailable = await ipcClient.connect();
+    let ipcClient = new KairosIPCClient(undefined, { requestTimeoutMs: 5_000 });
+    let daemonAvailable = await ipcClient.connect();
     if (!daemonAvailable) {
-        console.error(chalk.red.bold("\n  KAIROS daemon is not running.\n"));
+        ipcClient.disconnect();
+        const repaired = await ensureDaemonIpcForCommand({
+            label: "KAIROS daemon",
+            announce: "KAIROS daemon IPC is unavailable; starting or repairing the daemon...",
+        });
+        if (repaired) {
+            ipcClient = new KairosIPCClient(undefined, { requestTimeoutMs: 5_000 });
+            daemonAvailable = await ipcClient.connect();
+        }
+    }
+    if (!daemonAvailable) {
+        console.error(chalk.red.bold("\n  KAIROS daemon IPC is not reachable.\n"));
+        console.error(chalk.dim(await formatDaemonHealthDiagnostic("  ")));
+        console.error();
         console.error(chalk.yellow("  To fix, do ONE of these:\n"));
         console.error(chalk.dim("    1. Open the WOTANN desktop app (auto-starts daemon)"));
         console.error(chalk.dim("    2. Run: ") + chalk.white("wotann daemon start"));
@@ -266,6 +287,25 @@ program
         console.log();
         console.log(chalk.dim(`  Host:     ${pairing.host ?? "unknown"}`));
         console.log(chalk.dim(`  Port:     ${pairing.port ?? 3849}`));
+        const remoteEndpoints = pairing.remoteEndpoints ?? [];
+        if (remoteEndpoints.length > 0) {
+            console.log(chalk.dim("  Remote:"));
+            for (const endpoint of remoteEndpoints) {
+                const scheme = endpoint.scheme ?? "ws";
+                const host = endpoint.host ?? "unknown";
+                const port = endpoint.port ?? (scheme === "wss" ? 443 : 3849);
+                const label = endpoint.label ?? "Remote";
+                console.log(chalk.dim(`    ${label}: ${scheme}://${host}:${port}`));
+            }
+        }
+        else if (pairing.remoteAccess) {
+            console.log(chalk.dim(`  Remote:   ${pairing.remoteAccess.status ?? "missing-endpoint"}`));
+            console.log(chalk.dim(`            ${pairing.remoteAccess.message ?? "Same network only."}`));
+            const recommended = pairing.remoteAccess.setupOptions?.find((option) => option.id === "tailscale");
+            if (recommended) {
+                console.log(chalk.dim(`            ${recommended.label}: ${recommended.detail}`));
+            }
+        }
         console.log(chalk.dim(`  PIN:      ${pairing.pin}`));
         console.log(chalk.dim(`  Expires:  ${pairing.expiresAt}`));
         console.log();
@@ -274,6 +314,77 @@ program
         ipcClient.disconnect();
     }
 });
+// ── wotann remote ───────────────────────────────────────────
+program
+    .command("remote [actionOrUrl] [url]")
+    .description("Inspect or configure the iOS off-WiFi endpoint")
+    .option("--clear", "Remove the persisted remote endpoint")
+    .action(async (actionOrUrl, url, options) => {
+    const { KairosIPCClient } = await import("./daemon/kairos-ipc.js");
+    let ipcClient = new KairosIPCClient(undefined, { requestTimeoutMs: 5_000 });
+    let daemonAvailable = await ipcClient.connect();
+    if (!daemonAvailable) {
+        ipcClient.disconnect();
+        const repaired = await ensureDaemonIpcForCommand({
+            label: "KAIROS daemon",
+            announce: "KAIROS daemon IPC is unavailable; starting or repairing the daemon...",
+        });
+        if (repaired) {
+            ipcClient = new KairosIPCClient(undefined, { requestTimeoutMs: 5_000 });
+            daemonAvailable = await ipcClient.connect();
+        }
+    }
+    if (!daemonAvailable) {
+        console.error(chalk.red.bold("\n  KAIROS daemon IPC is not reachable.\n"));
+        console.error(chalk.dim(await formatDaemonHealthDiagnostic("  ")));
+        process.exit(1);
+    }
+    try {
+        const action = actionOrUrl?.trim();
+        const targetUrl = action === "set" || action === "configure"
+            ? url?.trim()
+            : action && action !== "status" && action !== "clear"
+                ? action
+                : undefined;
+        if ((action === "set" || action === "configure") && !targetUrl) {
+            console.error(chalk.red("Usage: wotann remote set <ws|wss|http|https-url>"));
+            process.exitCode = 1;
+            return;
+        }
+        const status = options.clear || action === "clear"
+            ? await ipcClient.call("companion.remote.clear")
+            : targetUrl
+                ? await ipcClient.call("companion.remote.configure", { url: targetUrl })
+                : await ipcClient.call("companion.remote.status");
+        const remote = status;
+        console.log(chalk.bold("\nWOTANN Remote Access\n"));
+        console.log(chalk.dim(`  Status: ${remote.status ?? "unknown"}`));
+        console.log(chalk.dim(`  Mode:   ${remote.mode ?? "unknown"}`));
+        if (remote.message)
+            console.log(chalk.dim(`  ${remote.message}`));
+        const endpoints = remote.endpoints ?? [];
+        if (endpoints.length > 0) {
+            console.log();
+            for (const endpoint of endpoints) {
+                const scheme = endpoint.scheme ?? "ws";
+                const port = endpoint.port ?? (scheme === "wss" ? 443 : 3849);
+                console.log(chalk.dim(`  ${endpoint.label ?? "Remote"}: ${scheme}://${endpoint.host ?? "unknown"}:${port}`));
+            }
+        }
+        else {
+            const configured = remote.setupOptions?.find((option) => option.id === "configured-url");
+            if (configured?.command) {
+                console.log();
+                console.log(chalk.dim(`  Configure: ${configured.command}`));
+                console.log(chalk.dim("  Or run:    wotann remote set wss://your-host.example"));
+            }
+        }
+        console.log();
+    }
+    finally {
+        ipcClient.disconnect();
+    }
+});
 // ── wotann init ──────────────────────────────────────────────
 program
     .command("init")
@@ -317,10 +428,29 @@ program
         console.log(chalk.dim(`  Then start a new shell. WOTANN will render Warp-style blocks for every command.`));
         return;
     }
-    // V9 T6.2 — opt-in to the Ink TUI wizard via `--wizard`. The
-    // legacy chalk flow remains the default until the wizard is
-    // proven on real users.
-    if (options.wizard) {
+    // Interactive Ink wizard is now the default for `wotann init`
+    // (with no flags). The legacy chalk flow runs only when the user
+    // passes an explicit mode flag (--free, --minimal, --advanced,
+    // --reset) — those flags imply the user knows what they want and
+    // the report-style output is more useful as a confirmation than
+    // as a hand-holding wizard. `--wizard` is kept as a no-op alias.
+    const hasExplicitMode = Boolean(options.free ||
+        options.minimal ||
+        options.advanced ||
+        options.reset ||
+        options.tdd ||
+        options.extendedContext);
+    // Only launch the wizard when stdin is a real TTY. Non-TTY runs
+    // (CI, piped input, headless scripts) fall through to the legacy
+    // chalk path because Ink's wizard requires raw-mode keyboard
+    // capture and crashes with "Raw mode is not supported" on a piped
+    // stdin — that's what broke `tests/e2e/cli-commands.test.ts >
+    // wotann init` after the wizard-by-default flip. `--wizard`
+    // overrides this gate so a user who really wants the TUI from a
+    // weird terminal can still get it (and accept the crash if their
+    // stdin doesn't support raw mode).
+    const isInteractiveTTY = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+    if ((!hasExplicitMode && isInteractiveTTY) || options.wizard) {
         const { runOnboardingWizard } = await import("./cli/run-onboarding-wizard.js");
         await runOnboardingWizard();
         return;
@@ -1312,6 +1442,73 @@ program
         runtime: interactive.runtime,
     }));
 });
+// ── wotann rewind ───────────────────────────────────────────
+//
+// Drop the last N user-bounded turns (or raw messages, with --messages)
+// from a saved session. Useful when the agent went off-track and you'd
+// rather rewind than /clear and lose the whole conversation. Writes the
+// rewound session back to disk; the original is overwritten — pass
+// --dry-run to preview without saving.
+program
+    .command("rewind")
+    .description("Rewind the latest (or named) session by N turns or messages")
+    .option("--id <sessionId>", "Rewind a specific session by id (default: latest)")
+    .option("--steps <n>", "Number of user-bounded turns to drop", "1")
+    .option("--messages <n>", "Drop raw messages instead of full turns (mutually exclusive with --steps)")
+    .option("--dry-run", "Show what would be removed without writing", false)
+    .action(async (options) => {
+    const { findLatestSession, restoreSession, saveSession } = await import("./core/session.js");
+    const { rewindBySteps, rewindByMessages } = await import("./core/session-rewind.js");
+    const sessionDir = join(process.cwd(), ".wotann", "sessions");
+    let sessionPath = null;
+    if (options.id) {
+        if (!/^[a-zA-Z0-9_-]+$/.test(options.id)) {
+            console.error(chalk.red(`error: invalid session id "${options.id}"`));
+            process.exit(2);
+        }
+        const candidate = join(sessionDir, `${options.id}.json`);
+        sessionPath = existsSync(candidate) ? candidate : null;
+    }
+    else {
+        sessionPath = findLatestSession(sessionDir);
+    }
+    if (!sessionPath) {
+        console.error(chalk.yellow("No matching session found."));
+        process.exit(1);
+    }
+    const session = restoreSession(sessionPath);
+    if (!session) {
+        console.error(chalk.red("Failed to read session."));
+        process.exit(1);
+    }
+    const useMessages = typeof options.messages === "string";
+    const n = Number(useMessages ? options.messages : options.steps);
+    if (!Number.isFinite(n) || n <= 0) {
+        console.error(chalk.red(`error: count must be a positive integer (got "${n}")`));
+        process.exit(2);
+    }
+    const result = useMessages ? rewindByMessages(session, n) : rewindBySteps(session, n);
+    if (!result.changed) {
+        console.log(chalk.dim("Nothing to rewind."));
+        return;
+    }
+    console.log(chalk.bold(`\nRewinding ${useMessages ? "messages" : "turns"}: ${n}`));
+    console.log(chalk.dim(`  Session : ${session.id}`));
+    console.log(chalk.dim(`  Removed : ${result.removed.length} message(s) — totals recomputed`));
+    for (const m of result.removed.slice(0, 6)) {
+        const preview = (m.content ?? "").replace(/\s+/g, " ").slice(0, 80);
+        console.log(chalk.dim(`    [${m.role}] ${preview}${preview.length === 80 ? "…" : ""}`));
+    }
+    if (result.removed.length > 6) {
+        console.log(chalk.dim(`    … and ${result.removed.length - 6} more`));
+    }
+    if (options.dryRun === true) {
+        console.log(chalk.yellow("\n--dry-run: not writing changes."));
+        return;
+    }
+    const writtenPath = saveSession(result.session, sessionDir);
+    console.log(chalk.green(`\n✓ Wrote rewound session to ${writtenPath}`));
+});
 // ── wotann next ─────────────────────────────────────────────
 program
     .command("next")
@@ -1430,13 +1627,26 @@ daemonCmd
         // status file already reflects the loaded heartbeat tasks
     }
 });
+daemonCmd
+    .command("jsonl")
+    .description("Run a foreground JSON-RPC daemon gateway over stdin/stdout")
+    .action(async () => {
+    try {
+        const { runKairosJsonlMode } = await import("./daemon/jsonl-mode.js");
+        await runKairosJsonlMode();
+    }
+    catch (error) {
+        process.stderr.write(`[KAIROS JSONL] ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(1);
+    }
+});
 daemonCmd
     .command("start")
     .description("Start the background daemon")
     .option("-v, --verbose", "Stream daemon log output to the terminal for the startup window")
     .action(async (opts) => {
     const { existsSync, mkdirSync, readFileSync } = await import("node:fs");
-    const { pidPath } = getDaemonPaths();
+    const { pidPath, statusPath } = getDaemonPaths();
     const wotannDir = join(process.cwd(), ".wotann");
     // TIER 4 fix: 0o700 perms — .wotann/ holds memory DBs, conversation cache,
     // potentially OAuth tokens. Other-user-readable could leak credentials.
@@ -1445,8 +1655,24 @@ daemonCmd
     if (existsSync(pidPath)) {
         const existingPid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
         if (isProcessAlive(existingPid)) {
-            console.log(chalk.yellow(`KAIROS daemon already running (PID ${existingPid}).`));
-            return;
+            const ipcReachable = await isDaemonIpcReachable();
+            if (ipcReachable) {
+                console.log(chalk.yellow(`KAIROS daemon already running (PID ${existingPid}).`));
+                return;
+            }
+            else {
+                console.log(chalk.yellow(`KAIROS daemon PID ${existingPid} is alive, but the IPC socket is not reachable.`));
+                console.log(chalk.dim("Repairing by restarting the daemon process..."));
+                const stopped = await stopDaemonProcess(existingPid, "KAIROS daemon");
+                if (!stopped) {
+                    console.error(chalk.red(`Could not stop KAIROS daemon PID ${existingPid}.`));
+                    process.exit(1);
+                }
+                await cleanupDaemonStateFiles(pidPath, statusPath);
+            }
+        }
+        else {
+            await cleanupDaemonStateFiles(pidPath, statusPath);
         }
     }
     const entryPath = fileURLToPath(import.meta.url);
@@ -1465,7 +1691,7 @@ daemonCmd
             process.exit(0);
         });
     }
-    const ready = await waitForDaemonReady(pidPath, 6_000);
+    const ready = await waitForDaemonReady(pidPath, 15_000);
     if (!ready) {
         console.error(chalk.red("KAIROS daemon failed to start."));
         process.exit(1);
@@ -1531,7 +1757,16 @@ daemonCmd
     if (existsSync(pidPath)) {
         const pid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
         if (isProcessAlive(pid)) {
-            console.log(chalk.green(`KAIROS daemon running (PID ${pid})`));
+            const ipcReachable = await isDaemonIpcReachable();
+            if (ipcReachable) {
+                console.log(chalk.green(`KAIROS daemon running (PID ${pid})`));
+                console.log(chalk.dim("  IPC: reachable"));
+            }
+            else {
+                console.log(chalk.yellow(`KAIROS daemon process alive (PID ${pid}), but IPC is unreachable`));
+                console.log(chalk.dim("  IPC: not reachable"));
+                console.log(chalk.dim("  Run `wotann daemon start` to repair it."));
+            }
             if (existsSync(statusPath)) {
                 try {
                     const status = JSON.parse(readFileSync(statusPath, "utf-8"));
@@ -1564,7 +1799,7 @@ engineCmd
     .description("Start the WOTANN engine (background daemon with runtime hosting)")
     .action(async () => {
     const { existsSync, mkdirSync, readFileSync } = await import("node:fs");
-    const { pidPath } = getDaemonPaths();
+    const { pidPath, statusPath } = getDaemonPaths();
     const wotannDir = join(process.cwd(), ".wotann");
     // TIER 4 fix: 0o700 perms — .wotann/ holds memory DBs, conversation cache,
     // potentially OAuth tokens. Other-user-readable could leak credentials.
@@ -1573,8 +1808,24 @@ engineCmd
     if (existsSync(pidPath)) {
         const existingPid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
         if (isProcessAlive(existingPid)) {
-            console.log(chalk.yellow(`WOTANN engine already running (PID ${existingPid}).`));
-            return;
+            const ipcReachable = await isDaemonIpcReachable();
+            if (ipcReachable) {
+                console.log(chalk.yellow(`WOTANN engine already running (PID ${existingPid}).`));
+                return;
+            }
+            else {
+                console.log(chalk.yellow(`WOTANN engine PID ${existingPid} is alive, but the IPC socket is not reachable.`));
+                console.log(chalk.dim("Repairing by restarting the engine process..."));
+                const stopped = await stopDaemonProcess(existingPid, "WOTANN engine");
+                if (!stopped) {
+                    console.error(chalk.red(`Could not stop WOTANN engine PID ${existingPid}.`));
+                    process.exit(1);
+                }
+                await cleanupDaemonStateFiles(pidPath, statusPath);
+            }
+        }
+        else {
+            await cleanupDaemonStateFiles(pidPath, statusPath);
         }
     }
     const entryPath = fileURLToPath(import.meta.url);
@@ -1582,7 +1833,7 @@ engineCmd
     // daemon runs independently. `void` marks the discard explicitly so
     // future readers don't think the handle was forgotten by accident.
     void spawnDaemonWorker(entryPath, process.cwd());
-    const ready = await waitForDaemonReady(pidPath, 6_000);
+    const ready = await waitForDaemonReady(pidPath, 15_000);
     if (!ready) {
         console.error(chalk.red("WOTANN engine failed to start."));
         process.exit(1);
@@ -1669,7 +1920,16 @@ engineCmd
     if (existsSync(pidPath)) {
         const pid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
         if (isProcessAlive(pid)) {
-            console.log(chalk.green(`WOTANN engine running (PID ${pid})`));
+            const ipcReachable = await isDaemonIpcReachable();
+            if (ipcReachable) {
+                console.log(chalk.green(`WOTANN engine running (PID ${pid})`));
+                console.log(chalk.dim("  IPC: reachable"));
+            }
+            else {
+                console.log(chalk.yellow(`WOTANN engine process alive (PID ${pid}), but IPC is unreachable`));
+                console.log(chalk.dim("  IPC: not reachable"));
+                console.log(chalk.dim("  Run `wotann engine start` to repair it."));
+            }
             if (existsSync(statusPath)) {
                 try {
                     // Wave 4F: richer telemetry emitted every 30s by the
@@ -1789,7 +2049,7 @@ engineCmd
     }
     const entryPath = fileURLToPath(import.meta.url);
     void spawnDaemonWorker(entryPath, process.cwd());
-    const ready = await waitForDaemonReady(pidPath, 6_000);
+    const ready = await waitForDaemonReady(pidPath, 15_000);
     if (!ready) {
         console.error(chalk.red("WOTANN engine failed to restart."));
         process.exit(1);
@@ -3037,6 +3297,8 @@ mcpCmd
     .option("--from-codex", "Import from ~/.codex/mcp.json")
     .option("--from-vscode", "Import from VSCode settings.json (stable + Insiders, mac/linux/win)")
     .option("--dry-run", "List what would be imported without modifying ~/.wotann/mcp.json")
+    .option("--skip-malware-check", "Skip the OSV.dev malware/CVE pre-flight (not recommended)", false)
+    .option("--strict-malware-check", "Block on high/critical CVEs (default: only block confirmed malware)", false)
     .description("Import MCP servers from other tools (Claude/Cursor/Windsurf/Codex/VSCode) into ~/.wotann/mcp.json")
     .action(async (options) => {
     const { MCPRegistry } = await import("./marketplace/registry.js");
@@ -3092,6 +3354,21 @@ mcpCmd
         console.log();
         return;
     }
+    // OSV.dev malware/CVE pre-flight — gated before persistToDisk so a
+    // typosquat or compromised package never reaches user config.
+    const { preflight: osvPreflight } = await import("./security/osv-check.js");
+    const importedServers = registry.getAllServers().map((s) => ({
+        name: s.name,
+        command: s.command,
+        args: [...s.args],
+    }));
+    const osvVerdict = await osvPreflight(importedServers, {
+        skip: options.skipMalwareCheck === true,
+        strict: options.strictMalwareCheck === true,
+    });
+    if (!osvVerdict.proceed) {
+        process.exit(1);
+    }
     // Persist to ~/.wotann/mcp.json so other wotann commands see the
     // imports.
     const path = registry.persistToDisk();
@@ -3161,6 +3438,8 @@ mcpCmd
     .option("--args <args...>", "Arguments passed to the command (space-separated)")
     .option("--transport <transport>", "Transport: stdio (default) or http", "stdio")
     .option("-f, --force", "Overwrite an existing server with the same name", false)
+    .option("--skip-malware-check", "Skip the OSV.dev malware/CVE pre-flight (not recommended)", false)
+    .option("--strict-malware-check", "Block on high/critical CVEs (default: only block confirmed malware)", false)
     .action(async (name, options) => {
     if (!options.command) {
         console.error(chalk.red("error: --command <cmd> is required"));
@@ -3189,6 +3468,16 @@ mcpCmd
         console.error(chalk.dim("Use --force to overwrite, or `wotann mcp list` to see existing servers."));
         process.exit(1);
     }
+    // OSV.dev malware/CVE pre-flight — gated before write so a typosquat
+    // or known-compromised package never reaches disk.
+    const { preflight: osvPreflight } = await import("./security/osv-check.js");
+    const osvVerdict = await osvPreflight([{ name, command: options.command, args: options.args ?? [] }], {
+        skip: options.skipMalwareCheck === true,
+        strict: options.strictMalwareCheck === true,
+    });
+    if (!osvVerdict.proceed) {
+        process.exit(1);
+    }
     const updated = {
         ...config,
         [key]: {
@@ -3680,6 +3969,7 @@ skillSourceCmd
     .description("Register a new skill source (e.g. add my-skills github.com owner/repo)")
     .option("--path <subpath>", "Path within the repo (e.g. `skills`)")
     .option("--ref <ref>", "Branch, tag, or commit reference")
+    .option("--no-prefetch", "Skip the eager clone — only register in config")
     .action(async (id, host, repo, options) => {
     const { config, path: configPath } = await loadSkillSourceConfig();
     if (config.sources.some((s) => s.id === id)) {
@@ -3702,6 +3992,35 @@ skillSourceCmd
     await writeSkillSourceConfig(next, configPath);
     console.log(chalk.green(`✓ added skill source "${id}" → ${host}/${repo}`));
     console.log(chalk.dim(`  config: ${configPath}`));
+    // Eager prefetch: actively clone via addGitSource so the new source
+    // is usable immediately, not only on the next `skill source fetch`.
+    // Pre-Wave-2 the CLI's add command and the marketplace's
+    // addGitSource were two separate "add a source" paradigms that
+    // never met — `add` wrote JSON, `addGitSource` did the clone, and
+    // nothing bridged them. This wire closes that gap. Skippable via
+    // `--no-prefetch` for users on metered networks or when the
+    // GitHub host can't be reached at config-time.
+    if (options.prefetch !== false && host === "github.com") {
+        const { addGitSource, SkillMarketplace } = await import("./marketplace/registry.js");
+        try {
+            const marketplace = new SkillMarketplace();
+            const spec = options.ref !== undefined && options.ref.length > 0 ? `${repo}@${options.ref}` : repo;
+            const result = await addGitSource(marketplace, spec, {
+                sparsePaths: options.path !== undefined && options.path.length > 0 ? [options.path] : undefined,
+            });
+            if (result.ok) {
+                console.log(chalk.dim(`  prefetched → ~/.wotann/marketplace-cache/`));
+            }
+            else {
+                console.log(chalk.yellow(`  prefetch skipped — ${result.error}. Source is registered; run \`wotann skill source fetch ${id} <skill>\` to retry.`));
+            }
+        }
+        catch (e) {
+            // Prefetch is best-effort — never blocks the registration.
+            const msg = e instanceof Error ? e.message : String(e);
+            console.log(chalk.yellow(`  prefetch threw — ${msg}. Source is registered.`));
+        }
+    }
 });
 skillSourceCmd
     .command("fetch <sourceId> <skillName>")
@@ -4364,91 +4683,39 @@ function parseBudgetToMs(spec) {
     return Math.floor(value * mult);
 }
 // ── wotann onboard ──────────────────────────────────────────
+//
+// `onboard` and `init` both route to the same interactive wizard now —
+// having two near-identical static-text reports was confusing (the user
+// flagged "wtf is this" on init's report, then independently flagged the
+// same thing on onboard's). One source of truth: the Ink wizard at
+// src/cli/onboarding-screens.tsx, invoked via runOnboardingWizard().
+// `onboard` stays as a discoverable verb but is structurally an alias.
 program
     .command("onboard")
-    .description("Interactive provider setup — guides through configuring all available providers")
-    .action(async () => {
-    console.log(chalk.bold("\nWOTANN Provider Onboarding\n"));
-    console.log(chalk.dim("  Checking for available providers...\n"));
-    const { discoverProviders, formatFullStatus } = await import("./providers/discovery.js");
-    const providers = await discoverProviders();
-    const statuses = formatFullStatus(providers);
-    const SETUP_GUIDE = [
-        {
-            provider: "anthropic",
-            label: "Anthropic Claude",
-            instructions: [
-                "Option A (Subscription): Install Claude Code CLI and log in:",
-                "  npm install -g @anthropic-ai/claude-code && claude login",
-                "Option B (API Key): Set ANTHROPIC_API_KEY in your shell:",
-                "  export ANTHROPIC_API_KEY=sk-ant-...",
-            ],
-        },
-        {
-            provider: "codex",
-            label: "OpenAI Codex (ChatGPT subscription)",
-            instructions: [
-                "Authenticate via Codex CLI (uses your ChatGPT Plus/Pro subscription):",
-                '  npx @openai/codex --full-auto "hello"',
-                "This creates ~/.codex/auth.json with your OAuth tokens.",
-            ],
-        },
-        {
-            provider: "openai",
-            label: "OpenAI API",
-            instructions: [
-                "Set OPENAI_API_KEY in your shell:",
-                "  export OPENAI_API_KEY=sk-...",
-                "Get a key at: https://platform.openai.com/api-keys",
-            ],
-        },
-        {
-            provider: "copilot",
-            label: "GitHub Copilot",
-            instructions: [
-                "Set GH_TOKEN with Copilot access:",
-                "  export GH_TOKEN=$(gh auth token)",
-                "Requires GitHub Copilot subscription: https://github.com/settings/copilot",
-            ],
-        },
-        {
-            provider: "gemini",
-            label: "Google Gemini (free tier: 1.5M tokens/day)",
-            instructions: [
-                "Get a free API key at: https://aistudio.google.com/app/apikey",
-                "  export GEMINI_API_KEY=AI...",
-            ],
-        },
-        {
-            provider: "ollama",
-            label: "Ollama (local, free, private)",
-            instructions: [
-                "Install Ollama: https://ollama.ai",
-                "  ollama serve",
-                "  ollama pull qwen3.5:27b      # best for 24GB+ VRAM",
-                "  ollama pull qwen3.5:9b       # for 8GB VRAM",
-            ],
-        },
-    ];
-    for (const guide of SETUP_GUIDE) {
-        const status = statuses.find((s) => s.provider === guide.provider);
-        const active = status?.available ?? false;
-        const icon = active ? chalk.green("ok") : chalk.yellow("--");
-        const label = active ? chalk.green(guide.label) : chalk.white(guide.label);
-        console.log(`  ${icon} ${label}`);
-        if (active) {
-            console.log(chalk.dim(`    Active (${status?.billing}) — ${status?.models.slice(0, 2).join(", ")}`));
-        }
-        else {
-            for (const line of guide.instructions) {
-                console.log(chalk.dim(`    ${line}`));
-            }
+    .description("Interactive provider setup wizard (alias of `wotann init`)")
+    .option("--print", "Print a static report instead of launching the wizard")
+    .action(async (options) => {
+    // Auto-fall-back to the print path when stdin isn't a TTY (CI,
+    // piped input, headless scripts) — same rule as `wotann init`.
+    // The wizard's Ink raw-mode requirement crashes otherwise.
+    const isInteractiveTTY = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+    if (options.print || !isInteractiveTTY) {
+        // Headless / scripted path — write a machine-friendly status
+        // report and exit. Useful for CI / dotfile bootstrap scripts that
+        // want to verify provider setup without opening a TUI.
+        const { discoverProviders, formatFullStatus } = await import("./providers/discovery.js");
+        const providers = await discoverProviders();
+        const statuses = formatFullStatus(providers);
+        const active = statuses.filter((s) => s.available);
+        console.log(`${active.length} providers active, ${statuses.length - active.length} available to configure`);
+        for (const s of statuses) {
+            const tag = s.available ? "ACTIVE" : "MISSING";
+            console.log(`${tag}\t${s.provider}\t${s.billing ?? ""}\t${s.models.slice(0, 3).join(",")}`);
         }
-        console.log();
+        return;
     }
-    const active = statuses.filter((s) => s.available);
-    console.log(chalk.bold(`  ${active.length} providers active, ${statuses.length - active.length} available to configure`));
-    console.log(chalk.dim("  Re-run `wotann onboard` after configuration to verify.\n"));
+    const { runOnboardingWizard } = await import("./cli/run-onboarding-wizard.js");
+    await runOnboardingWizard();
 });
 // ── wotann serve ────────────────────────────────────────────
 program
@@ -4885,8 +5152,120 @@ function getDaemonPaths() {
     return {
         pidPath: join(wotannDir, "daemon.pid"),
         statusPath: join(wotannDir, "daemon.status.json"),
+        socketPath: process.platform === "win32"
+            ? resolveDaemonSocketPath({ daemonId: "kairos" })
+            : join(wotannDir, "kairos.sock"),
     };
 }
+async function isDaemonIpcReachable(timeoutMs = 750) {
+    const { socketPath } = getDaemonPaths();
+    if (!existsSync(socketPath))
+        return false;
+    const { createConnection } = await import("node:net");
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(ok);
+        };
+        const client = createConnection(socketPath, () => {
+            client.end();
+            finish(true);
+        });
+        client.setTimeout(timeoutMs, () => {
+            client.destroy();
+            finish(false);
+        });
+        client.on("error", () => finish(false));
+        client.on("close", () => finish(false));
+    });
+}
+async function ensureDaemonIpcForCommand(options) {
+    if (await isDaemonIpcReachable())
+        return true;
+    if (options.announce) {
+        console.error(chalk.yellow(options.announce));
+    }
+    const { pidPath, statusPath } = getDaemonPaths();
+    const { existsSync, readFileSync } = await import("node:fs");
+    if (existsSync(pidPath)) {
+        const pid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
+        if (isProcessAlive(pid)) {
+            console.error(chalk.dim(`${options.label} PID ${pid} is alive, but its IPC socket is not reachable.`));
+            console.error(chalk.dim("Repairing by restarting the process..."));
+            const stopped = await stopDaemonProcess(pid, options.label);
+            if (!stopped)
+                return false;
+        }
+        await cleanupDaemonStateFiles(pidPath, statusPath);
+    }
+    const entryPath = fileURLToPath(import.meta.url);
+    void spawnDaemonWorker(entryPath, process.cwd());
+    return (await waitForDaemonReady(pidPath, 15_000)) !== null;
+}
+async function stopDaemonProcess(pid, label) {
+    if (!isProcessAlive(pid))
+        return true;
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch {
+        return false;
+    }
+    await waitForProcessExit(pid, 5_000);
+    if (!isProcessAlive(pid))
+        return true;
+    console.error(chalk.yellow(`${label} PID ${pid} did not exit after SIGTERM; escalating to SIGKILL.`));
+    try {
+        process.kill(pid, "SIGKILL");
+    }
+    catch {
+        return false;
+    }
+    await waitForProcessExit(pid, 2_000);
+    return !isProcessAlive(pid);
+}
+async function cleanupDaemonStateFiles(pidPath, statusPath) {
+    const { unlinkSync } = await import("node:fs");
+    for (const path of [pidPath, statusPath]) {
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+async function formatDaemonHealthDiagnostic(indent = "") {
+    const { pidPath, socketPath, statusPath } = getDaemonPaths();
+    const { existsSync, readFileSync } = await import("node:fs");
+    const lines = [];
+    if (!existsSync(pidPath)) {
+        lines.push(`${indent}No daemon PID file found at ${pidPath}.`);
+    }
+    else {
+        const pid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
+        lines.push(isProcessAlive(pid)
+            ? `${indent}Daemon PID file exists (${pid}), and the process is alive.`
+            : `${indent}Daemon PID file exists (${pid}), but the process is not alive.`);
+    }
+    lines.push(existsSync(socketPath)
+        ? `${indent}IPC socket exists at ${socketPath}, but connection failed.`
+        : `${indent}IPC socket is missing at ${socketPath}.`);
+    if (existsSync(statusPath)) {
+        try {
+            const status = JSON.parse(readFileSync(statusPath, "utf-8"));
+            if (typeof status.status === "string")
+                lines.push(`${indent}Status file says: ${status.status}.`);
+        }
+        catch {
+            lines.push(`${indent}Status file is present but malformed.`);
+        }
+    }
+    return lines.join("\n");
+}
 function formatTokenCount(tokens) {
     if (tokens >= 1_000_000)
         return `${(tokens / 1_000_000).toFixed(tokens % 1_000_000 === 0 ? 0 : 2)}M`;
@@ -4930,7 +5309,7 @@ async function waitForDaemonReady(pidPath, timeoutMs) {
     while (Date.now() < deadline) {
         if (existsSync(pidPath)) {
             const pid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
-            if (Number.isFinite(pid) && isProcessAlive(pid)) {
+            if (Number.isFinite(pid) && isProcessAlive(pid) && (await isDaemonIpcReachable(250))) {
                 return pid;
             }
         }
@@ -4953,7 +5332,12 @@ function isProcessAlive(pid) {
         process.kill(pid, 0);
         return true;
     }
-    catch {
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return false;
+        if (code === "EPERM")
+            return true;
         // Best-effort path — caller gets a safe fallback, no user-facing error.
         return false;
     }
@@ -6277,7 +6661,8 @@ program
     const maxIter = parseInt(opts.maxIterations ?? "0", 10);
     const executor = async (cmd) => {
         return new Promise((resolvePromise) => {
-            const child = spawn("sh", ["-c", cmd], {
+            const shell = buildShellCommand(cmd);
+            const child = spawn(shell.file, [...shell.argv], {
                 stdio: "inherit",
                 cwd: process.cwd(),
                 env: process.env,
@@ -6420,6 +6805,209 @@ intentByoaCmd
     const { registerExploitCommands } = await import("./cli/commands/exploit.js");
     registerExploitCommands(program);
 }
+// ── wotann persona — identity persona inspection + switching ──
+//
+// PersonaManager (src/identity/persona.ts) loads YAML profiles from
+// `.wotann/personas/` but had no CLI surface — users couldn't see
+// what persona was active or switch between them. This wire exposes
+// list/show/active/switch/init through the standard intent-style
+// handler pattern: pure handler in cli/commands/persona.ts, this
+// shell only translates commander args.
+{
+    const personaCmd = program
+        .command("persona")
+        .description("List, show, switch, or scaffold WOTANN identity personas");
+    // Matches prompt/engine.ts:loadPersona which expects personas under
+    // `<workspaceRoot>/.wotann/personas/`. PersonaManager appends the
+    // "personas" subdir; the active-persona pointer file lives next to
+    // it as `<workspaceRoot>/.wotann/active-persona`.
+    const dotWotann = () => join(process.cwd(), ".wotann");
+    personaCmd
+        .command("list")
+        .description("List configured personas in .wotann/personas/")
+        .action(async () => {
+        const { runPersonaCommand } = await import("./cli/commands/persona.js");
+        const result = await runPersonaCommand({ action: "list", wotannDir: dotWotann() });
+        for (const line of result.lines)
+            process.stdout.write(`${line}\n`);
+        if (!result.success) {
+            process.stderr.write(chalk.red(`✗ ${result.error ?? "failed"}\n`));
+            process.exit(1);
+        }
+    });
+    personaCmd
+        .command("show <name>")
+        .description("Print the YAML-derived persona profile")
+        .action(async (name) => {
+        const { runPersonaCommand } = await import("./cli/commands/persona.js");
+        const result = await runPersonaCommand({ action: "show", name, wotannDir: dotWotann() });
+        for (const line of result.lines)
+            process.stdout.write(`${line}\n`);
+        if (!result.success) {
+            process.stderr.write(chalk.red(`✗ ${result.error ?? "failed"}\n`));
+            process.exit(1);
+        }
+    });
+    personaCmd
+        .command("active")
+        .description("Show the currently-active persona")
+        .action(async () => {
+        const { runPersonaCommand } = await import("./cli/commands/persona.js");
+        const result = await runPersonaCommand({ action: "active", wotannDir: dotWotann() });
+        for (const line of result.lines)
+            process.stdout.write(`${line}\n`);
+        if (!result.success) {
+            process.stderr.write(chalk.red(`✗ ${result.error ?? "failed"}\n`));
+            process.exit(1);
+        }
+    });
+    personaCmd
+        .command("switch <name>")
+        .description("Set the active persona (writes .wotann/active-persona)")
+        .action(async (name) => {
+        const { runPersonaCommand } = await import("./cli/commands/persona.js");
+        const result = await runPersonaCommand({ action: "switch", name, wotannDir: dotWotann() });
+        for (const line of result.lines)
+            process.stdout.write(`${line}\n`);
+        if (!result.success) {
+            process.stderr.write(chalk.red(`✗ ${result.error ?? "failed"}\n`));
+            process.exit(1);
+        }
+    });
+    personaCmd
+        .command("init")
+        .description("Scaffold a default persona under .wotann/personas/")
+        .action(async () => {
+        const { runPersonaCommand } = await import("./cli/commands/persona.js");
+        const result = await runPersonaCommand({ action: "init", wotannDir: dotWotann() });
+        for (const line of result.lines)
+            process.stdout.write(`${line}\n`);
+        if (!result.success) {
+            process.stderr.write(chalk.red(`✗ ${result.error ?? "failed"}\n`));
+            process.exit(1);
+        }
+    });
+}
+// ── wotann learning — inspect daemon-internal learning state ──
+//
+// The learning subsystem (DreamPipeline, FeedbackCollector,
+// PatternCrystallizer, DecisionLedger) runs ONLY inside the daemon
+// and accumulates state in .wotann/memory.db + .wotann/.dreams/ +
+// .wotann/LESSONS.md. Until this wire there was no way for users to
+// see what the agent had learned. Pure handler in
+// cli/commands/learning.ts reads SQLite + disk directly (no runtime
+// or daemon coupling).
+{
+    const learningCmd = program
+        .command("learning")
+        .description("Inspect dreams, patterns, decisions, lessons, and learning stats");
+    const dotWotann = () => join(process.cwd(), ".wotann");
+    const wireSimpleSubcommand = (name, description, action) => {
+        learningCmd
+            .command(name)
+            .description(description)
+            .action(async () => {
+            const { runLearningCommand } = await import("./cli/commands/learning.js");
+            const result = await runLearningCommand({ action, wotannDir: dotWotann() });
+            for (const line of result.lines)
+                process.stdout.write(`${line}\n`);
+            if (!result.success) {
+                process.stderr.write(chalk.red(`✗ ${result.error ?? "failed"}\n`));
+                process.exit(1);
+            }
+        });
+    };
+    wireSimpleSubcommand("dreams", "List crystallized dreams from the daemon's dream pipeline", "dreams");
+    wireSimpleSubcommand("patterns", "List patterns from PatternCrystallizer (SQLite layer=patterns)", "patterns");
+    wireSimpleSubcommand("decisions", "List decisions from the DecisionLedger SQLite table", "decisions");
+    wireSimpleSubcommand("lessons", "List gotchas extracted from .wotann/LESSONS.md", "lessons");
+    wireSimpleSubcommand("stats", "Summary counts across all learning surfaces", "stats");
+}
+// ── wotann evolve — evolutionary skill optimisation ──
+//
+// The evolution subsystem (Optimizer / Mutator / Evaluator / constraints,
+// ~711 LOC) was reachable only via dream-runner inside the daemon. This
+// wire exposes status / history / constraints inspection plus the real
+// runOptimization() entry-point for user-driven evolution runs.
+{
+    const evolveCmd = program
+        .command("evolve")
+        .description("Inspect or run skill evolution (Optimizer / Mutator / Evaluator)");
+    const dotWotann = () => join(process.cwd(), ".wotann");
+    evolveCmd
+        .command("status")
+        .description("Show last evolution-run timestamp + fitness")
+        .action(async () => {
+        const { runEvolveCommand } = await import("./cli/commands/evolve.js");
+        const result = await runEvolveCommand({ action: "status", wotannDir: dotWotann() });
+        for (const line of result.lines)
+            process.stdout.write(`${line}\n`);
+        if (!result.success) {
+            process.stderr.write(chalk.red(`✗ ${result.error ?? "failed"}\n`));
+            process.exit(1);
+        }
+    });
+    evolveCmd
+        .command("history [count]")
+        .description("Last N generations (default 10) from .wotann/evolution-log.jsonl")
+        .action(async (count) => {
+        const { runEvolveCommand } = await import("./cli/commands/evolve.js");
+        const parsedCount = count ? Number.parseInt(count, 10) : undefined;
+        const result = await runEvolveCommand({
+            action: "history",
+            wotannDir: dotWotann(),
+            ...(typeof parsedCount === "number" && Number.isFinite(parsedCount)
+                ? { count: parsedCount }
+                : {}),
+        });
+        for (const line of result.lines)
+            process.stdout.write(`${line}\n`);
+        if (!result.success) {
+            process.stderr.write(chalk.red(`✗ ${result.error ?? "failed"}\n`));
+            process.exit(1);
+        }
+    });
+    evolveCmd
+        .command("constraints")
+        .description("Print FORBIDDEN_TOKENS + structural caps")
+        .action(async () => {
+        const { runEvolveCommand } = await import("./cli/commands/evolve.js");
+        const result = await runEvolveCommand({ action: "constraints", wotannDir: dotWotann() });
+        for (const line of result.lines)
+            process.stdout.write(`${line}\n`);
+        if (!result.success) {
+            process.stderr.write(chalk.red(`✗ ${result.error ?? "failed"}\n`));
+            process.exit(1);
+        }
+    });
+    evolveCmd
+        .command("run <skill-path>")
+        .description("Run one evolution round on the skill file at <skill-path>")
+        .option("--population <n>", "Population size", (v) => Number(v))
+        .option("--generations <n>", "Number of generations (default 1)", (v) => Number(v))
+        .option("--target-fitness <n>", "Stop when fitness reaches this", (v) => Number(v))
+        .option("--write", "Write the winning variant back over the skill file (original archived)")
+        .option("--budget <usd>", "Max spend in USD before stopping", (v) => Number(v))
+        .action(async (skillPath, opts) => {
+        const { runEvolveCommand } = await import("./cli/commands/evolve.js");
+        const result = await runEvolveCommand({
+            action: "run",
+            wotannDir: dotWotann(),
+            skillPath,
+            ...(typeof opts.population === "number" ? { population: opts.population } : {}),
+            ...(typeof opts.generations === "number" ? { generations: opts.generations } : {}),
+            ...(typeof opts.targetFitness === "number" ? { targetFitness: opts.targetFitness } : {}),
+            ...(opts.write === true ? { write: true } : {}),
+            ...(typeof opts.budget === "number" ? { budgetUsd: opts.budget } : {}),
+        });
+        for (const line of result.lines)
+            process.stdout.write(`${line}\n`);
+        if (!result.success) {
+            process.stderr.write(chalk.red(`✗ ${result.error ?? "failed"}\n`));
+            process.exit(1);
+        }
+    });
+}
 // ── wotann grep — B9 ParallelGrep semantic-search wire (P1-B9 wire) ─
 //
 // ParallelGrep (src/tools/parallel-grep.ts + grep-subagent.ts, 716 LOC,
@@ -6432,6 +7020,41 @@ intentByoaCmd
     const { registerGrepCommand } = await import("./cli/commands/grep.js");
     registerGrepCommand(program);
 }
+// ── wotann blast-radius — cross-file symbol usage tracer ───────
+//
+// Companion to grep — instead of free-text search, walks the AST (or
+// ripgrep fallback) for a named symbol and lists every call site
+// across the workspace. Emits a "LOW USAGE" warning when a symbol
+// has ≤1 call site, flagging likely dead exports or unused
+// identifiers. Pure handler in cli/commands/blast-radius.ts; this
+// shell only translates commander args into handler options.
+program
+    .command("blast-radius <symbol>")
+    .description("List cross-file usage sites for a symbol (function/class/variable). Warns when usage ≤1.")
+    .option("--root <dir>", "Project root to scan (defaults to cwd)")
+    .option("--language <lang>", "Restrict to a language (typescript|javascript|python|rust|go|swift). Repeatable.", (value, prev = []) => [...prev, value], [])
+    .option("--max <n>", "Maximum usages to report (default 200)", (v) => Number(v))
+    .option("--json", "Emit machine-readable JSON instead of pretty text", false)
+    .action(async (symbol, opts) => {
+    const { runBlastRadiusCommand } = await import("./cli/commands/blast-radius.js");
+    const validLangs = ["typescript", "javascript", "python", "rust", "go", "swift"];
+    const requested = (opts.language ?? []).filter((l) => validLangs.includes(l));
+    const result = await runBlastRadiusCommand({
+        symbol,
+        rootDir: opts.root ?? process.cwd(),
+        ...(requested.length > 0 ? { languages: requested } : {}),
+        ...(typeof opts.max === "number" && Number.isFinite(opts.max)
+            ? { maxUsages: opts.max }
+            : {}),
+        ...(opts.json === true ? { json: true } : {}),
+    });
+    for (const line of result.lines)
+        process.stdout.write(`${line}\n`);
+    if (!result.success) {
+        process.stderr.write(chalk.red(`✗ ${result.error ?? "blast-radius failed"}\n`));
+        process.exit(1);
+    }
+});
 // ── wotann replay — V9 T14.7 trajectory replay ───────────────
 //
 // `wotann replay <trajectory.json>` plays back a recorded session
@@ -6884,7 +7507,8 @@ program
     }
     const { execFileNoThrow } = await import("./utils/execFileNoThrow.js");
     const probe = async () => {
-        const result = await execFileNoThrow("/bin/sh", ["-c", options.probeCmd]);
+        const probeShell = buildShellCommand(options.probeCmd);
+        const result = await execFileNoThrow(probeShell.file, [...probeShell.argv]);
         if (result.exitCode !== 0) {
             throw new Error(`probe-cmd exited ${result.exitCode}: ${result.stderr}`);
         }
@@ -7884,57 +8508,51 @@ teamsCmd
         console.log(`  ${chalk.cyan(a.padEnd(20))} pending=${counts.pending} consumed=${counts.consumed} done=${counts.done}`);
     }
 });
-// ── wotann evolve (hermes-self-evolution port) ────────────────
-program
-    .command("evolve <skillPath>")
-    .description("Evolve a skill file via the GEPA-style optimizer (hermes-self-evolution port)")
-    .option("--generations <n>", "Number of optimization generations (default 3)", "3")
-    .option("--write", "Write the winning variant back over the skill file (creates archive of original)")
-    .option("--budget <usd>", "Maximum spend in USD before stopping (default $10)", "10")
-    .action(async (skillPath, options) => {
-    const { evolveSkill, buildSyntheticExamples } = await import("./evolution/runner.js");
-    const { existsSync, readFileSync } = await import("node:fs");
-    if (!existsSync(skillPath)) {
-        console.error(chalk.red(`Skill not found: ${skillPath}`));
-        process.exitCode = 1;
-        return;
-    }
-    const baseline = readFileSync(skillPath, "utf8");
-    const examples = buildSyntheticExamples(baseline);
-    // Stub callers that don't actually invoke a provider — preserves
-    // the design contract that the optimizer is provider-agnostic.
-    // Users who want a real provider call can wrap this CLI by passing
-    // their own callable into runOptimization() programmatically.
-    const { makeStubMutator, makeStubEvaluator } = await import("./evolution/optimizer.js");
-    const summary = await evolveSkill({
-        skillPath,
-        examples,
-        mutate: makeStubMutator(),
-        evaluate: makeStubEvaluator(),
-        generations: Number(options.generations) || 3,
-        write: Boolean(options.write),
+// ── wotann evolve standalone (legacy hermes-self-evolution port)
+//
+// This was the original `wotann evolve <skillPath>` standalone. It is
+// now superseded by the `wotann evolve run <skill-path>` subcommand
+// registered higher in this file (which exposes the same evolveSkill
+// path + auto-stub mutator/evaluator, plus --write/--budget support).
+// Removed at integration time to fix the duplicate `evolve` command
+// registration that broke startup. The new subcommand path preserves
+// all previous flags + adds status/history/constraints inspection.
+// ── wotann session — relational-storage fork primitive
+//
+// Parallel-approach exploration: fork an existing session at its last
+// checkpoint into a NEW session row + deep-copy the message thread up
+// to the fork point. Backed by .wotann/sessions.db (better-sqlite3,
+// see src/session/fork.ts). Distinct from `wotann fork-session`
+// (line ~11000 below) which forks the codex-style rollout JSON file
+// — this one is the relational variant for the new sessions schema.
+{
+    const sessionCmd = program
+        .command("session")
+        .description("Session management — relational fork for parallel-approach work");
+    sessionCmd
+        .command("fork <sourceSessionId>")
+        .description("Fork an existing session at its last checkpoint into a new session row")
+        .option("--label <label>", 'Optional label for the new fork (e.g. "approach-A")')
+        .action(async (sourceSessionId, opts) => {
+        const { forkSession } = await import("./session/fork.js");
+        const result = await forkSession({
+            sourceSessionId,
+            wotannDir: join(process.cwd(), ".wotann"),
+            ...(opts.label !== undefined ? { label: opts.label } : {}),
+        });
+        if (!result.ok) {
+            process.stderr.write(chalk.red(`✗ fork failed: ${result.error ?? "unknown"}\n`));
+            process.exit(1);
+        }
+        process.stdout.write(`${chalk.green("✓")} Forked session ${chalk.cyan(sourceSessionId)} → ${chalk.cyan(result.newSessionId ?? "")}\n`);
+        if (typeof result.messageCount === "number") {
+            process.stdout.write(`  Messages copied: ${result.messageCount}\n`);
+        }
+        if (result.sourceCheckpoint) {
+            process.stdout.write(`  Forked from checkpoint: ${result.sourceCheckpoint}\n`);
+        }
     });
-    console.log(chalk.bold(`\nEvolution summary for ${skillPath}\n`));
-    console.log(`  baseline score : ${summary.baselineScore.toFixed(3)}`);
-    console.log(`  best score     : ${summary.bestScore.toFixed(3)}`);
-    console.log(`  improvement    : ${summary.improvementPct.toFixed(1)}%`);
-    console.log(`  generations    : ${summary.generations}`);
-    console.log(`  cost (USD)     : $${summary.totalCostUsd.toFixed(4)}`);
-    if (summary.notes.length > 0) {
-        console.log(chalk.dim("\n  Notes:"));
-        for (const n of summary.notes)
-            console.log(chalk.dim(`    - ${n}`));
-    }
-    if (options.write && summary.bestScore > summary.baselineScore) {
-        console.log(chalk.green(`\n✓ Wrote winning variant to ${skillPath} (original archived)`));
-    }
-    else if (options.write) {
-        console.log(chalk.yellow("\n  No improvement found — skill file left unchanged."));
-    }
-    else {
-        console.log(chalk.dim("\n  (Pass --write to apply the winning variant.)"));
-    }
-});
+}
 const recipeCmd = program.command("recipe").description("Goose-style recipe management (V9 T12.4)");
 // Helper: enumerate recipe filenames in .wotann/recipes/. CLI-local helper
 // since other callers don't need a directory walker.
@@ -8692,6 +9310,8 @@ mcpCmd
     .description("Register an MCP server from a .mcpb manifest into ~/.wotann/wotann.yaml")
     .option("-f, --force", "Overwrite an existing server with the same name", false)
     .option("--name <name>", "Override the manifest's name (rare; mostly for testing)")
+    .option("--skip-malware-check", "Skip the OSV.dev malware/CVE pre-flight (not recommended)", false)
+    .option("--strict-malware-check", "Block on high/critical CVEs (default: only block confirmed malware)", false)
     .action(async (file, options) => {
     const { parseMcpb } = await import("./marketplace/mcpb.js");
     const { resolveWotannHomeSubdir } = await import("./utils/wotann-home.js");
@@ -8730,6 +9350,22 @@ mcpCmd
         process.exit(1);
     }
     const env = manifest.server.mcp_config.env;
+    // OSV.dev malware/CVE pre-flight — gated before write so a typosquat
+    // or compromised package never reaches user config.
+    const { preflight: osvPreflight } = await import("./security/osv-check.js");
+    const osvVerdict = await osvPreflight([
+        {
+            name: serverName,
+            command: manifest.server.mcp_config.command,
+            args: [...manifest.server.mcp_config.args],
+        },
+    ], {
+        skip: options.skipMalwareCheck === true,
+        strict: options.strictMalwareCheck === true,
+    });
+    if (!osvVerdict.proceed) {
+        process.exit(1);
+    }
     const updated = {
         ...config,
         [key]: {
@@ -8754,6 +9390,406 @@ mcpCmd
     console.log(chalk.dim(`  written to:       ${configPath}`));
     console.log(chalk.dim("  Restart the engine for changes to take effect: wotann engine restart"));
 });
+// ── wotann research-strategy <query> ────────────────────────
+//
+// Surfaces the dual-confidence + IterDRAG strategies in
+// src/intelligence/research-strategies.ts. Default flow runs
+// dual-confidence (cheap, 2 search calls) and reports the Jaccard
+// overlap between the two passes as confidence. --strategy=iterdrag
+// switches to depth-bounded recursive Decompose-Retrieve-Aggregate.
+//
+// Distinct from the existing `wotann research <topic>` command which
+// is the LLM-driven autonomous deep-research runtime. This command is
+// strategy-only (no LLM call) and always returns a structured result.
+//
+// Search/decompose/synthesize callbacks are honest-stub by default
+// (echo-only) so the command runs offline; pass --search-cmd or
+// --decompose-cmd to wire your own shell-based search engine.
+program
+    .command("research-strategy <query>")
+    .description("Run a structured research-strategy pass (dual-confidence | iterdrag)")
+    .option("--strategy <name>", "Strategy: dual-confidence (default) | iterdrag", "dual-confidence")
+    .option("--max-depth <n>", "iterdrag tree depth cap", "2")
+    .option("--hits-per-call <n>", "Cap hits per search invocation", "10")
+    .option("--search-cmd <cmd>", "Shell command that takes a query string and emits JSON {url,title?,snippet?}[] on stdout")
+    .option("--json", "Emit JSON instead of human-readable summary", false)
+    .action(async (query, options) => {
+    const strategies = await import("./intelligence/research-strategies.js");
+    const { execFile } = await import("node:child_process");
+    const { promisify } = await import("node:util");
+    const execFileAsync = promisify(execFile);
+    const maxDepth = Number(options.maxDepth ?? 2);
+    const hitsPerCall = Number(options.hitsPerCall ?? 10);
+    const search = async (q) => {
+        if (!options.searchCmd) {
+            // Honest-stub default: echoes one synthetic hit per query so the
+            // pipeline is exercisable end-to-end without a real search backend.
+            return [{ url: `wotann://stub/${encodeURIComponent(q)}`, title: q }];
+        }
+        try {
+            const searchShell = buildShellCommand(`${options.searchCmd} ${JSON.stringify(q)}`);
+            const { stdout } = await execFileAsync(searchShell.file, [...searchShell.argv]);
+            const parsed = JSON.parse(stdout);
+            if (Array.isArray(parsed)) {
+                return parsed.filter((h) => !!h && typeof h === "object" && typeof h.url === "string");
+            }
+            return [];
+        }
+        catch (err) {
+            console.error(chalk.yellow(`  search-cmd failed for "${q}": ${err instanceof Error ? err.message : String(err)}`));
+            return [];
+        }
+    };
+    const strategy = (options.strategy ?? "dual-confidence").toLowerCase();
+    if (strategy === "dual-confidence" || strategy === "dc") {
+        const result = await strategies.dualConfidenceSearch(query, search, {
+            hitsPerCall,
+        });
+        if (options.json === true) {
+            process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+            return;
+        }
+        const banner = result.diverged
+            ? chalk.yellow(`Diverged (low confidence)`)
+            : chalk.green(`Converged (high confidence)`);
+        console.log(chalk.bold(`\nDual-confidence: ${banner}`));
+        console.log(chalk.dim(`  Confidence (Jaccard): ${result.confidence.toFixed(3)}`));
+        console.log(chalk.dim(`  Overlap hits         : ${result.overlap.length}`));
+        console.log(chalk.dim(`  Primary-only         : ${result.primaryHits.length}`));
+        console.log(chalk.dim(`  Twin-only            : ${result.twinHits.length}`));
+        if (result.overlap.length > 0) {
+            console.log(chalk.bold("\nHigh-confidence sources:"));
+            for (const h of result.overlap.slice(0, 8)) {
+                console.log(`  ${chalk.dim("●")} ${h.title ?? h.url} ${chalk.dim(h.url)}`);
+            }
+        }
+        return;
+    }
+    if (strategy === "iterdrag") {
+        const decompose = async (q) => {
+            // Heuristic decomposition: split on " and "/" or "/";", or fall back
+            // to keyword extraction. Useful default that doesn't need an LLM.
+            const parts = q
+                .split(/\s+(?:and|or)\s+|;\s*/i)
+                .filter((p) => p.trim().length > 0);
+            return parts.length > 1 ? parts : [];
+        };
+        const root = await strategies.iterDrag(query, search, decompose, {
+            maxDepth,
+            hitsPerNode: hitsPerCall,
+        });
+        if (options.json === true) {
+            process.stdout.write(JSON.stringify(root, null, 2) + "\n");
+            return;
+        }
+        const all = [...strategies.iterDragNodes(root)];
+        console.log(chalk.bold(`\nIterDRAG: ${all.length} node(s) walked`));
+        for (const n of all) {
+            const indent = "  ".repeat(n.depth);
+            console.log(`${indent}${chalk.cyan(`Q[${n.depth}]`)} ${n.question}`);
+            console.log(chalk.dim(`${indent}  hits: ${n.hits.length}`));
+        }
+        if (root.aggregated) {
+            console.log(chalk.bold("\nAggregated answer:"));
+            console.log(root.aggregated);
+        }
+        return;
+    }
+    console.error(chalk.red(`error: unknown strategy "${strategy}"`));
+    process.exit(2);
+});
+// ── wotann skill optimize-description <name> ────────────────
+//
+// Surfaces src/skills/description-optimizer.ts as a CLI tool. Reads
+// the SKILL.md frontmatter for `name`, evaluates its current
+// description against a labeled prompt corpus, and prints suggested
+// rewrites with their F1 deltas. Pass --write to overwrite the
+// description in-place (the body of the SKILL.md is preserved).
+// Reattach to the existing `skillCmd` (declared near line 4694) — defining
+// `program.command("skill")` again would throw at registration time
+// ("cannot add command 'skill' as already have command 'skill'").
+skillCmd
+    .command("optimize-description <name>")
+    .description("Suggest a higher-F1 description for the named skill")
+    .option("--corpus <path>", "JSON file with {positives: string[], negatives: string[]}")
+    .option("--write", "Overwrite the SKILL.md description with the best variant", false)
+    .option("--threshold <n>", "Trigger threshold ∈ [0,1]", "0.5")
+    .option("--from-telemetry [path]", "Mine the corpus from skill-activation telemetry (default ~/.wotann/skill-telemetry.jsonl)")
+    .option("--max-each <n>", "Cap on positives/negatives mined from telemetry", "200")
+    .option("--json", "Emit JSON instead of a human-readable report", false)
+    .action(async (name, options) => {
+    const { optimizeDescription, evaluateDescription } = await import("./skills/description-optimizer.js");
+    const { resolveWotannHomeSubdir } = await import("./utils/wotann-home.js");
+    const fs = await import("node:fs");
+    const path = await import("node:path");
+    // Locate the SKILL.md — search ~/.wotann/skills/<name>/SKILL.md, then
+    // ./skills/<name>/SKILL.md as a workspace-local fallback.
+    const candidates = [
+        resolveWotannHomeSubdir(path.join("skills", name, "SKILL.md")),
+        path.join(process.cwd(), "skills", name, "SKILL.md"),
+    ];
+    const skillPath = candidates.find((p) => fs.existsSync(p));
+    if (!skillPath) {
+        console.error(chalk.red(`error: SKILL.md for "${name}" not found in:`));
+        for (const c of candidates)
+            console.error(chalk.dim(`  ${c}`));
+        process.exit(1);
+    }
+    const raw = fs.readFileSync(skillPath, "utf-8");
+    const fmMatch = raw.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
+    if (!fmMatch || !fmMatch[1] || !fmMatch[2]) {
+        console.error(chalk.red(`error: SKILL.md missing frontmatter at ${skillPath}`));
+        process.exit(1);
+    }
+    const frontmatter = fmMatch[1];
+    const body = fmMatch[2];
+    const descMatch = frontmatter.match(/^description:\s*(.+)$/m);
+    const currentDesc = descMatch && descMatch[1] ? descMatch[1].trim() : "";
+    if (currentDesc.length === 0) {
+        console.error(chalk.red(`error: no "description" in frontmatter`));
+        process.exit(1);
+    }
+    let positives = [];
+    let negatives = [];
+    if (options.corpus) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(options.corpus, "utf-8"));
+            positives = Array.isArray(parsed.positives) ? parsed.positives : [];
+            negatives = Array.isArray(parsed.negatives) ? parsed.negatives : [];
+        }
+        catch (err) {
+            console.error(chalk.red(`error: failed to read corpus: ${err instanceof Error ? err.message : err}`));
+            process.exit(1);
+        }
+    }
+    // --from-telemetry: mine the corpus directly from observed activations.
+    // This closes the loop end-to-end: real usage → telemetry log → corpus
+    // → optimizer → improved description.
+    if (options.fromTelemetry !== undefined) {
+        const telemetryPath = typeof options.fromTelemetry === "string" && options.fromTelemetry.length > 0
+            ? options.fromTelemetry
+            : resolveWotannHomeSubdir("skill-telemetry.jsonl");
+        const { loadTelemetryLog, extractCorpusForSkill } = await import("./skills/activation-telemetry.js");
+        const result = loadTelemetryLog(telemetryPath);
+        const maxEach = Number(options.maxEach ?? 200);
+        const corpus = extractCorpusForSkill(result.events, name, {
+            maxEach: Number.isFinite(maxEach) && maxEach > 0 ? maxEach : 200,
+        });
+        positives = [...positives, ...corpus.positives];
+        negatives = [...negatives, ...corpus.negatives];
+        console.error(chalk.dim(`  telemetry: ${result.events.length} events scanned (skipped ${result.skipped} malformed) → ${corpus.positives.length} positives + ${corpus.negatives.length} negatives mined for "${name}"`));
+    }
+    if (positives.length === 0) {
+        console.error(chalk.yellow("no labeled prompts (use --corpus or --from-telemetry). Showing baseline eval against empty set."));
+    }
+    const threshold = Number(options.threshold ?? 0.5);
+    const r = await optimizeDescription({
+        current: currentDesc,
+        positives,
+        negatives,
+        threshold,
+    });
+    if (options.json === true) {
+        process.stdout.write(JSON.stringify(r, null, 2) + "\n");
+        return;
+    }
+    console.log(chalk.bold(`\nSkill: ${name}`));
+    console.log(chalk.dim(`  Path: ${skillPath}`));
+    console.log(chalk.bold("\nOriginal:"));
+    console.log(`  ${currentDesc}`);
+    console.log(chalk.dim(`  F1: ${r.originalEval.f1.toFixed(3)} (P ${r.originalEval.precision.toFixed(3)} / R ${r.originalEval.recall.toFixed(3)})`));
+    console.log(chalk.bold("\nBest:"));
+    console.log(`  ${r.best}`);
+    console.log(chalk.dim(`  F1: ${r.bestEval.f1.toFixed(3)} (P ${r.bestEval.precision.toFixed(3)} / R ${r.bestEval.recall.toFixed(3)})`));
+    if (r.candidates.length > 1) {
+        console.log(chalk.bold("\nAll candidates:"));
+        for (const c of r.candidates.slice(0, 8)) {
+            const tag = c.description === currentDesc ? "ORIG" : "    ";
+            console.log(chalk.dim(`  [${tag}] F1=${c.eval.f1.toFixed(3)}  ${c.description.slice(0, 100)}`));
+        }
+    }
+    if (options.write && r.best !== currentDesc) {
+        const newFrontmatter = frontmatter.replace(/^description:\s*.+$/m, `description: ${r.best}`);
+        const updated = `---\n${newFrontmatter}\n---\n${body}`;
+        fs.writeFileSync(skillPath, updated);
+        console.log(chalk.green(`\n✓ Updated description in ${skillPath}`));
+    }
+    else if (options.write) {
+        console.log(chalk.dim("\n--write: best matched original; nothing to do."));
+    }
+    // Touch evaluateDescription so the import isn't dead-code-eliminated.
+    void evaluateDescription;
+});
+// `wotann skill mark-outcome <sessionId> <outcome>` — manually flag the
+// last activation for a session as ok|regret|unknown. Lets users
+// retroactively correct false positives so the description-optimizer
+// corpus reflects real intent.
+skillCmd
+    .command("mark-outcome <sessionId> <outcome>")
+    .description("Flag the last skill activation in a session (ok | regret | unknown)")
+    .action(async (sessionId, outcome) => {
+    if (outcome !== "ok" && outcome !== "regret" && outcome !== "unknown") {
+        console.error(chalk.red(`error: outcome must be ok | regret | unknown (got "${outcome}")`));
+        process.exit(2);
+    }
+    const { SkillActivationTelemetry } = await import("./skills/activation-telemetry.js");
+    const { resolveWotannHomeSubdir } = await import("./utils/wotann-home.js");
+    const t = new SkillActivationTelemetry({
+        path: resolveWotannHomeSubdir("skill-telemetry.jsonl"),
+    });
+    const ok = await t.markOutcome(sessionId, outcome);
+    if (ok) {
+        console.log(chalk.green(`✓ Patched session ${sessionId} → ${outcome}`));
+    }
+    else {
+        console.log(chalk.dim("Telemetry disabled — no patch written."));
+    }
+});
+// `wotann skill telemetry-stats` — show how many activation events
+// the local log has, plus per-skill positive/negative counts via the
+// optimizer corpus extractor.
+skillCmd
+    .command("telemetry-stats")
+    .description("Summarise the skill-activation telemetry log")
+    .option("--skill <name>", "Show per-skill corpus counts for one skill")
+    .option("--json", "Emit JSON instead of a human-readable summary", false)
+    .action(async (options) => {
+    const { loadTelemetryLog, extractCorpusForSkill } = await import("./skills/activation-telemetry.js");
+    const { resolveWotannHomeSubdir } = await import("./utils/wotann-home.js");
+    const path = resolveWotannHomeSubdir("skill-telemetry.jsonl");
+    const result = loadTelemetryLog(path);
+    // Aggregate counts by triggered skill (or "<none>" for null).
+    const counts = new Map();
+    let regretCount = 0;
+    for (const e of result.events) {
+        const key = e.triggered?.skill ?? "<none>";
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+        if (e.outcome === "regret")
+            regretCount++;
+    }
+    const summary = {
+        path,
+        events: result.events.length,
+        malformed: result.skipped,
+        regrets: regretCount,
+        bySkill: Object.fromEntries([...counts.entries()].sort((a, b) => b[1] - a[1])),
+        ...(options.skill
+            ? {
+                skill: options.skill,
+                corpus: extractCorpusForSkill(result.events, options.skill, { maxEach: 1000 }),
+            }
+            : {}),
+    };
+    if (options.json === true) {
+        process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+        return;
+    }
+    console.log(chalk.bold(`\nSkill activation telemetry — ${path}`));
+    console.log(chalk.dim(`  events: ${summary.events}  malformed: ${summary.malformed}  regrets: ${summary.regrets}`));
+    if (summary.events === 0) {
+        console.log(chalk.yellow("\n  No telemetry yet. Run a few queries through `wotann run` to populate the log."));
+        return;
+    }
+    console.log(chalk.bold("\nActivations by skill:"));
+    for (const [name, count] of Object.entries(summary.bySkill)) {
+        console.log(`  ${chalk.cyan(String(name).padEnd(28))} ${String(count).padStart(5)}`);
+    }
+    if (options.skill) {
+        const extracted = extractCorpusForSkill(result.events, options.skill, { maxEach: 1000 });
+        console.log(chalk.bold(`\nCorpus for "${options.skill}":`));
+        console.log(`  positives: ${extracted.positives.length}`);
+        console.log(`  negatives: ${extracted.negatives.length}`);
+    }
+});
+// ── wotann manifest <trajectoryPath> ────────────────────────
+//
+// Surfaces src/autopilot/run-manifest.ts. Reads a Trajectory JSON
+// produced by autopilot/trajectory-recorder.ts and renders the
+// manifest as Markdown (default), JSON (--json), or both.
+program
+    .command("manifest <trajectoryPath>")
+    .description("Render an overnight-run manifest from a trajectory JSON")
+    .option("--json", "Emit JSON instead of Markdown", false)
+    .option("--out <path>", "Write the rendered manifest to a file")
+    .option("--cost <usd>", "Total cost USD to embed in the manifest")
+    .option("--title <title>", "Override the auto-derived task title")
+    .action(async (trajectoryPath, options) => {
+    const fs = await import("node:fs");
+    const { loadTrajectory } = await import("./autopilot/trajectory-recorder.js");
+    const { buildManifest, renderManifestMarkdown, renderManifestJson } = await import("./autopilot/run-manifest.js");
+    if (!fs.existsSync(trajectoryPath)) {
+        console.error(chalk.red(`error: trajectory file not found: ${trajectoryPath}`));
+        process.exit(1);
+    }
+    let trajectory;
+    try {
+        trajectory = await loadTrajectory(trajectoryPath);
+    }
+    catch (err) {
+        console.error(chalk.red(`error: failed to load trajectory: ${err instanceof Error ? err.message : err}`));
+        process.exit(1);
+    }
+    const buildOpts = {};
+    if (options.title)
+        buildOpts.taskTitle = options.title;
+    if (options.cost) {
+        const cost = Number(options.cost);
+        if (Number.isFinite(cost))
+            buildOpts.costUsd = cost;
+    }
+    const manifest = buildManifest(trajectory, buildOpts);
+    const rendered = options.json === true ? renderManifestJson(manifest) : renderManifestMarkdown(manifest);
+    if (options.out) {
+        fs.writeFileSync(options.out, rendered);
+        console.log(chalk.green(`✓ Wrote manifest to ${options.out}`));
+        return;
+    }
+    process.stdout.write(rendered + "\n");
+});
+// ── wotann effort <prompt> ──────────────────────────────────
+//
+// Surfaces src/providers/effort-cascade.ts. Distinct from the existing
+// `wotann route` command (TaskSemanticRouter / model picker) — this one
+// is pure heuristics that returns the recommended starting tier the
+// effort cascade would use. Useful for inspecting how the classifier
+// rates a given prompt before paying for an LLM call.
+program
+    .command("effort <prompt>")
+    .description("Show the effort-cascade tier the classifier picks for a prompt")
+    .option("--max-tier <tier>", "minimal | low | medium | high")
+    .option("--min-tier <tier>", "minimal | low | medium | high")
+    .option("--bump", "Force one-tier bump (e.g. retry after low confidence)", false)
+    .option("--json", "Emit JSON", false)
+    .action(async (prompt, options) => {
+    const { classifyEffort, EFFORT_ORDER } = await import("./providers/effort-cascade.js");
+    const isTier = (t) => EFFORT_ORDER.includes(t);
+    const hints = {};
+    if (options.minTier) {
+        if (!isTier(options.minTier)) {
+            console.error(chalk.red(`error: --min-tier must be one of ${EFFORT_ORDER.join("|")}`));
+            process.exit(2);
+        }
+        hints.minTier = options.minTier;
+    }
+    if (options.maxTier) {
+        if (!isTier(options.maxTier)) {
+            console.error(chalk.red(`error: --max-tier must be one of ${EFFORT_ORDER.join("|")}`));
+            process.exit(2);
+        }
+        hints.maxTier = options.maxTier;
+    }
+    if (options.bump === true)
+        hints.bump = true;
+    const tier = classifyEffort(prompt, hints);
+    if (options.json === true) {
+        process.stdout.write(JSON.stringify({ tier, prompt }, null, 2) + "\n");
+        return;
+    }
+    console.log(chalk.bold(`\nEffort tier: ${chalk.cyan(tier)}`));
+    console.log(chalk.dim(`  prompt length: ${prompt.length} chars`));
+    console.log(chalk.dim(`  Tier ladder : ${EFFORT_ORDER.map((t) => (t === tier ? chalk.cyan(t.toUpperCase()) : t)).join(" → ")}`));
+    console.log(chalk.dim(`\nThe runtime can use this tier to map (provider, model). See effort-cascade.ts.`));
+});
 // ── Parse ───────────────────────────────────────────────────
 // Deep-link fast path — if the first positional arg is a `wotann://` URL,
 // parse it and dispatch via the deep-link handler BEFORE commander sees
@@ -8791,6 +9827,9 @@ snipCmd
     .command("list")
     .description("List saved snippets")
     .option("--cat <category>", "Filter by category")
+    .option("--tag <tag>", "Filter by tag")
+    .option("--source <source>", "Filter by imported corpus source")
+    .option("--limit <n>", "Maximum rows to print", "200")
     .option("--fav", "Only show favorites", false)
     .option("--search <query>", "Free-text search via FTS5")
     .action(async (opts) => {
@@ -8803,6 +9842,12 @@ snipCmd
         const filter = {};
         if (opts.cat)
             filter.category = opts.cat;
+        if (opts.tag)
+            filter.tag = opts.tag;
+        if (opts.source)
+            filter.source = opts.source;
+        if (opts.limit)
+            filter.limit = Number(opts.limit);
         if (opts.fav)
             filter.favOnly = true;
         if (opts.search)
@@ -8816,8 +9861,11 @@ snipCmd
             const star = s.isFavorite ? chalk.yellow("★ ") : "  ";
             const used = s.useCount > 0 ? chalk.dim(` (used ${s.useCount}×)`) : "";
             const cat = s.category ? chalk.dim(` [${s.category}]`) : "";
+            const source = s.source
+                ? chalk.dim(` <${s.source}${s.version ? `@${s.version}` : ""}>`)
+                : "";
             const vars = s.variables.length > 0 ? chalk.cyan(` {${s.variables.join(", ")}}`) : "";
-            process.stdout.write(`${star}${chalk.bold(s.title)}${cat}${vars}${used}\n`);
+            process.stdout.write(`${star}${chalk.bold(s.title)}${cat}${source}${vars}${used}\n`);
             process.stdout.write(chalk.dim(`  id: ${s.id}\n`));
         }
     }
@@ -8876,6 +9924,45 @@ snipCmd
         store.close();
     }
 });
+snipCmd
+    .command("import <path>")
+    .description("Import a JSON/YAML/Markdown prompt corpus into the shared snippet library")
+    .option("--source <name>", "Corpus source name")
+    .option("--version <version>", "Corpus version or release tag")
+    .option("--url <url>", "Source URL for provenance")
+    .option("--cat <category>", "Default category")
+    .option("--tags <csv>", "Default comma-separated tags")
+    .action(async (path, opts) => {
+    const { readFileSync } = await import("node:fs");
+    const { SnippetStore } = await import("./snippets/snippet-store.js");
+    const { parsePromptCorpusText } = await import("./snippets/prompt-corpus.js");
+    const { resolveWotannHomeSubdir } = await import("./utils/wotann-home.js");
+    const { join } = await import("node:path");
+    const text = readFileSync(path, "utf-8");
+    const corpus = parsePromptCorpusText(text, {
+        ...(opts.source ? { source: opts.source } : {}),
+        ...(opts.version ? { version: opts.version } : {}),
+        ...(opts.url ? { sourceUrl: opts.url } : {}),
+        ...(opts.cat ? { category: opts.cat } : {}),
+        ...(opts.tags
+            ? {
+                tags: opts.tags
+                    .split(",")
+                    .map((tag) => tag.trim())
+                    .filter((tag) => tag.length > 0),
+            }
+            : {}),
+    });
+    const dbPath = join(resolveWotannHomeSubdir(""), "snippets.db");
+    const store = new SnippetStore(dbPath);
+    try {
+        const result = store.importCorpus(corpus);
+        process.stdout.write(chalk.green(`✓ imported ${result.imported}, updated ${result.updated}, skipped ${result.skipped} from ${corpus.source}\n`));
+    }
+    finally {
+        store.close();
+    }
+});
 snipCmd
     .command("use <id>")
     .description("Render a snippet (with optional --var key=value overrides) to stdout")
@@ -8960,6 +10047,10 @@ snipCmd
             body: current.body,
             category: current.category,
             tags: current.tags,
+            source: current.source,
+            externalId: current.externalId,
+            sourceUrl: current.sourceUrl,
+            version: current.version,
             isFavorite: next,
         });
         process.stdout.write(chalk.green(`✓ ${next ? "favorited" : "unfavorited"} ${current.title}\n`));
@@ -9086,6 +10177,31 @@ toolsCmd
     if (!result.markdown.endsWith("\n"))
         process.stdout.write("\n");
 });
+toolsCmd
+    .command("ingest-capabilities")
+    .alias("markitdown-capabilities")
+    .description("Show runtime-probed document/image/audio ingestion support")
+    .option("--json", "Emit result as JSON", false)
+    .action(async (opts) => {
+    const { getMarkitdownCapabilities } = await import("./tools/markitdown-bridge.js");
+    const report = await getMarkitdownCapabilities();
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+        return;
+    }
+    process.stdout.write(chalk.bold("Ingestion capabilities\n"));
+    for (const capability of report.capabilities) {
+        const statusColor = capability.status === "available"
+            ? chalk.green
+            : capability.status === "requires_key"
+                ? chalk.yellow
+                : chalk.red;
+        process.stdout.write(`${statusColor(capability.status.padEnd(15))} ${capability.label} ${chalk.dim(capability.extensions.join(" "))}\n`);
+        process.stdout.write(`  ${chalk.dim(capability.converter)}\n`);
+        if (capability.notes)
+            process.stdout.write(`  ${chalk.dim(capability.notes)}\n`);
+    }
+});
 // ── Orphan-wires registrar (V9 follow-up) ─────────────────────
 // Mounts 14 previously-orphaned library modules under `wotann ow <verb>`
 // via a single `registerOrphanWires(program)` call. Each subcommand is a
@@ -9109,6 +10225,24 @@ catch (err) {
     if (isHelpOrVersion) {
         process.exit(typeof e.exitCode === "number" ? e.exitCode : 0);
     }
+    const message = typeof e.message === "string" ? e.message : "";
+    if (!code.startsWith("commander.") && message.length > 0) {
+        const lower = message.toLowerCase();
+        const daemonRelated = lower.includes("enoent") ||
+            lower.includes("econnrefused") ||
+            lower.includes("ipc") ||
+            lower.includes("socket") ||
+            lower.includes("daemon") ||
+            lower.includes("rpc timeout") ||
+            lower.includes("not connected");
+        if (daemonRelated) {
+            process.stderr.write(chalk.red(`KAIROS daemon is not reachable: ${message}\n`));
+            process.stderr.write(chalk.dim("Run `wotann daemon start` or `wotann engine start`, then retry.\n"));
+        }
+        else {
+            process.stderr.write(chalk.red(`${message}\n`));
+        }
+    }
     // Real usage failure (unknown command, missing arg, bad option). Commander
     // already wrote the error message to stderr via configureOutput.writeErr,
     // so we only need to set the exit code.