aiden-runtime 4.1.5 → 4.6.0

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");
@@ -207,7 +214,35 @@ function buildAgentFallbackSlots(primaryAdapter, primaryProviderId, primaryModel
     // same Groq account at slots 0 and 1).
     return [primarySlot, ...defaults];
 }
+/**
+ * Commander 5.x option-value collector. Use with `.option('--flag <v>',
+ * '...', collectArray, [])` so repeated `--flag a --flag b` produces
+ * `['a','b']` instead of `'b'`. Commander 5 does NOT support the
+ * `<x...>` variadic syntax on options (only positional args).
+ */
+function collectArray(value, previous) {
+    if (!Array.isArray(previous))
+        return [value];
+    return previous.concat([value]);
+}
 async function main(argv, opts = {}) {
+    // v4.5 Phase 1 — daemon foundation bootstrap is deferred until the
+    // REPL action handler fires (see the default `.action()` below).
+    // Subcommands like `trigger add`, `trigger list`, `config get`,
+    // `--version`, `--help`, `doctor`, etc. do NOT need the daemon
+    // foundation. Booting it for every CLI invocation:
+    //   1. Wastes work (HTTP server up + tear down for a one-shot
+    //      DB-write subcommand).
+    //   2. Creates phantom "crash recovery" warnings: the daemon-
+    //      foundation install/teardown cycle for each subcommand
+    //      doesn't shut down gracefully (process.exit happens after
+    //      the action), so the NEXT invocation's evaluateBootState
+    //      sees a stale daemon_instances row with a missed heartbeat
+    //      and writes a crash_reports row.
+    //   3. Adds latency on cold paths (CLI feels slow when AIDEN_DAEMON=1).
+    // The interactive REPL action calls `bootstrapDaemon()` explicitly,
+    // which is the only entry point that genuinely benefits from the
+    // foundation (long-running session = useful daemon).
     const program = new commander_1.Command();
     program
         .name('aiden')
@@ -234,6 +269,36 @@ async function main(argv, opts = {}) {
             process.stderr.write(`Run 'aiden --help' for available commands.\n`);
             process.exit(2);
         }
+        // v4.5 Phase 1 — daemon foundation bootstrap. Lazy-imported so
+        // the daemon module's side-effect cost stays at zero when
+        // AIDEN_DAEMON is off (better-sqlite3 native binding, chokidar,
+        // express, etc. all stay unloaded). Only fires for the REPL
+        // path — subcommands (trigger add/list/show/remove/enable/
+        // disable/test, config, --version, --help, doctor, …) do NOT
+        // touch the daemon foundation.
+        // v4.5 Phase 7c — two-phase bootstrap. The daemon FOUNDATION
+        // (file watchers, webhook routes, email triggers, cron
+        // emitter, dispatcher with placeholder runner, HTTP server)
+        // comes up HERE — before buildAgentRuntime, before the setup
+        // wizard. This restores the pre-7b guarantee that daemon
+        // foundation boots regardless of REPL configuration state
+        // (matters for systemd/launchd units booted on fresh machines
+        // and for any environment without a provider configured yet).
+        //
+        // The REAL agent runner gets installed later inside
+        // runInteractiveChat() once buildAgentRuntime returns — see
+        // `installDaemonAgentBuilder` call there.
+        try {
+            if (process.env.AIDEN_DAEMON === '1') {
+                const { bootstrapDaemonFoundation } = await Promise.resolve().then(() => __importStar(require('../../core/v4/daemon/bootstrap')));
+                bootstrapDaemonFoundation();
+            }
+        }
+        catch (e) {
+            // Fail-loud but non-fatal — daemon foundation init failure
+            // must not block the user from opening a REPL.
+            console.error('[daemon] foundation bootstrap failed: ' + (e instanceof Error ? e.message : String(e)));
+        }
         // Tier-3.1: surface --no-ui as an env var so downstream modules
         // (which import uiBuild.ts) see the flag without threading it
         // through every call site.
@@ -318,6 +383,140 @@ async function main(argv, opts = {}) {
         }
         await runSkillsSubcommand(action, arg, opts);
     });
