aiden-runtime 4.5.0 → 4.6.1

package/README.md

@@ -10,14 +10,15 @@
 
 Autonomous AI Engine — local-first, Windows-native, yours to own
 
-74 skills · 59 tools · 19 providers · 9 channels · AGPL-3.0
+74 skills · 60 tools · 19 providers · 9 channels · AGPL-3.0
 
 Windows · Linux · WSL · macOS (API Mode)
 ```
 
 <p align="center">
-  <a href="https://github.com/taracodlabs/aiden/releases/latest"><img src="https://img.shields.io/badge/version-v4.5.0-f97316?style=for-the-badge" alt="v4.5.0" /></a>
+  <a href="https://github.com/taracodlabs/aiden/releases/latest"><img src="https://img.shields.io/badge/version-v4.6.0-f97316?style=for-the-badge" alt="v4.6.0" /></a>
   <a href="https://www.npmjs.com/package/aiden-runtime"><img src="https://img.shields.io/npm/v/aiden-runtime?color=f97316&label=npm&style=for-the-badge" alt="npm" /></a>
+  <a href="https://www.npmjs.com/package/aiden-runtime"><img src="https://img.shields.io/npm/dm/aiden-runtime?color=f97316&label=downloads&style=for-the-badge" alt="npm downloads" /></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-orange?style=for-the-badge" alt="License: AGPL-3.0" /></a>
   <a href="https://discord.gg/gMZ3hUnQTm"><img src="https://img.shields.io/badge/chat-discord-7289da?logo=discord&logoColor=white&style=for-the-badge" alt="Discord" /></a>
   <a href="https://github.com/taracodlabs/aiden/stargazers"><img src="https://img.shields.io/github/stars/taracodlabs/aiden?style=for-the-badge&color=f9d71c" alt="Stars" /></a>
@@ -33,6 +34,20 @@ Windows · Linux · WSL · macOS (API Mode)
 
 ---
 
+## What's new in v4.6
+
+Aiden now spawns workers and learns from itself.
+
+- **Sub-agents.** `spawn_sub_agent` runs a focused child with an isolated context + intersected toolset; `subagent_fanout` runs N children in parallel (ensemble or partition) with merge strategies (`all` / `vote` / `pick-best` / `combine`) and provider rotation across configured fallback slots.
+- **Operator kill-switch.** `/spawn-pause on|off|status` blocks new sub-agent spawning while in-flight children continue. Marker file at `~/.aiden/spawn.paused` so the state survives restart and is shared across REPL, daemon, and MCP runtimes. Optional reason field captured in the typed `SUBAGENT_SPAWN_PAUSED` error envelope.
+- **Self-improvement loop foundation.** TCE classifications + recoveries persist to two new SQLite tables (`failure_signatures`, `recovery_reports`); `/recovery list|show|clear` surfaces recurring failure patterns across sessions.
+- **REPL parent-run lineage.** Each REPL turn writes its own `runs` row; sub-agent children link back via `spawned_from_run_id`. `aiden runs list` hides children by default and shows a `(N children, M OK)` badge per parent; `--include-children` flips to flat view.
+- **PlannerGuard opt-in.** The keyword-based per-turn tool narrower is OFF by default in v4.6 (modern models pick well from the full catalog). Enable via `/planner-guard on` or `AIDEN_PLANNER_GUARD=1` for smaller local models.
+
+Phase 2 also fixed an MCP-mode `subagent_fanout` regression that had silently broken in the v4.5 refactor.
+
+---
+
 ## What's new in v4.5
 
 Aiden now wakes up by itself.

package/dist/cli/v4/aidenCLI.js

@@ -97,6 +97,13 @@ const sessionManager_1 = require("../../core/v4/sessionManager");
 const toolRegistry_1 = require("../../core/v4/toolRegistry");
 const skillLoader_1 = require("../../core/v4/skillLoader");
 const index_1 = require("../../tools/v4/index");
+// v4.6 Phase 1 — spawn_sub_agent: always-on runStore + LLM-callable tool.
+const node_crypto_1 = require("node:crypto");
+const node_os_1 = __importDefault(require("node:os"));
+const daemonConfig_1 = require("../../core/v4/daemon/daemonConfig");
+const connection_1 = require("../../core/v4/daemon/db/connection");
+const runStore_1 = require("../../core/v4/daemon/runStore");
+const spawnSubAgentTool_1 = require("../../tools/v4/subagent/spawnSubAgentTool");
 const skillCommands_1 = require("../../core/v4/skillCommands");
 const aidenAgent_1 = require("../../core/v4/aidenAgent");
 const promptBuilder_1 = require("../../core/v4/promptBuilder");
@@ -502,6 +509,7 @@ async function main(argv, opts = {}) {
         .option('--source <src>', 'list: filter by trigger source (file/webhook/email/schedule/manual)')
         .option('--status <s>', 'list: filter by status (queued/running/completed/failed/cancelled/interrupted)')
         .option('--trigger <prefix>', 'list: sessionId prefix (e.g. "trigger:file:<id>:")')
+        .option('--include-children', 'list: include sub-agent children (default: top-level only, with per-parent badge)')
         .action(async (action, posArgs, cmdObj) => {
         const { runRunsSubcommand } = await Promise.resolve().then(() => __importStar(require('./commands/runs')));
         const code = await runRunsSubcommand(action, posArgs ?? [], cmdObj, {
@@ -623,6 +631,60 @@ async function main(argv, opts = {}) {
 async function buildAgentRuntime(cliOpts, opts) {
     const paths = opts.pathsOverride ?? (0, paths_1.resolveAidenPaths)();
     await (0, paths_1.ensureAidenDirsExist)(paths);
+    // ── v4.6 Phase 1 — always-on runStore for spawn_sub_agent ──────────────
+    //
+    // The spawn_sub_agent primitive persists each child run to the runs
+    // table via spawned_from_run_id FK. The REPL needs a runStore handle
+    // regardless of whether AIDEN_DAEMON=1 or not. SQLite WAL mode
+    // (enabled in openDaemonDb) allows REPL + daemon to coexist on the
+    // same file without lock contention. The connection.ts module caches
+    // per-path, so when daemon foundation has already opened the DB this
+    // call returns the same handle. Migration runner is idempotent on
+    // already-current schemas.
+    const replInstanceId = `repl-${(0, node_crypto_1.randomUUID)().slice(0, 8)}`;
+    const replDb = (0, connection_1.openDaemonDb)((0, daemonConfig_1.daemonDbPath)(paths.root));
+    // Seed the REPL's daemon_instances row so the FK on runs.instance_id
+    // is satisfied. Idempotent under INSERT OR IGNORE — multiple REPL
+    // launches reusing the same instance_id (rare with random UUID
+    // suffix) silently no-op.
+    replDb.prepare(`INSERT OR IGNORE INTO daemon_instances
+       (instance_id, pid, hostname, started_at, last_heartbeat, version)
+     VALUES (?, ?, ?, ?, ?, ?)`).run(replInstanceId, process.pid, node_os_1.default.hostname(), Date.now(), Date.now(), version_1.VERSION);
+    const replRunStore = (0, runStore_1.createRunStore)({ db: replDb });
+    // v4.6 Phase 3A — operator kill-switch for sub-agent spawning.
+    // Initialised as early as possible so any subsequent tool wiring
+    // sees the singleton. The marker file lives at
+    // `<paths.root>/spawn.paused` and is shared across REPL + daemon
+    // + MCP for cross-process coordination. The startup probe (warn
+    // operator that pause is active from a prior session) fires
+    // later, once `bootLogger` is available — see the
+    // `spawnPauseBootStatus` block below.
+    const { initSpawnPause } = await Promise.resolve().then(() => __importStar(require('../../core/v4/subagent/spawnPause')));
+    const spawnPauseState = initSpawnPause({ aidenHome: paths.root });
+    // v4.6 Phase 3b — self-improvement loop. Initialise the durable
+    // failure-ledger / recovery-report store against the same
+    // daemon.db handle the runStore uses. WAL coexistence: REPL +
+    // daemon + MCP all share the same connection-cached handle, so
+    // any writes from one runtime are visible to the others. The
+    // TCE write-through path inside the agent loop reads through the
+    // module-level singleton; initialising here makes spawnSubAgent
+    // and daemon-fired turns observe the same persistence.
+    const { initRecoveryStore } = await Promise.resolve().then(() => __importStar(require('../../core/v4/selfimprovement/recoveryStore')));
+    initRecoveryStore({ db: replDb });
+    const spawnPauseBootStatus = spawnPauseState.isPaused()
+        ? spawnPauseState.status()
+        : null;
+    // v4.6 Phase 2Q-B — mutable holder for the REPL's current parent
+    // run id. ChatSession's `runAgentTurn` writes a row before each
+    // turn dispatches and stores the id here (and clears it on
+    // completion). The spawn / fanout tool factories below read it
+    // through `resolveParentRunId` / `resolveParentSessionId`
+    // callbacks so any child spawned mid-turn is linked back to the
+    // live REPL parent row via `runs.spawned_from_run_id`.
+    const replParentRunRef = {
+        runId: null,
+        sessionId: null,
+    };
     // Phase 16c.2: load `paths.envFile` (the aiden-managed `.env` that
     // `setupWizard.ts::upsertEnvVar` writes to) into `process.env` BEFORE
     // any provider resolution. The bug: setup wrote keys to this file but
@@ -747,7 +809,28 @@ async function buildAgentRuntime(cliOpts, opts) {
                 process.stdout.write(`\n${(0, providerDetection_1.summarizeDetection)(detection)}\n`);
                 process.stdout.write('config.yaml is empty — let\'s pick a provider that matches.\n');
             }
-            process.stdout.write('Launching setup wizard…\n\n');
+            // ONB1-WIRE — disclaimer + loading screens land BEFORE the wizard.
+            // Only inside this TTY-guarded branch (the non-TTY branch at the
+            // outer else already bails into explore mode). The detection
+            // summary above gives the user context for what was found; the
+            // disclaimer then asks for explicit consent before we walk them
+            // through setup. Declining exits 0 — the user chose not to
+            // continue, that's not an error.
+            //
+            // Lazy-required so the test harness paths that stub the wizard
+            // don't pay the load cost.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { showDisclaimer } = require('./onboarding/disclaimer');
+            const disc = await showDisclaimer();
+            if (!disc.ok) {
+                // User typed 'n' / 'no'. The disclaimer already printed the
+                // friendly goodbye line; just exit cleanly.
+                process.exit(0);
+            }
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { runLoadingSequence, defaultLoadingSteps } = require('./onboarding/loading');
+            await runLoadingSequence(defaultLoadingSteps(paths));
+            process.stdout.write('\n');
             const result = await (0, setupWizard_1.runSetupWizard)({ paths });
             // Phase 30.2.1: three exit states.
             if (result.status === 'exited') {
@@ -1238,7 +1321,11 @@ async function buildAgentRuntime(cliOpts, opts) {
     // ── Build agent with all moat layers attached ────────────────────────
     const agent = new aidenAgent_1.AidenAgent({
         provider: adapter,
-        tools: toolRegistry.getSchemas(),
+        // v4.6 Phase 1 — 'repl' context filter excludes tools tagged
+        // daemon-only (none today) and INCLUDES tools tagged repl-only
+        // (e.g. spawn_sub_agent, registered after this line). Tools with
+        // no `contexts` field default to visible in both contexts.
+        tools: toolRegistry.getSchemas(undefined, 'repl'),
         toolExecutor,
         maxTurns: config.getValue('agent.max_turns', 90),
         auxiliaryClient,
@@ -1426,6 +1513,21 @@ async function buildAgentRuntime(cliOpts, opts) {
     // Wire the gateway singleton's logger BEFORE registering its processor
     // so register / unregister channel events are scoped correctly.
     gateway_1.gateway.attachLogger(bootLogger.child('gateway'));
+    // v4.6 Phase 3A — startup probe for the spawn-pause kill-switch.
+    // The state was initialised early (line ~740) before tool wiring.
+    // Now that bootLogger exists, emit a visible warning so an
+    // operator who forgot they paused in a prior session learns
+    // immediately rather than puzzling at silent rejected fanouts.
+    if (spawnPauseBootStatus) {
+        const s = spawnPauseBootStatus;
+        const reasonSuffix = s.reason ? ` (reason: ${s.reason})` : '';
+        bootLogger.warn(`spawn_sub_agent / subagent_fanout are PAUSED${reasonSuffix}. ` +
+            'Run /spawn-pause off to resume.', {
+            pausedAt: s.pausedAt ?? null,
+            pausedBy: s.pausedBy ?? null,
+            durationMs: s.durationMs ?? null,
+        });
+    }
     // ── Phase v4.1-subagent.1 — replace subagent_fanout stub with wired version
     //
     // tools/v4/index.ts registers a stub at boot so the schema is visible
@@ -1442,10 +1544,45 @@ async function buildAgentRuntime(cliOpts, opts) {
     // shared subsystems (registry, skillLoader, paths, memoryManager,
     // promptBuilder, promptBuilderOptions) are read-only and pass by
     // reference.
+    // v4.6 Phase 2Q-A — `runFanout` routes each child through
+    // `spawnSubAgent`. `spawnDeps` mirrors the deps the
+    // `makeSpawnSubAgentTool` factory accepts (see registration below
+    // this block). The legacy per-call `runChild` closure that lived
+    // here pre-2R has been deleted; the primitive owns child
+    // construction now.
     toolRegistry.register((0, index_1.makeSubagentFanoutTool)({
         logger: bootLogger.child('subagent'),
         resolveActiveModel: () => ({ providerId, modelId }),
         aggregatorAdapter: adapter,
+        spawnDeps: {
+            toolRegistry,
+            parentToolContext: {
+                cwd: process.cwd(),
+                paths,
+                sessions: sessionManager,
+                memory: memoryManager,
+                memoryGuard,
+                ssrfProtection,
+                tirithScanner,
+                skillLoader,
+            },
+            parentProvider: adapter,
+            parentProviderId: providerId,
+            parentModelId: modelId,
+            resolveVerifiedFlag,
+            resolveToolset,
+            resolveMutates,
+            runStore: replRunStore,
+            instanceId: replInstanceId,
+            logger: bootLogger.child('subagent'),
+        },
+        // v4.6 Phase 2Q-B — REPL parent-run wiring. Reads the shared
+        // `replParentRunRef` mutated by `ChatSession.runAgentTurn` so
+        // fanout children get `spawned_from_run_id` populated. Returns
+        // undefined between turns (ref cleared post-turn), matching the
+        // pre-2Q-B behaviour for slash-command-triggered spawns.
+        resolveParentRunId: () => replParentRunRef.runId ?? undefined,
+        resolveParentSessionId: () => replParentRunRef.sessionId ?? undefined,
         resolveProviders: () => {
             // When the parent uses FallbackAdapter, expose every key-present
             // slot's (providerId, modelId) so rotation can spread children
@@ -1466,110 +1603,68 @@ async function buildAgentRuntime(cliOpts, opts) {
             }
             return [{ providerId, modelId }];
         },
-        runChild: async (childOpts) => {
-            // Per-child context: paths / skillLoader / memoryManager / processes
-            // are SAFE to share (read-only or per-call by design). The approval
-            // engine is intentionally OMITTED — N children competing for one
-            // stdin REPL would deadlock.
-            const childCtx = {
-                cwd: process.cwd(),
-                paths,
-                sessions: sessionManager,
-                memory: memoryManager,
-                skillLoader,
-                // approvalEngine, ssrfProtection, tirithScanner, memoryGuard:
-                // SSRF + Tirith would be safe to share but adding them now
-                // expands the per-child surface; keep lean for v4.1-subagent.1
-                // and revisit when fanout actually exercises network or shell
-                // tools (gated by ALLOW_DESTRUCTIVE).
-            };
-            // Filter the tool surface. Default-safe: read-only tools only.
-            // AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE=1 mirrors the MCP env from
-            // v4.1-mcp — predictable, env-driven.
-            const allowDestructive = process.env.AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE === '1' ||
-                process.env.AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE === 'true';
-            const childToolNames = [];
-            for (const name of toolRegistry.list()) {
-                const h = toolRegistry.get(name);
-                if (!h)
-                    continue;
-                if (h.mutates && !allowDestructive)
-                    continue;
-                // Avoid recursive fanout this phase — children cannot spawn
-                // their own children. Recursion was capped at depth 1 by
-                // default in prior multi-agent systems for the same reason;
-                // v3 starved nested spawns.
-                if (name === 'subagent_fanout')
-                    continue;
-                childToolNames.push(name);
-            }
-            const childExecutor = toolRegistry.buildExecutor(childCtx);
-            const childTools = childToolNames
-                .map((n) => toolRegistry.get(n)?.schema)
-                .filter((s) => !!s);
-            // Provider isolation: clone the FallbackAdapter so per-child
-            // rate-limit state doesn't pollute the parent or siblings.
-            // Non-Fallback adapters are stateless by spec (providers/v4/
-            // types.ts:190) so direct reuse is safe.
-            const childProvider = adapter instanceof providerFallback_1.FallbackAdapter
-                ? adapter.clone()
-                : adapter;
-            // Build per-child AidenAgent. Skip the moat layers (PlannerGuard,
-            // HonestyEnforcement, SkillTeacher, SkillEnforcementTracker) —
-            // they're parent-loop concerns and add cost without value at the
-            // child scale. Skip promptBuilder too: children get a SHORT
-            // system prompt (brief identity + role) instead of the parent's
-            // full SOUL.md + 72-skills inventory + memory snapshot. The
-            // tradeoff is deliberate — children answer the GOAL, not "be
-            // Aiden". With the full prompt, trivial queries take 30s+ for
-            // children to generate verbose self-introductions; the lean
-            // child prompt brings n=2 trivial fanouts under 12s. Parent
-            // should pass any context children genuinely need via the
-            // `query` / `tasks[].context` argument.
-            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 — childSystemPrompt prepended manually below.
-                // No fallback strategy — child failures bubble up to the
-                // orchestrator, which surfaces them in the result envelope.
-            });
-            // Honour the abort signal — if the parent aborts mid-call (or the
-            // per-child timeout fires), short-circuit before dispatching to
-            // the provider. AidenAgent doesn't take an AbortSignal directly;
-            // the AbortController plumbing through fetch is the
-            // v4.1-subagent.2 / v4.2 hardening pass. Pre-check here for the
-            // synchronous path.
-            if (childOpts.signal.aborted) {
-                throw new Error('aborted before dispatch');
-            }
-            // Brief, role-aware system prompt — drops 5KB+ of Aiden identity
-            // boilerplate that would otherwise inflate every child to 30s+
-            // wall-clock for a trivial query. The parent agent retains the
-            // full prompt when it's the orchestrator; children answer the
-            // goal directly.
-            const roleLine = childOpts.role
-                ? `Role: ${childOpts.role}. `
-                : '';
-            const childSystemPrompt = `You are one of ${childOpts.index >= 0 ? '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;
-        },
     }));
     bootLogger.child('subagent').info('subagent_fanout: wired (replaces stub)', {
         providerId,
         modelId,
         fallback: adapter instanceof providerFallback_1.FallbackAdapter ? 'FallbackAdapter' : 'direct',
     });
