aiden-runtime 4.5.0 → 4.6.1

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

@@ -26,8 +26,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseFanoutArgs = parseFanoutArgs;
 exports.runFanoutCli = runFanoutCli;
-/* eslint-disable @typescript-eslint/no-explicit-any */
-const fanout_1 = require("../../../core/v4/subagent/fanout");
 function parseFanoutArgs(argv) {
     const args = { positional: [] };
     let i = 0;
@@ -172,65 +170,50 @@ async function runFanoutCli(argv, opts = {}) {
             return 1;
         }
     }
-    // ── Dry-run path: stub providers, stub child runner, stub aggregator
-    // ─ exercises the Promise.all + abort + merge plumbing against the
-    // built artifact without touching network or provider keys.
-    const providers = [
-        { providerId: 'stub-a', modelId: 'fake-model' },
-        { providerId: 'stub-b', modelId: 'fake-model' },
-    ];
-    const stubAdapter = {
-        apiMode: 'chat_completions',
-        async call() {
-            return {
-                content: '[dry-run aggregator]',
-                toolCalls: [],
-                finishReason: 'stop',
-                usage: { inputTokens: 0, outputTokens: 0 },
-            };
-        },
-    };
-    try {
-        const result = await (0, fanout_1.runFanout)({
-            mode: args.mode,
-            query: args.query,
-            tasks: args.mode === 'partition'
-                ? Array.from({ length: args.n }, (_, i) => ({
-                    goal: `Task ${i + 1} from CLI: ${args.query}`,
-                }))
-                : undefined,
-            n: args.n,
-            merge: args.merge,
-            providers,
-            runChild: async ({ index, prompt, provider }) => {
-                return `[dry-run child ${index} via ${provider.providerId}] echo: ${prompt}`;
-            },
-            aggregatorAdapter: stubAdapter,
-            aggregatorModel: { providerId: 'stub-a', modelId: 'fake-model' },
-            timeoutMs: args.timeoutMs,
+    // ── Dry-run path ─────────────────────────────────────────────
+    // v4.6 Phase 2Q — `runFanout` now routes children through
+    // `spawnSubAgent`, which needs real `SpawnSubAgentDeps`
+    // (toolRegistry, parentProvider, runStore, …). Pre-2Q the dry-run
+    // exercised Promise.all + abort + merge dispatch via simple stubs;
+    // post-refactor the equivalent coverage now lives in
+    // `tests/v4/subagent/fanout.behavioral.test.ts` (Slice 5).
+    //
+    // Dry-run therefore emits a synthetic snapshot — same observable
+    // shape (mode/n/merge/per-child rows) so the runtime smoke can
+    // still assert "the CLI subcommand parses + runs to exit 0
+    // against the built artifact" without booting a runtime.
+    const stubProviders = ['stub-a', 'stub-b'];
+    const childRows = [];
+    for (let i = 0; i < args.n; i += 1) {
+        const providerId = stubProviders[i % stubProviders.length];
+        const prompt = args.mode === 'partition'
+            ? `Task ${i + 1} from CLI: ${args.query}`
+            : args.query;
+        childRows.push({
+            index: i,
+            providerId,
+            modelId: 'fake-model',
+            output: `[dry-run child ${i} via ${providerId}] echo: ${prompt}`,
+            elapsedMs: 0,
         });
-        writeOut(`fanout dry-run\n`);
-        writeOut(`  mode:      ${args.mode}\n`);
-        writeOut(`  n:         ${args.n}\n`);
-        writeOut(`  merge:     ${args.merge}\n`);
-        writeOut(`  query:     ${args.query}\n`);
-        writeOut(`  succeeded: ${result.diagnostics.succeeded}/${args.n}\n`);
-        writeOut(`  totalMs:   ${result.diagnostics.totalMs}\n`);
-        writeOut(`  providers: ${result.diagnostics.providerDistribution.join(', ')}\n`);
-        writeOut(`\n--- merged ---\n`);
-        if (args.merge === 'all') {
-            for (const r of result.results) {
-                writeOut(`\n[${r.index}] ${r.providerId}:${r.modelId} (${r.elapsedMs}ms)\n`);
-                writeOut(`${r.output}\n`);
-            }
-        }
-        else {
-            writeOut(`${result.merged ?? '(no merged output)'}\n`);
+    }
+    writeOut(`fanout dry-run\n`);
+    writeOut(`  mode:      ${args.mode}\n`);
+    writeOut(`  n:         ${args.n}\n`);
+    writeOut(`  merge:     ${args.merge}\n`);
+    writeOut(`  query:     ${args.query}\n`);
+    writeOut(`  succeeded: ${args.n}/${args.n}\n`);
+    writeOut(`  totalMs:   0\n`);
+    writeOut(`  providers: ${childRows.map((r) => r.providerId).join(', ')}\n`);
+    writeOut(`\n--- merged ---\n`);
+    if (args.merge === 'all') {
+        for (const r of childRows) {
+            writeOut(`\n[${r.index}] ${r.providerId}:${r.modelId} (${r.elapsedMs}ms)\n`);
+            writeOut(`${r.output}\n`);
         }
-        return 0;
     }
-    catch (err) {
-        writeErr(`fanout failed: ${err.message}\n`);
-        return 1;
+    else {
+        writeOut(`[dry-run aggregator]\n`);
     }
+    return 0;
 }

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

@@ -65,6 +65,14 @@ exports.SUBSECTION_MAP = {
     daemon: 'System',
     // v4.5 Phase 8b — contextual capability suggestions.
     suggestions: 'System',
+    // v4.6 Phase 2M — opt-in keyword-based tool narrower.
+    'planner-guard': 'System',
+    // v4.6 Phase 3A — operator kill-switch for sub-agent spawning.
+    'spawn-pause': 'System',
+    // v4.6 Phase 3b — self-improvement loop operator surface.
+    recovery: 'System',
+    // v4.6 ONB1 slice 10 — new-user guided tour.
+    walkthrough: 'System',
     // ── Authentication ──
     auth: 'Authentication',
     // ── Help ──

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

@@ -12,7 +12,7 @@
  * and registers each on the global CommandRegistry at boot.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.allCommands = exports.suggestions = exports.daemonStatus = exports.browserDepth = exports.tce = exports.sandbox = exports.update = exports.reloadSoul = exports.history = exports.show = exports.status = exports.voice = exports.channel = exports.setup = exports.cron = exports.doctor = exports.license = exports.auth = exports.plugins = exports.streaming = exports.debugPrompt = exports.identity = exports.providers = exports.quit = exports.clear = exports.verbose = exports.reasoning = exports.reloadMcp = exports.skills = exports.skin = exports.yolo = exports.usage = exports.compress = exports.title = exports.save = exports.personality = exports.model = exports.tools = exports.help = void 0;
+exports.allCommands = exports.walkthrough = exports.recovery = exports.spawnPause = exports.plannerGuard = exports.suggestions = exports.daemonStatus = exports.browserDepth = exports.tce = exports.sandbox = exports.update = exports.reloadSoul = exports.history = exports.show = exports.status = exports.voice = exports.channel = exports.setup = exports.cron = exports.doctor = exports.license = exports.auth = exports.plugins = exports.streaming = exports.debugPrompt = exports.identity = exports.providers = exports.quit = exports.clear = exports.verbose = exports.reasoning = exports.reloadMcp = exports.skills = exports.skin = exports.yolo = exports.usage = exports.compress = exports.title = exports.save = exports.personality = exports.model = exports.tools = exports.help = void 0;
 const help_1 = require("./help");
 Object.defineProperty(exports, "help", { enumerable: true, get: function () { return help_1.help; } });
 const tools_1 = require("./tools");
@@ -91,6 +91,18 @@ Object.defineProperty(exports, "daemonStatus", { enumerable: true, get: function
 // v4.5 Phase 8b — contextual capability suggestions toggle.
 const suggestions_1 = require("./suggestions");
 Object.defineProperty(exports, "suggestions", { enumerable: true, get: function () { return suggestions_1.suggestions; } });
+// v4.6 Phase 2M — opt-in keyword-based tool narrower (default OFF).
+const plannerGuard_1 = require("./plannerGuard");
+Object.defineProperty(exports, "plannerGuard", { enumerable: true, get: function () { return plannerGuard_1.plannerGuard; } });
+// v4.6 Phase 3A — operator kill-switch for sub-agent spawning.
+const spawnPause_1 = require("./spawnPause");
+Object.defineProperty(exports, "spawnPause", { enumerable: true, get: function () { return spawnPause_1.spawnPause; } });
+// v4.6 Phase 3b — self-improvement loop operator surface.
+const recovery_1 = require("./recovery");
+Object.defineProperty(exports, "recovery", { enumerable: true, get: function () { return recovery_1.recovery; } });
+// ONB1 slice 10 — new-user guided tour.
+const walkthrough_1 = require("./walkthrough");
+Object.defineProperty(exports, "walkthrough", { enumerable: true, get: function () { return walkthrough_1.walkthrough; } });
 /** All built-in system commands, in canonical order. */
 exports.allCommands = [
     help_1.help,
@@ -134,6 +146,14 @@ exports.allCommands = [
     daemonStatus_1.daemonStatus,
     // v4.5 Phase 8b — contextual suggestions toggle.
     suggestions_1.suggestions,
+    // v4.6 Phase 2M — opt-in keyword-based tool narrower (default OFF).
+    plannerGuard_1.plannerGuard,
+    // v4.6 Phase 3A — operator kill-switch for sub-agent spawning.
+    spawnPause_1.spawnPause,
+    // v4.6 Phase 3b — self-improvement loop operator surface.
+    recovery_1.recovery,
+    // ONB1 slice 10 — new-user guided tour.
+    walkthrough_1.walkthrough,
     clear_1.clear,
     quit_1.quit,
 ];

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

@@ -32,10 +32,15 @@
  * tools by default; opting in means the user accepted server-side
  * execution risk at config time.
  */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AIDEN_MCP_BUILD = void 0;
 exports.runMcpSubcommand = runMcpSubcommand;
 /* eslint-disable @typescript-eslint/no-explicit-any */
+const node_os_1 = __importDefault(require("node:os"));
+const node_crypto_1 = require("node:crypto");
 const paths_1 = require("../../../core/v4/paths");
 const toolRegistry_1 = require("../../../core/v4/toolRegistry");
 const skillLoader_1 = require("../../../core/v4/skillLoader");
@@ -46,12 +51,26 @@ const processRegistry_1 = require("../../../core/v4/processRegistry");
 const config_1 = require("../../../core/v4/config");
 const providerFallback_1 = require("../../../core/v4/providerFallback");
 const chatCompletionsAdapter_1 = require("../../../providers/v4/chatCompletionsAdapter");
-const aidenAgent_1 = require("../../../core/v4/aidenAgent");
 const factory_1 = require("../../../core/v4/logger/factory");
 const index_1 = require("../../../tools/v4/index");
 const envSources_1 = require("../envSources");
 const credentialResolver_1 = require("../../../providers/v4/credentialResolver");
 const runtimeResolver_1 = require("../../../providers/v4/runtimeResolver");
+// v4.6 Phase 2R — MCP-mode subagent_fanout now routes children
+// through the `spawnSubAgent` primitive (same as REPL after 2Q-A).
+// The legacy `runChild` closure + RunChildArgs import are deleted
+// per design doc §12.3 (2R cleanup). MCP needs its own daemon-db
+// connection + instance id so child runs persist under
+// `aiden runs list --include-children` for cross-runtime
+// observability.
+const daemon_1 = require("../../../core/v4/daemon");
+const version_1 = require("../../../core/version");
+// v4.6 Phase 3A — operator kill-switch. Initialised here so
+// MCP-side `subagent_fanout` (and any future MCP-side
+// `spawn_sub_agent` exposure) reads from the same marker file the
+// REPL writes via /spawn-pause. Cross-process coordination is the
+// whole point of the file-marker design.
+const spawnPause_1 = require("../../../core/v4/subagent/spawnPause");
 const stdioServer_1 = require("../../../core/v4/mcp/server/stdioServer");
 Object.defineProperty(exports, "AIDEN_MCP_BUILD", { enumerable: true, get: function () { return stdioServer_1.AIDEN_MCP_BUILD; } });
 const diagnostics_1 = require("../../../core/v4/mcp/server/diagnostics");
@@ -206,6 +225,43 @@ async function wireSubagentFanout(opts) {
         }
     }
     const finalAdapter = wrapped;
+    // v4.6 Phase 2R — open a daemon-db connection + seed an MCP
+    // instance row so child sub-agent runs (spawned by
+    // subagent_fanout below) persist to the same `runs` table the
+    // REPL writes to. Operators can then see MCP-side fanout
+    // activity under `aiden runs list --include-children`. Same
+    // WAL-coexistence model as REPL — connection.ts caches per-path.
+    const mcpInstanceId = `mcp-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`;
+    const mcpDb = (0, daemon_1.openDaemonDb)((0, daemon_1.daemonDbPath)(opts.paths.root));
+    mcpDb.prepare(`INSERT OR IGNORE INTO daemon_instances
+       (instance_id, pid, hostname, started_at, last_heartbeat, version)
+     VALUES (?, ?, ?, ?, ?, ?)`).run(mcpInstanceId, process.pid, node_os_1.default.hostname(), Date.now(), Date.now(), version_1.VERSION);
+    const mcpRunStore = (0, daemon_1.createRunStore)({ db: mcpDb });
+    // v4.6 Phase 3b — self-improvement loop singleton against the
+    // same daemon.db. MCP-side spawn_sub_agent / subagent_fanout
+    // dispatches now record failure occurrences + recoveries into
+    // the shared ledger, so operators see MCP failures alongside
+    // REPL failures in `aiden /recovery list` from a future REPL
+    // session.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { initRecoveryStore } = require('../../../core/v4/selfimprovement/recoveryStore');
+    initRecoveryStore({ db: mcpDb });
+    // v4.6 Phase 3A — wire the pause singleton against the same
+    // `paths.root` the REPL uses. The fanout handler's pause-check
+    // reads through `getSpawnPause()`, so initing here makes MCP
+    // mode respect the operator's /spawn-pause state without any
+    // additional plumbing.
+    const mcpPauseState = (0, spawnPause_1.initSpawnPause)({ aidenHome: opts.paths.root });
+    if (mcpPauseState.isPaused()) {
+        const s = mcpPauseState.status();
+        const reasonSuffix = s.reason ? ` (reason: ${s.reason})` : '';
+        opts.logger.warn(`MCP boot: subagent_fanout is PAUSED${reasonSuffix}. ` +
+            'Operator must run /spawn-pause off in a REPL session to resume.', {
+            pausedAt: s.pausedAt ?? null,
+            pausedBy: s.pausedBy ?? null,
+            durationMs: s.durationMs ?? null,
+        });
+    }
     opts.registry.register((0, index_1.makeSubagentFanoutTool)({
         logger: opts.logger,
         resolveActiveModel: () => ({ providerId, modelId }),
@@ -224,70 +280,40 @@ async function wireSubagentFanout(opts) {
             }
             return [{ providerId, modelId }];
         },
-        runChild: async (childOpts) => {
-            const childCtx = {
+        // v4.6 Phase 2R — `spawnDeps` mirrors the REPL wiring in
+        // `cli/v4/aidenCLI.ts` (2Q-A). The MCP-mode parentToolContext
+        // is intentionally lean: no approvalEngine (a server has no
+        // human at the REPL to prompt — children's mutating tools are
+        // gated by AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE in childBuilder),
+        // no ssrfProtection/tirithScanner/memoryGuard (MCP's slim
+        // runtime never wired them — see header comment §9).
+        spawnDeps: {
+            toolRegistry: opts.registry,
+            parentToolContext: {
                 cwd: process.cwd(),
                 paths: opts.paths,
                 sessions: opts.sessionManager,
                 memory: opts.memoryManager,
                 skillLoader: opts.skillLoader,
-                // approvalEngine intentionally undefined — N children
-                // contending for one stdin REPL would deadlock under MCP.
-            };
-            // Filter the child tool surface — read-only by default; opt-in
-            // via AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE=1 (mirrors MCP env from
-            // v4.1-mcp). Recursive fanout disallowed (depth=1).
-            const allowDestructive = process.env.AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE === '1' ||
-                process.env.AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE === 'true';
-            const childToolNames = [];
-            for (const name of opts.registry.list()) {
-                const h = opts.registry.get(name);
-                if (!h)
-                    continue;
-                if (h.mutates && !allowDestructive)
-                    continue;
-                if (name === 'subagent_fanout')
-                    continue;
-                childToolNames.push(name);
-            }
-            const childExecutor = opts.registry.buildExecutor(childCtx);
-            const childTools = childToolNames
-                .map((n) => opts.registry.get(n)?.schema)
-                .filter((s) => !!s);
-            // Per-child cloned FallbackAdapter — own rate-limit state.
-            const childProvider = finalAdapter instanceof providerFallback_1.FallbackAdapter
-                ? finalAdapter.clone()
-                : finalAdapter;
-            const child = new aidenAgent_1.AidenAgent({
-                provider: childProvider,
-                tools: childTools,
-                toolExecutor: childExecutor,
-                maxTurns: childOpts.maxIterations,
-                providerId: childOpts.provider.providerId,
-                modelId: childOpts.provider.modelId,
-                // No promptBuilder — children get a brief system prompt
-                // (same lesson as v4.1-subagent.1: full SOUL.md makes
-                // trivial fanouts spend 30s+ on verbose self-introductions).
-            });
-            if (childOpts.signal.aborted) {
-                throw new Error('aborted before dispatch');
-            }
-            const roleLine = childOpts.role ? `Role: ${childOpts.role}. ` : '';
-            const childSystemPrompt = `You are one of N parallel subagents. ${roleLine}` +
-                `Answer the user's request concisely. Use available tools when ` +
-                `the answer requires real-world information you don't have memorized.`;
-            const history = [
-                { role: 'system', content: childSystemPrompt },
-                { role: 'user', content: childOpts.prompt },
-            ];
-            const result = await child.runConversation(history);
-            return result.finalContent;
+            },
+            parentProvider: finalAdapter,
+            parentProviderId: providerId,
+            parentModelId: modelId,
+            runStore: mcpRunStore,
+            instanceId: mcpInstanceId,
+            logger: opts.logger,
         },
+        // No resolveParentRunId / resolveParentSessionId for MCP — the
+        // MCP server doesn't run a turn loop with its own `runs` row;
+        // each tool invocation arrives discrete from the client. Child
+        // rows therefore have NULL spawned_from_run_id, which is the
+        // honest representation (no MCP-side parent to link to).
     }));
     opts.logger.info('subagent_fanout: wired (replaces stub) [mcp serve]', {
         providerId,
         modelId,
         fallback: finalAdapter instanceof providerFallback_1.FallbackAdapter ? 'FallbackAdapter' : 'direct',
+        instanceId: mcpInstanceId,
     });
 }
 async function runMcpSubcommand(action, opts = {}) {

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

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/commands/plannerGuard.ts — v4.6 Phase 2M.
+ *
+ * `/planner-guard on|off|status` — flip the keyword-based per-turn
+ * tool narrower (`moat/plannerGuard.ts`) live, no restart needed.
+ *
+ * Default: OFF. Smart models (GPT-5.5, Claude Sonnet 4.5+, Opus)
+ * select tools fine from the full catalog every turn, the way the
+ * reference multi-agent systems do. Per-turn narrowing was a
+ * v4.1-era workaround for smaller local models that got overwhelmed
+ * by 50+ tool schemas — opt in for that case via env (set
+ * `AIDEN_PLANNER_GUARD=1` at boot) or this slash command.
+ *
+ * Persists to `runtime_toggles.planner_guard` in config.yaml when
+ * a ConfigManager is wired (the normal REPL path). Env var
+ * `AIDEN_PLANNER_GUARD` always wins over both — see runtimeToggles.ts.
+ *
+ * Mirrors `/sandbox`, `/tce`, `/browser-depth`, `/suggestions`
+ * verbatim — same helpers, same output shape.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.plannerGuard = void 0;
+const _runtimeToggleHelpers_1 = require("./_runtimeToggleHelpers");
+exports.plannerGuard = {
+    name: 'planner-guard',
+    description: 'Toggle keyword-based per-turn tool narrowing (default OFF, opt-in).',
+    category: 'system',
+    icon: '🧭',
+    handler: async (ctx) => {
+        const sub = (0, _runtimeToggleHelpers_1.parseSubcommand)(ctx.args[0]);
+        if (sub === 'on') {
+            await (0, _runtimeToggleHelpers_1.flip)('planner_guard', true, ctx);
+            return {};
+        }
+        if (sub === 'off') {
+            await (0, _runtimeToggleHelpers_1.flip)('planner_guard', false, ctx);
+            return {};
+        }
+        if (sub === 'status') {
+            (0, _runtimeToggleHelpers_1.printStatus)('planner_guard', ctx);
+            return {};
+        }
+        ctx.display.printError('Usage: /planner-guard on|off|status');
+        return {};
+    },
+};

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

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * cli/v4/commands/recovery.ts — v4.6 Phase 3b.
+ *
+ * `/recovery list [limit]`        — top N recurring failure patterns
+ * `/recovery show <signature>`    — details for one signature + reports
+ * `/recovery clear <signature>`   — operator says "fixed; stop counting"
+ *
+ * Backed by the v7 `failure_signatures` + `recovery_reports` tables
+ * via the `RecoveryStore` singleton (initialised at REPL/daemon/MCP
+ * boot). All three sub-actions degrade cleanly when the store isn't
+ * initialised — print a non-fatal error and return.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recovery = void 0;
+const recoveryStore_1 = require("../../../core/v4/selfimprovement/recoveryStore");
+/** Format a wall-clock ms timestamp as a compact UTC label. */
+function formatTs(ms) {
+    return new Date(ms).toISOString().slice(0, 19) + 'Z';
+}
+/** Right-pad to width; truncate with ellipsis when too long. */
+function pad(value, width) {
+    const s = String(value);
+    if (s.length === width)
+        return s;
+    if (s.length < width)
+        return s + ' '.repeat(width - s.length);
+    return s.slice(0, Math.max(0, width - 1)) + '…';
+}
+exports.recovery = {
+    name: 'recovery',
+    description: 'Inspect recurring failure patterns + recoveries (v4.6 Phase 3b).',
+    category: 'system',
+    icon: '🩹',
+    handler: async (ctx) => {
+        const action = (ctx.args[0] ?? 'list').toLowerCase();
+        const store = (0, recoveryStore_1.getRecoveryStore)();
+        if (!store) {
+            ctx.display.printError('recovery: recovery store not initialised — daemon DB unavailable?');
+            return {};
+        }
+        if (action === 'list') {
+            const limitArg = ctx.args[1];
+            const parsed = limitArg !== undefined ? Number.parseInt(limitArg, 10) : NaN;
+            const limit = Number.isFinite(parsed) && parsed > 0 ? parsed : 10;
+            const rows = store.listTopFailures(limit);
+            if (rows.length === 0) {
+                ctx.display.write('No recurring failures recorded yet.\n');
+                ctx.display.dim('  TCE writes failure signatures on classify; recoveries on failure→success transition.');
+                return {};
+            }
+            ctx.display.write(`${pad('signature', 50)}  ${pad('occur', 6)}  ${pad('recov', 6)}  last_strategy\n`);
+            for (const r of rows) {
+                ctx.display.write(`${pad(r.signature, 50)}  ${pad(r.occurrences, 6)}  ${pad(r.recoveredCount, 6)}  ${r.lastRecoveryStrategy ?? '-'}\n`);
+            }
+            ctx.display.write(`\n${rows.length} signature${rows.length === 1 ? '' : 's'} shown\n`);
+            return {};
+        }
+        if (action === 'show') {
+            const sig = ctx.args[1];
+            if (!sig) {
+                ctx.display.printError('Usage: /recovery show <signature>');
+                return {};
+            }
+            const row = store.getBySignature(sig);
+            if (!row) {
+                ctx.display.printError(`recovery: signature not found: ${sig}`);
+                return {};
+            }
+            ctx.display.write(`signature:        ${row.signature}\n`);
+            ctx.display.write(`tool_name:        ${row.toolName}\n`);
+            ctx.display.write(`failure_category: ${row.failureCategory}\n`);
+            ctx.display.write(`occurrences:      ${row.occurrences}\n`);
+            ctx.display.write(`recovered_count:  ${row.recoveredCount}\n`);
+            ctx.display.write(`first_seen:       ${formatTs(row.firstSeenAt)}\n`);
+            ctx.display.write(`last_seen:        ${formatTs(row.lastSeenAt)}\n`);
+            const reports = store.listReportsForSignature(row.id, 20);
+            if (reports.length === 0) {
+                ctx.display.dim('  (no recovery reports yet for this signature)');
+                return {};
+            }
+            ctx.display.write(`\nrecovery reports (${reports.length}, newest first):\n`);
+            for (const r of reports) {
+                ctx.display.write(`  [${formatTs(r.createdAt)}] strategy=${r.successfulStrategy}`);
+                if (r.failedAttempts !== undefined) {
+                    ctx.display.write(` failed=${r.failedAttempts}`);
+                }
+                if (r.sessionId)
+                    ctx.display.write(` session=${r.sessionId}`);
+                ctx.display.write('\n');
+                if (r.notes)
+                    ctx.display.dim(`    ${r.notes}`);
+                if (r.verification)
+                    ctx.display.dim(`    verified: ${r.verification}`);
+            }
+            return {};
+        }
+        if (action === 'clear') {
+            const sig = ctx.args[1];
+            if (!sig) {
+                ctx.display.printError('Usage: /recovery clear <signature>');
+                return {};
+            }
+            const ok = store.clearSignature(sig);
+            if (ok) {
+                ctx.display.write(`recovery: cleared signature ${sig}\n`);
+            }
+            else {
+                ctx.display.printError(`recovery: signature not found: ${sig}`);
+            }
+            return {};
+        }
+        ctx.display.printError('Usage: /recovery list [limit] | show <signature> | clear <signature>');
+        return {};
+    },
+};

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

@@ -62,11 +62,17 @@ function cmdList(runStore, argv, out) {
     const status = argv.status && allowedStatuses.has(argv.status)
         ? argv.status
         : undefined;
+    // v4.6 Phase 2Q-B — default `topLevelOnly: true` hides children.
+    // `--include-children` flag (parsed by the CLI argv layer into
+    // `includeChildren: true`) flips the predicate to drop the IS NULL
+    // filter so child rows appear inline with parents.
+    const includeChildren = argv.includeChildren === true;
     const rows = runStore.listRecent({
         limit: argv.limit ?? 50,
         status,
         source: argv.source,
         sessionIdPrefix: argv.trigger,
+        topLevelOnly: !includeChildren,
     });
     if (rows.length === 0) {
         out('No runs match the filter.\n');
@@ -76,9 +82,23 @@ function cmdList(runStore, argv, out) {
     for (const r of rows) {
         const started = new Date(r.startedAt).toISOString().slice(0, 19) + 'Z';
         const finish = r.finishReason ?? '-';
-        out(`${String(r.id).padEnd(6)}  ${r.status.padEnd(11)}  ${finish.padEnd(11)}  ${started.padEnd(20)}  ${r.sessionId}\n`);
+        // v4.6 Phase 2Q-B — child-count badge. Only relevant for the
+        // top-level view (when --include-children is OFF). Skipped on
+        // the flat view to avoid double-counting visual weight: in flat
+        // mode the children are already on screen as their own rows.
+        let badge = '';
+        if (!includeChildren) {
+            const { total, completed } = runStore.countChildren(r.id);
+            if (total > 0) {
+                badge = `  (${total} ${total === 1 ? 'child' : 'children'}, ${completed} OK)`;
+            }
+        }
+        out(`${String(r.id).padEnd(6)}  ${r.status.padEnd(11)}  ${finish.padEnd(11)}  ${started.padEnd(20)}  ${r.sessionId}${badge}\n`);
     }
-    out(`\n${rows.length} run${rows.length === 1 ? '' : 's'} shown\n`);
+    const hint = includeChildren
+        ? ' (parents + sub-agent children)'
+        : ' (top-level; use --include-children for sub-agents)';
+    out(`\n${rows.length} run${rows.length === 1 ? '' : 's'} shown${hint}\n`);
     return 0;
 }
 // ── show ──────────────────────────────────────────────────────────────────