+    // v4.5 Phase 2 — file watcher trigger management.
+    program
+        .command('trigger <action> [args...]')
+        .description('Manage daemon triggers. Actions: add, list, show, remove, enable, disable, test.')
+        // Commander 5.x stores option values directly on the Command
+        // instance, so `--name` would clobber Command.prototype.name().
+        // Use `--label` instead; we map to the internal `name` arg below.
+        .option('--label <label>', 'Trigger label/name (for add).')
+        // Commander 5.x does NOT support `<x...>` variadic syntax on
+        // OPTIONS (only on positional args) — repeating overwrites
+        // instead of appending. Use an explicit collector so multiple
+        // --path / --include / --exclude / --event flags accumulate.
+        .option('--path <path>', 'Path to watch (for add file). Repeatable.', collectArray, [])
+        .option('--include <glob>', 'Include glob pattern. Repeatable.', collectArray, [])
+        .option('--exclude <glob>', 'Exclude glob pattern. Repeatable.', collectArray, [])
+        .option('--event <type>', 'Event type: add|change|unlink. Repeatable.', collectArray, [])
+        .option('--debounce-ms <n>', 'Per-path debounce in ms (default 750).', (v) => Number.parseInt(v, 10))
+        .option('--settle-ms <n>', 'Stable-stat settle in ms (default 1000).', (v) => Number.parseInt(v, 10))
+        .option('--max-settle-ms <n>', 'Max settle time before giving up (default 30000).', (v) => Number.parseInt(v, 10))
+        .option('--max-queue-depth <n>', 'Max per-watcher queue depth (default 100).', (v) => Number.parseInt(v, 10))
+        .option('--no-ignore-temp', 'Disable default ignore for editor temps + .git + node_modules.')
+        .option('--content-hash', 'Compute sha256 per change (opt-in; slower).')
+        .option('--reconcile <policy>', 'skip_existing | process_new_since_last_seen | full_rescan (default skip_existing).')
+        .option('--polling', 'Force polling mode (network FS / WSL bind mount).')
+        .option('--prompt-template <text>', 'Phase 5 — agent prompt template.')
+        .option('--disabled', 'Create trigger in disabled state.')
+        // v4.5 Phase 3 — webhook-specific options.
+        .option('--hmac <format>', 'Webhook HMAC format: github | gitlab | generic (default generic).')
+        .option('--secret <s>', 'Webhook secret. Auto-generated when omitted.')
+        .option('--rate-limit <n>', 'Webhook requests/min (default 30).', (v) => Number.parseInt(v, 10))
+        .option('--max-body-bytes <n>', 'Webhook max body cap (default 1048576).', (v) => Number.parseInt(v, 10))
+        .option('--idempotency-ttl-ms <n>', 'Webhook idempotency TTL (default 3600000).', (v) => Number.parseInt(v, 10))
+        .option('--deliver-only', 'Phase 3 stub: accept + log; Phase 5 will dispatch via channel.')
+        // v4.5 Phase 4a — email IMAP options.
+        .option('--host <host>', 'IMAP host (for add email).')
+        .option('--port <n>', 'IMAP port (default 993).', (v) => Number.parseInt(v, 10))
+        .option('--user <addr>', 'IMAP user / email address (for add email).')
+        .option('--password <pwd>', 'IMAP password (for add email).')
+        .option('--no-tls', 'Disable TLS (for add email; default is TLS on).')
+        .option('--mailbox <name>', 'IMAP mailbox (default INBOX).')
+        .option('--poll-ms <n>', 'Email poll interval ms (default 15000).', (v) => Number.parseInt(v, 10))
+        .option('--allow-sender <addr-or-glob>', 'Allowed sender pattern (repeatable, REQUIRED for email).', collectArray, [])
+        .option('--allow-subject <regex>', 'Allowed subject regex (repeatable).', collectArray, [])
+        .option('--attachment-policy <policy>', 'skip | inline-text | save-to-tmp (default skip).')
+        .option('--no-validate', 'Skip IMAP pre-flight connectivity check.')
+        .action(async (action, posArgs, cmd) => {
+        const { runTriggerSubcommand } = await Promise.resolve().then(() => __importStar(require('./commands/trigger')));
+        const cliOpts = cmd.opts();
+        const argv = {
+            name: cliOpts.label,
+            paths: cliOpts.path,
+            include: cliOpts.include,
+            exclude: cliOpts.exclude,
+            events: cliOpts.event,
+            debounceMs: cliOpts.debounceMs,
+            settleMs: cliOpts.settleMs,
+            maxSettleMs: cliOpts.maxSettleMs,
+            maxQueueDepth: cliOpts.maxQueueDepth,
+            noIgnoreTemp: cliOpts.ignoreTemp === false,
+            contentHash: cliOpts.contentHash === true,
+            reconcile: cliOpts.reconcile,
+            polling: cliOpts.polling === true,
+            promptTemplate: cliOpts.promptTemplate,
+            disabled: cliOpts.disabled === true,
+            // v4.5 Phase 3 — webhook options.
+            hmac: cliOpts.hmac,
+            secret: cliOpts.secret,
+            rateLimit: cliOpts.rateLimit,
+            maxBodyBytes: cliOpts.maxBodyBytes,
+            idempotencyTtlMs: cliOpts.idempotencyTtlMs,
+            deliverOnly: cliOpts.deliverOnly === true,
+            // v4.5 Phase 4a — email options.
+            host: cliOpts.host,
+            port: cliOpts.port,
+            user: cliOpts.user,
+            password: cliOpts.password,
+            noTls: cliOpts.tls === false,
+            mailbox: cliOpts.mailbox,
+            pollMs: cliOpts.pollMs,
+            allowSenders: cliOpts.allowSender ?? [],
+            allowSubjects: cliOpts.allowSubject ?? [],
+            attachmentPolicy: cliOpts.attachmentPolicy,
+            noValidate: cliOpts.validate === false,
+        };
+        const code = await runTriggerSubcommand(action, posArgs ?? [], argv, {
+            writeOut: opts.writeOut,
+        });
+        process.exit(code);
+    });
+    // v4.5 Phase 4b — daemon supervisor commands.
+    program
+        .command('daemon <action> [args...]')
+        .description('Manage the v4.5 daemon. Actions: install, uninstall, start, stop, restart, status, logs.')
+        .action(async (action, posArgs) => {
+        const { runDaemonSubcommand } = await Promise.resolve().then(() => __importStar(require('./commands/daemon')));
+        const code = await runDaemonSubcommand(action, posArgs ?? [], {
+            writeOut: opts.writeOut,
+        });
+        process.exit(code);
+    });
+    // v4.5 Phase 6 — `aiden cron` top-level surface (mirrors slash command).
+    program
+        .command('cron <action> [args...]')
+        .description('Scheduled jobs. Actions: add, list, show, remove, enable, disable, run, logs.')
+        .option('--label <name>', 'job label (alphanumeric/dash/underscore)')
+        .option('--schedule <expr>', 'cron expr ("0 9 * * *") / interval ("every 5m") / ISO timestamp')
+        .option('--command <cmd>', 'shell command to run')
+        .option('--timezone <tz>', 'IANA timezone (default UTC)')
+        .option('--misfire-policy <policy>', 'skip_stale | run_once_if_late | catch_up_with_limit | manual_review')
+        .option('--prompt-template <tpl>', 'render template instead of running raw command (daemon mode)')
+        .option('--deliver-only', 'daemon skips the agent loop on fire')
+        .action(async (action, posArgs, cmdObj) => {
+        const { runCronSubcommand } = await Promise.resolve().then(() => __importStar(require('./commands/cron')));
+        const code = await runCronSubcommand(action, posArgs ?? [], cmdObj, {
+            writeOut: opts.writeOut,
+        });
+        process.exit(code);
+    });
+    // v4.5 Phase 6 — `aiden runs` surface (daemon run history).
+    program
+        .command('runs <action> [args...]')
+        .description('Daemon runs. Actions: list, show <id>, interrupt <id>, stats.')
+        .option('--limit <n>', 'list: max rows (default 50)', (v) => Number.parseInt(v, 10))
+        .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, {
+            writeOut: opts.writeOut,
+        });
+        process.exit(code);
+    });
     program
         .command('mcp <action>')
         .description('MCP server mode (Phase v4.1-mcp). Actions: serve, status, tools.')