+    // ── v4.6 Phase 1 — register spawn_sub_agent (REPL only) ────────────────
+    //
+    // The new single-child synchronous primitive. Coexists with
+    // subagent_fanout (Q9 — additive in Phase 1; Phase 2 will refactor
+    // fanout to call this primitive N times).
+    //
+    // Wired here, AFTER `agent` and `toolExecutor` are in scope, because
+    // the child builder needs the parent agent's reference (to read
+    // `getCurrentSignal()` at dispatch time per the agent-instance signal
+    // pattern) and the parent's tool context for ssrf/tirith/memory/etc.
+    //
+    // Deliberately NOT registered in cli/v4/daemonAgentBuilder.ts —
+    // daemon-fired agents don't expose spawn_sub_agent in their tool
+    // catalog (Q6 lock).
+    toolRegistry.register((0, spawnSubAgentTool_1.makeSpawnSubAgentTool)({
+        parentAgent: agent,
+        toolRegistry,
+        parentToolContext: {
+            cwd: process.cwd(),
+            paths,
+            sessions: sessionManager,
+            memory: memoryManager,
+            memoryGuard,
+            // approvalEngine intentionally OMITTED — the child builder
+            // constructs its own auto-deny ApprovalEngine. Listing it here
+            // would be ignored (childBuilder overrides via spread), but
+            // keeping it out makes the intent explicit.
+            ssrfProtection,
+            tirithScanner,
+            skillLoader,
+        },
+        parentProvider: adapter,
+        parentProviderId: providerId,
+        parentModelId: modelId,
+        resolveVerifiedFlag,
+        resolveToolset,
+        resolveMutates,
+        runStore: replRunStore,
+        instanceId: replInstanceId,
+        // v4.6 Phase 2Q-B — REPL parent-run wiring. Reads the same
+        // shared `replParentRunRef` the fanout factory above uses;
+        // ChatSession.runAgentTurn populates it before each turn
+        // dispatches. Returns undefined between turns so spawns from
+        // slash-command handlers stay top-level (consistent with
+        // pre-2Q-B observable behaviour).
+        resolveParentRunId: () => replParentRunRef.runId ?? undefined,
+        resolveParentSessionId: () => replParentRunRef.sessionId ?? undefined,
+        // v4.6 Phase 1 observability — info-level traces for spec at
+        // invocation, child-tools count, completion, and per-tool-call
+        // run_events on the child's runs row.
+        logger: bootLogger.child('subagent'),
+    }));
+    bootLogger.child('subagent').info('spawn_sub_agent: wired (REPL only)', {
+        instanceId: replInstanceId,
+        dbPath: (0, daemonConfig_1.daemonDbPath)(paths.root),
+    });
     // ── Phase v4.1-2.1: gateway message processor ────────────────────
     //
     // Channel adapters call `gateway.routeMessage(...)` for every inbound