@@ -432,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
@@ -475,6 +728,21 @@ async function buildAgentRuntime(cliOpts, opts) {
     }
     const config = new config_1.ConfigManager(paths);
     await config.load();
+    // v4.5 Phase 8a — initialise the runtimeToggles singleton with a
+    // ConfigManager seam so /sandbox /tce /browser-depth flips persist
+    // to config.yaml. Core modules (sandboxConfig, turnState,
+    // browserState) consult this singleton; precedence is
+    // env > config.yaml > default per Q-P8a-1(a).
+    {
+        const { initRuntimeToggles } = await Promise.resolve().then(() => __importStar(require('../../core/v4/runtimeToggles')));
+        initRuntimeToggles({
+            configRead: (key) => config.getValue(key),
+            configWriteAndSave: async (key, value) => {
+                config.set(key, value);
+                await config.save();
+            },
+        });
+    }
     // Phase 30.2 — fresh-user UX. Detection extends the old
     // `isFreshInstall`-only gate so we cover three new failure modes:
     //   1. fresh user with no env / no OAuth / no config → wizard fires
@@ -504,42 +772,63 @@ async function buildAgentRuntime(cliOpts, opts) {
     // consumed when building the adapter.
     let exploreMode = false;
     if (wizardNeeded) {
-        if (!detection.hasAnyProvider) {
-            // Truly empty: no env, no OAuth, no Ollama, no inline config.
-            process.stdout.write(`\n${(0, providerDetection_1.summarizeDetection)(detection)}\n`);
-        }
-        else if (configuredProviderBroken) {
-            // Config points at a provider we can't credential-resolve.
-            process.stdout.write(`\nConfigured provider '${detection.configProvider}' has no usable credentials ` +
-                `at ${node_path_1.default.join(paths.root, 'auth', `${detection.configProvider}.json`)}.\n`);
-        }
-        else {
-            // Detected something (env / oauth / ollama) but config.yaml is
-            // missing or empty — DEFAULT_CONFIG would route to anthropic and
-            // the resolver would fail. Surface the detection so the user
-            // sees what we found, then walk them through proper setup.
-            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');
-        const result = await (0, setupWizard_1.runSetupWizard)({ paths });
-        // Phase 30.2.1: three exit states.
-        if (result.status === 'exited') {
-            // Recovery option [5] — clean exit, no REPL.
-            process.exit(0);
-        }
-        if (result.status === 'skipped') {
-            // Recovery option [4] "explore mode" OR Ctrl+C cancellation.
-            // Boot continues into the REPL with a NullAdapter; chat is
-            // intercepted by ChatSession, slash commands work normally.
-            // Flagged here and consumed below where the adapter is built.
+        // v4.5 Phase 7c — TTY guard. The wizard uses inquirer prompts
+        // which block on stdin. When stdin is NOT a TTY (systemd unit
+        // start, launchd run, piped invocation, CI), there's no user
+        // to answer, so the wizard would hang forever — which in turn
+        // blocks the rest of buildAgentRuntime AND any post-build
+        // daemon wiring. Bail into exploreMode instead so the REPL
+        // boots with a NullAdapter; the daemon foundation (started at
+        // top of REPL action handler) keeps serving trigger rails with
+        // the placeholder runner. The operator runs `aiden` interactively
+        // once to finish configuration; from then on the real-agent
+        // runner installs on every subsequent boot.
+        if (!process.stdin.isTTY) {
+            process.stderr.write('[setup] stdin is not a TTY — skipping interactive wizard. ' +
+                'Booting in explore mode with NullAdapter. ' +
+                'Run `aiden` from a terminal once to configure a provider.\n');
             exploreMode = true;
+            // Skip the wizard block entirely; fall through to adapter
+            // build with exploreMode=true so a NullAdapter is used.
         }
-        // 'configured' (or 'skipped' — we still want the env/.env reload
-        // for slash commands like /providers that read fresh state) →
-        // re-load both so the resolver sees what the wizard wrote.
-        (0, envSources_1.loadAidenEnvFile)(paths.envFile);
-        await config.load();
+        else {
+            if (!detection.hasAnyProvider) {
+                // Truly empty: no env, no OAuth, no Ollama, no inline config.
+                process.stdout.write(`\n${(0, providerDetection_1.summarizeDetection)(detection)}\n`);
+            }
+            else if (configuredProviderBroken) {
+                // Config points at a provider we can't credential-resolve.
+                process.stdout.write(`\nConfigured provider '${detection.configProvider}' has no usable credentials ` +
+                    `at ${node_path_1.default.join(paths.root, 'auth', `${detection.configProvider}.json`)}.\n`);
+            }
+            else {
+                // Detected something (env / oauth / ollama) but config.yaml is
+                // missing or empty — DEFAULT_CONFIG would route to anthropic and
+                // the resolver would fail. Surface the detection so the user
+                // sees what we found, then walk them through proper setup.
+                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');
+            const result = await (0, setupWizard_1.runSetupWizard)({ paths });
+            // Phase 30.2.1: three exit states.
+            if (result.status === 'exited') {
+                // Recovery option [5] — clean exit, no REPL.
+                process.exit(0);
+            }
+            if (result.status === 'skipped') {
+                // Recovery option [4] "explore mode" OR Ctrl+C cancellation.
+                // Boot continues into the REPL with a NullAdapter; chat is
+                // intercepted by ChatSession, slash commands work normally.
+                // Flagged here and consumed below where the adapter is built.
+                exploreMode = true;
+            }
+            // 'configured' (or 'skipped' — we still want the env/.env reload
+            // for slash commands like /providers that read fresh state) →
+            // re-load both so the resolver sees what the wizard wrote.
+            (0, envSources_1.loadAidenEnvFile)(paths.envFile);
+            await config.load();
+        } // end of TTY branch
     }
     // Phase v4.1.2-bug1: boot model selection now consults the priority-
     // list auto-picker (cli/v4/providerBootSelector.ts) instead of
@@ -726,35 +1015,28 @@ async function buildAgentRuntime(cliOpts, opts) {
         else
             display.dim(ln.text);
     }
+    // v4.5 TUI polish — blank line so the plugin boot card breathes
+    // before the AIDEN banner stamps in below.
+    display.write('\n');
     // Phase 16g: surface the SOUL.md upgrade notice once on boot (only
     // when set — for users with edited SOUL.md that would have been
     // silently overwritten by the upgrade).
     if (soulNotice) {
         display.dim(`[soul] ${soulNotice}`);
     }
-    // Phase 20 Task 5: non-blocking npm update check. Fires on a separate
-    // microtask so REPL boot is unaffected. The cache hit path is sub-ms;
-    // the cache miss path is bounded by REGISTRY_TIMEOUT_MS (4 s) and runs
-    // after the prompt is already up. Honors AIDEN_NO_UPDATE_CHECK=1.
+    // v4.5 update system — the old setImmediate dim/warn one-liner
+    // here was superseded by the interactive boot prompt rendered
+    // later inside `chatSession.run()::maybeShowBootUpdatePrompt`.
+    // Single surface for update notification: the boxed prompt.
+    // Pre-warm the registry probe so the cache is fresh by the time
+    // the prompt asks — same non-blocking pattern, same opt-out
+    // semantics, no user-visible output from this call.
     setImmediate(async () => {
         try {
-            const { checkForUpdate, formatUpdateLine } = await Promise.resolve().then(() => __importStar(require('../../core/v4/update/checkUpdate')));
+            const { checkForUpdate } = await Promise.resolve().then(() => __importStar(require('../../core/v4/update/checkUpdate')));
             // eslint-disable-next-line @typescript-eslint/no-var-requires
             const pkg = require('../../package.json');
-            const status = await checkForUpdate({
-                paths,
-                installedVersion: pkg.version,
-            });
-            const line = formatUpdateLine(status);
-            if (line) {
-                // Phase 20 Task 6: louder surfacing on first-ever boot when the
-                // installed package is already behind. Subsequent boots stay
-                // low-key (dim) — users have seen the line before.
-                if (status.firstRun && status.updateAvailable)
-                    display.warn(line);
-                else
-                    display.dim(line);
-            }
+            await checkForUpdate({ paths, installedVersion: pkg.version });
         }
         catch {
             /* silent — update check is best-effort */
@@ -902,6 +1184,11 @@ async function buildAgentRuntime(cliOpts, opts) {
     const recallSessionHealth = new subsystemHealth_1.SubsystemHealthTracker('recall-session');
     subsystemHealthRegistry.register('recall-session', () => recallSessionHealth.snapshot());
     const skillTeacher = new skillTeacher_1.SkillTeacher(skillLoader, skillManageProxy, skillTeacherTier, undefined, (name) => toolRegistry.get(name), skillTeacherHealth);
+    // v4.1.6 Polish 2 — late-wire the SkillTeacher reference so the
+    // post-render `handleSkillProposal` flow can persist accepted
+    // proposals. CliCallbacks was constructed earlier (line ~906) —
+    // before SkillTeacher existed — so we set it now.
+    callbacks.setSkillTeacher(skillTeacher);
     // ── Tool executor with full Phase 9 + 10 context ─────────────────────
     const toolExecutor = toolRegistry.buildExecutor({
         cwd: process.cwd(),
@@ -921,6 +1208,14 @@ async function buildAgentRuntime(cliOpts, opts) {
         return typeof v === 'boolean' ? v : undefined;
     };
     const resolveToolset = (name) => toolRegistry.get(name)?.toolset;
+    // v4.2 Phase 4 — checkpoint/restore mutability resolver. The agent's
+    // Phase 4 hook calls this before dispatching each tool to decide
+    // whether to flag the live checkpoint as having mutated state. Same
+    // registry source as resolveToolset; closure captures the live
+    // registry reference so newly-registered tools are seen. Unknown
+    // tools return undefined → agent treats them as non-mutating (no
+    // checkpoint flag); plugin authors must declare `mutates` honestly.
+    const resolveMutates = (name) => toolRegistry.get(name)?.mutates;
     // ── Phase 16b.4: assemble system-prompt context ─────────────────────
     // PromptBuilder needs SOUL.md (read at build time from `paths.soulMd`),
     // a frozen MemorySnapshot (loaded once at boot — same lifecycle as
@@ -1005,7 +1300,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,
@@ -1034,6 +1333,22 @@ async function buildAgentRuntime(cliOpts, opts) {
                 skillOutcomeTracker.onTool(call, phase, result);
             }
             catch { /* telemetry must not break the turn */ }
+            // v4.5 Phase 8b — pre-tool-call contextual suggestion. Fires
+            // when the call would benefit from a v4.4/v4.5 subsystem the
+            // user currently has off. Engine handles dismissal + budget;
+            // we just render the tip and tell the engine it was shown.
+            if (phase === 'before') {
+                try {
+                    // eslint-disable-next-line @typescript-eslint/no-var-requires
+                    const { getSuggestionEngine } = require('../../core/v4/suggestionEngine');
+                    const tip = getSuggestionEngine().checkToolCall(call);
+                    if (tip) {
+                        display.dim(tip.message);
+                        getSuggestionEngine().recordFired(tip.slot);
+                    }
+                }
+                catch { /* never let a suggestion crash a tool call */ }
+            }
             callbacks.onToolCall?.(call, phase, result);
         },
         onCompression: callbacks.onCompression,
@@ -1042,6 +1357,7 @@ async function buildAgentRuntime(cliOpts, opts) {
         skillTeacherCallbacks: { promptUser: callbacks.promptSkillProposal },
         resolveVerifiedFlag,
         resolveToolset,
+        resolveMutates,
         providerId,
         modelId,
         // Phase 16b.4: wire PromptBuilder so SOUL.md actually reaches the LLM.
@@ -1113,6 +1429,28 @@ async function buildAgentRuntime(cliOpts, opts) {
     memoryManager.onMutation((file) => {
         agent.markMemoryDirty(file === 'user' ? 'user' : 'memory');
     });
+    // v4.5 Phase 7b — daemon agent builder. Captures the references
+    // above so the dispatcher can construct a fresh AidenAgent per
+    // daemon-claimed trigger. Strategy B (closure capture) — REPL
+    // construction stays untouched; we just expose the builder on
+    // the returned AgentRuntime so runInteractiveChat can pass it to
+    // bootstrapDaemon().
+    const { buildDaemonAgentBuilder } = await Promise.resolve().then(() => __importStar(require('./daemonAgentBuilder')));
+    const daemonAgentBuilder = buildDaemonAgentBuilder({
+        paths,
+        resolver,
+        fallbackAdapter: adapter,
+        toolRegistry,
+        toolExecutor,
+        auxiliaryClient,
+        promptBuilder,
+        promptBuilderOptions,
+        memoryManager,
+        resolveVerifiedFlag,
+        resolveToolset,
+        resolveMutates,
+        maxTurns: config.getValue('agent.max_turns', 90),
+    });
     // Phase v4.1.2 alive-core: SOUL.md file watcher. Best-effort —
     // some filesystems (network mounts, certain WSL configs) don't
     // support fs.watch reliably. We try to attach; if it fails, the
@@ -1154,6 +1492,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
@@ -1170,10 +1523,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
@@ -1194,110 +1582,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
@@ -1489,10 +1835,40 @@ async function buildAgentRuntime(cliOpts, opts) {
         pluginLoader,
         exploreMode,
         channelManager,
+        daemonAgentBuilder,
+        // v4.6 Phase 2Q-B — REPL parent-run wiring.
+        replRunStore,
+        replInstanceId,
+        replParentRunRef,
     };
 }
 async function runInteractiveChat(cliOpts, opts) {
     const runtime = await buildAgentRuntime(cliOpts, opts);
+    // v4.5 Phase 7c — install the REAL agent runner now that the
+    // REPL agent is built. The daemon foundation already came up
+    // earlier (top of REPL action handler) with the Phase 5a
+    // placeholder runner serving claims. This call atomically swaps
+    // the dispatcher's runner from placeholder → real; the next
+    // claim uses `runtime.daemonAgentBuilder` to construct a real
+    // AidenAgent per fire.
+    try {
+        if (process.env.AIDEN_DAEMON === '1') {
+            const { getDaemonHandle, installDaemonAgentBuilder } = await Promise.resolve().then(() => __importStar(require('../../core/v4/daemon/bootstrap')));
+            const handle = getDaemonHandle();
+            if (handle && handle.active) {
+                const ok = installDaemonAgentBuilder(handle, runtime.daemonAgentBuilder, { provider: runtime.providerId, model: runtime.modelId });
+                if (!ok) {
+                    console.warn('[daemon] real-runner install returned false — placeholder still active');
+                }
+            }
+        }
+    }
+    catch (e) {
+        // Fail-loud but non-fatal — install failure leaves the
+        // placeholder runner active; the REPL still works and the
+        // daemon's rails still serve triggers.
+        console.error('[daemon] install agent builder failed: ' + (e instanceof Error ? e.message : String(e)));
+    }
     const sessionOpts = {
         agent: runtime.agent,
         display: runtime.display,
@@ -1530,6 +1906,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)({