@@ -1762,6 +1857,10 @@ async function buildAgentRuntime(cliOpts, opts) {
         exploreMode,
         channelManager,
         daemonAgentBuilder,
+        // v4.6 Phase 2Q-B — REPL parent-run wiring.
+        replRunStore,
+        replInstanceId,
+        replParentRunRef,
     };
 }
 async function runInteractiveChat(cliOpts, opts) {
@@ -1828,6 +1927,14 @@ async function runInteractiveChat(cliOpts, opts) {
         // when /quit fires the auto-summary path.
         memoryManager: runtime.memoryManager,
         memoryGuard: runtime.memoryGuard,
+        // v4.6 Phase 2Q-B — REPL parent-run wiring. ChatSession.runAgentTurn
+        // writes a runs row per turn and stores its id into
+        // `replParentRunRef`; the spawn / fanout factories above read the
+        // ref via their `resolveParentRunId` / `resolveParentSessionId`
+        // callbacks so children get `spawned_from_run_id` populated.
+        replRunStore: runtime.replRunStore,
+        replInstanceId: runtime.replInstanceId,
+        replParentRunRef: runtime.replParentRunRef,
     };
     if (cliOpts.tui) {
         await (0, aidenTUI_1.runTuiMode)({

package/dist/cli/v4/chatSession.js

@@ -922,6 +922,43 @@ class ChatSession {
         const baseHistory = newHistory.length > 0
             ? [...this.history, ...newHistory, userMsg]
             : [...this.history, userMsg];
+        // v4.6 Phase 2Q-B — REPL parent-run row (best-effort).
+        //
+        // Insert a `runs` row tagged with this REPL session BEFORE the
+        // agent loop dispatches. Capture the row id into the shared
+        // `replParentRunRef` so any `spawn_sub_agent` / `subagent_fanout`
+        // child this turn produces can link back via
+        // `spawned_from_run_id`. The ref is cleared in the catch /
+        // success paths below regardless of outcome.
+        //
+        // Defensive: a runStore write failure (locked DB, schema drift,
+        // etc.) must NOT crash the REPL — every persistence call here is
+        // wrapped in try/catch and reduces to a logged warning. The
+        // user-facing turn still runs.
+        let replRunId = null;
+        const replRunStore = this.opts.replRunStore;
+        const replInstanceId = this.opts.replInstanceId;
+        const replParentRunRef = this.opts.replParentRunRef;
+        if (replRunStore && replInstanceId && this.sessionId) {
+            try {
+                replRunId = replRunStore.create({
+                    sessionId: this.sessionId,
+                    instanceId: replInstanceId,
+                    status: 'running',
+                    startedAt: turnStartedAt,
+                });
+                if (replParentRunRef) {
+                    replParentRunRef.runId = replRunId;
+                    replParentRunRef.sessionId = this.sessionId;
+                }
+            }
+            catch (err) {
+                // Logged once per turn; the user's chat is not interrupted.
+                // eslint-disable-next-line no-console
+                console.warn('[runs] failed to write REPL parent-run row:', err instanceof Error ? err.message : String(err));
+                replRunId = null;
+            }
+        }
         // Phase 16c: streaming gated on display.streaming config.
         // v4.1.4 Part 1.6: PRODUCTION DEFAULT FLIPPED FROM FALSE TO TRUE.
         // Streaming delivers the activity indicator, tool-row live tick,
@@ -1179,6 +1216,35 @@ class ChatSession {
             this.history = result.messages;
             this.totalUsage.inputTokens += result.totalUsage.inputTokens;
             this.totalUsage.outputTokens += result.totalUsage.outputTokens;
+            // v4.6 Phase 2Q-B — finalize the REPL parent-run row on success.
+            // `finishReason` from the agent loop maps directly into our DB
+            // status: `stop` → completed; `interrupted` / `tool_loop` →
+            // surface as 'interrupted' so it's visible in `runs list`;
+            // `budget_exhausted` / `error` → failed. Wrapped in try/catch
+            // so even a runStore write failure here can't crash the REPL.
+            if (replRunStore && replRunId !== null) {
+                try {
+                    const dbStatus = result.finishReason === 'stop' ? 'completed' :
+                        result.finishReason === 'interrupted' ? 'interrupted' :
+                            result.finishReason === 'tool_loop' ? 'interrupted' :
+                                'failed';
+                    replRunStore.setStatus(replRunId, dbStatus, {
+                        finishReason: result.finishReason,
+                        completedAt: Date.now(),
+                    });
+                }
+                catch (err) {
+                    // eslint-disable-next-line no-console
+                    console.warn('[runs] failed to finalize REPL parent-run row:', err instanceof Error ? err.message : String(err));
+                }
+            }
+            // Clear the shared ref so a subsequent turn (or stray
+            // spawn/fanout dispatched between turns from a slash command
+            // handler) doesn't see a stale parent id.
+            if (replParentRunRef) {
+                replParentRunRef.runId = null;
+                replParentRunRef.sessionId = null;
+            }
             // Phase 16d: surface inline confirmations for verified memory writes.
             // We MUST gate on verified=true (the post-write read flag from
             // MemoryGuard) — HonestyEnforcement uses the same flag to catch
@@ -1289,6 +1355,26 @@ class ChatSession {
             progressBar?.hide();
             if (streamingActive)
                 this.opts.display.streamComplete();
+            // v4.6 Phase 2Q-B — finalize REPL parent-run row on error.
+            // Visible in `aiden runs list` as a failed top-level row so
+            // operators can correlate a chat error with whatever children
+            // it had already kicked off this turn.
+            if (replRunStore && replRunId !== null) {
+                try {
+                    replRunStore.setStatus(replRunId, 'failed', {
+                        finishReason: 'error',
+                        completedAt: Date.now(),
+                    });
+                }
+                catch (e2) {
+                    // eslint-disable-next-line no-console
+                    console.warn('[runs] failed to mark REPL parent-run failed:', e2 instanceof Error ? e2.message : String(e2));
+                }
+            }
+            if (replParentRunRef) {
+                replParentRunRef.runId = null;
+                replParentRunRef.sessionId = null;
+            }
             const msg = err?.message ?? String(err);
             // v4.1.3-prebump: classify the error so the suggestion below
             // points at the actual fix instead of the generic "/model or
@@ -1418,6 +1504,27 @@ class ChatSession {
             providerOk: !this.opts.unconfigured,
             version: version_1.VERSION,
         }) + '\n');
+        // v4.6 Phase 3A — operator kill-switch indicator. Lands ABOVE
+        // the blank-line + provider-source annotation so an operator
+        // who paused in a prior session sees the state immediately on
+        // boot, alongside the standard status pills. Single dim
+        // warning line; no special chrome — the message itself is the
+        // visual signal.
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { getSpawnPause } = require('../../core/v4/subagent/spawnPause');
+            const s = getSpawnPause().status();
+            if (s.paused) {
+                const reasonSuffix = s.reason ? ` · ${s.reason}` : '';
+                const durationSuffix = typeof s.durationMs === 'number'
+                    ? ` · ${formatDuration(s.durationMs)}`
+                    : '';
+                display.warn(`spawn-pause: ON${reasonSuffix}${durationSuffix} — use /spawn-pause off to resume`);
+            }
+        }
+        catch {
+            // Singleton not initialised (test stubs, etc.) — silently skip.
+        }
         // v4.5 TUI polish — blank line so the status pills row doesn't
         // crowd the muted source annotation right beneath it.
         display.write('\n');
@@ -1493,6 +1600,19 @@ class ChatSession {
             await this.maybeShowBootUpdatePrompt();
         }
         catch { /* never let the update prompt crash boot */ }
+        // ONB1 slice 9 — one-time first-run hint banner. Renders below
+        // the boot card on the very first session after a successful
+        // setup; dismissed when the user sends their first message or
+        // runs /dismiss. Lazy-required so test-harness sessions that
+        // omit `paths` don't pay the fs cost.
+        try {
+            if (this.opts.paths) {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const { renderFirstRunHint } = require('./repl/firstRunHint');
+                await renderFirstRunHint({ paths: this.opts.paths, out: process.stdout });
+            }
+        }
+        catch { /* never let a missing marker crash boot */ }
         // Bottom prompt hint — final line of the boot card.
         display.write('\n');
         display.write(display.bottomPromptHint() + '\n');

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

@@ -31,12 +31,14 @@ const LABEL = {
     tce: 'TCE',
     browser_depth: 'Browser depth',
     suggestions: 'Suggestions',
+    planner_guard: 'Planner-Guard',
 };
 const CONFIG_DOTTED = {
     sandbox: 'runtime_toggles.sandbox',
     tce: 'runtime_toggles.tce',
     browser_depth: 'runtime_toggles.browser_depth',
     suggestions: 'runtime_toggles.suggestions',
+    planner_guard: 'runtime_toggles.planner_guard',
 };
 /**
  * Apply a toggle change. When `ctx.config` is wired, persists to