aiden-runtime 4.0.1 → 4.1.0

package/dist/cli/v4/aidenCLI.js

@@ -58,8 +58,11 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getEnvSource = exports.loadAidenEnvFile = void 0;
+exports.getEnvSource = exports.loadAidenEnvFile = exports.AIDEN_UI_BUILD = void 0;
 exports.main = main;
 exports.buildAgentRuntime = buildAgentRuntime;
 exports.runInteractiveChat = runInteractiveChat;
@@ -71,12 +74,17 @@ exports.runSkillsSubcommand = runSkillsSubcommand;
 /* eslint-disable @typescript-eslint/no-explicit-any */
 const commander_1 = require("commander");
 const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
 const chatSession_1 = require("./chatSession");
 const aidenTUI_1 = require("./aidenTUI");
 const display_1 = require("./display");
 const skinEngine_1 = require("./skinEngine");
 const commandRegistry_1 = require("./commandRegistry");
 const callbacks_1 = require("./callbacks");
+// Tier-3.1 (v4.1-tier3.1) — re-export the build fingerprint so the
+// runtime smoke can find it in the bundled artifact.
+const uiBuild_1 = require("./uiBuild");
+Object.defineProperty(exports, "AIDEN_UI_BUILD", { enumerable: true, get: function () { return uiBuild_1.AIDEN_UI_BUILD; } });
 const setupWizard_1 = require("./setupWizard");
 const doctor_1 = require("./doctor");
 const modelPicker_1 = require("./commands/modelPicker");
@@ -88,6 +96,7 @@ const sessionStore_1 = require("../../core/v4/sessionStore");
 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");
 const skillCommands_1 = require("../../core/v4/skillCommands");
 const aidenAgent_1 = require("../../core/v4/aidenAgent");
 const promptBuilder_1 = require("../../core/v4/promptBuilder");
@@ -98,17 +107,31 @@ const approvalEngine_1 = require("../../moat/approvalEngine");
 const plannerGuard_1 = require("../../moat/plannerGuard");
 const honestyEnforcement_1 = require("../../moat/honestyEnforcement");
 const skillTeacher_1 = require("../../moat/skillTeacher");
+const skillMiner_1 = require("../../core/v4/skillMining/skillMiner");
+const uiBuild_2 = require("./uiBuild");
 const memoryGuard_1 = require("../../moat/memoryGuard");
 const ssrfProtection_1 = require("../../moat/ssrfProtection");
 const tirithScanner_1 = require("../../moat/tirithScanner");
 const credentialResolver_1 = require("../../providers/v4/credentialResolver");
 const runtimeResolver_1 = require("../../providers/v4/runtimeResolver");
 const chatCompletionsAdapter_1 = require("../../providers/v4/chatCompletionsAdapter");
+const modelCatalog_1 = require("../../providers/v4/modelCatalog");
 const providerFallback_1 = require("../../core/v4/providerFallback");
 const skillBundledRestore_1 = require("../../core/v4/skillBundledRestore");
+const providerDetection_1 = require("../../core/v4/firstRun/providerDetection");
 const aidenLogger_1 = require("../../core/v4/aidenLogger");
 const plugins_1 = require("../../core/v4/plugins");
 const providerAuth_1 = require("../../core/v4/auth/providerAuth");
+// Phase v4.1-1.1 — CLI-side ChannelManager. The same singleton lives in
+// the API server process; in a CLI-only session we host it here so
+// /channel commands operate without a separate server. When `aiden serve`
+// runs in the SAME process tree on the same machine, polling-based
+// adapters (Telegram) must only be started in one of the two — we
+// gate startup on a heuristic below to avoid 409 polling-conflict.
+const manager_1 = require("../../core/channels/manager");
+const telegram_1 = require("../../core/channels/telegram");
+const gateway_1 = require("../../core/gateway");
+const logger_1 = require("../../core/v4/logger");
 const v4_1 = require("../../tools/v4");
 const mcpSetup_1 = require("../../tools/v4/mcpSetup");
 const skillCommandHandler_1 = require("./commands/skillCommandHandler");
@@ -191,7 +214,24 @@ async function main(argv, opts = {}) {
         .option('--planner-guard <mode>', 'PlannerGuard mode: off | rule_based | llm_classified')
         .option('--honesty <mode>', 'HonestyEnforcement mode: off | detect | enforce')
         .option('--skill-teacher <tier>', 'SkillTeacher tier: off | tier_3_propose | tier_4_auto')
+        .option('--no-ui', 'Disable Tier-3 UI polish (autosuggest ghost text, inline status line); fall back to legacy rendering')
         .action(async () => {
+        // Tier-3.1: argv discipline. If positional args were passed but
+        // no subcommand matched, error to stderr and exit non-zero
+        // rather than silently booting the REPL — a typo'd subcommand
+        // otherwise produces a hung foreground.
+        const leftover = program.args ?? [];
+        if (leftover.length > 0) {
+            process.stderr.write(`error: unknown command "${leftover[0]}"\n`);
+            process.stderr.write(`Run 'aiden --help' for available commands.\n`);
+            process.exit(2);
+        }
+        // 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.
+        const o = program.opts();
+        if (o.ui === false)
+            process.env.AIDEN_NO_UI = '1';
         const cliOpts = program.opts();
         if (opts.runChatHook) {
             await opts.runChatHook(cliOpts);
@@ -199,6 +239,16 @@ async function main(argv, opts = {}) {
         }
         await runInteractiveChat(cliOpts, opts);
     });
+    // Tier-3.1: hidden one-shot — emits the UI build fingerprint and
+    // exits. Used by the runtime smoke to verify the bundled artifact
+    // matches the expected sub-phase without parsing other output.
+    program
+        .command('print-ui-build', { hidden: true })
+        .description('Print the v4.1 tier-3 UI build fingerprint and exit.')
+        .action(() => {
+        process.stdout.write(`${uiBuild_1.AIDEN_UI_BUILD}\n`);
+        process.exit(0);
+    });
     program
         .command('setup')
         .description('Run the setup wizard (provider + model + API key)')
@@ -261,17 +311,82 @@ async function main(argv, opts = {}) {
     });
     program
         .command('mcp <action>')
-        .description('Manage MCP servers (full impl deferred to v4.1 with the gateway).')
+        .description('MCP server mode (Phase v4.1-mcp). Actions: serve, status, tools.')
         .action(async (action) => {
         if (opts.runMcpHook) {
             await opts.runMcpHook(action);
             return;
         }
-        const out = opts.writeOut ?? ((t) => process.stdout.write(t));
-        out(`'aiden mcp ${action}' is deferred to v4.1 alongside the gateway.\n`);
+        // Lazy-load so the rest of the CLI does not pay the import cost
+        // for `setup`, `doctor`, `model`, etc. on every invocation.
+        const { runMcpSubcommand } = await Promise.resolve().then(() => __importStar(require('./commands/mcp')));
+        const code = await runMcpSubcommand(action, {
+            writeOut: opts.writeOut,
+            writeErr: (t) => process.stderr.write(t),
+        });
+        if (code !== 0)
+            process.exit(code);
+    });
+    program
+        .command('voice [args...]')
+        .description('Voice diagnostics + one-shot TTS / transcribe (Phase v4.1-voice-cli). ' +
+        'Usage: aiden voice doctor | tts "<text>" | transcribe <file>')
+        .allowUnknownOption()
+        .action(async (args) => {
+        const { runVoiceSubcommand } = await Promise.resolve().then(() => __importStar(require('./voiceCli')));
+        const action = (args[0] ?? 'doctor').toLowerCase();
+        const rest = args.slice(1);
+        const code = await runVoiceSubcommand(action, rest, {
+            writeOut: opts.writeOut,
+            writeErr: (t) => process.stderr.write(t),
+        });
+        if (code !== 0)
+            process.exit(code);
+    });
+    program
+        .command('subagent <action>')
+        .description('Subagent fanout diagnostics (Phase v4.1-subagent). Actions: status, tools.')
+        .action(async (action) => {
+        const { runSubagentSubcommand } = await Promise.resolve().then(() => __importStar(require('./commands/subagent')));
+        const code = await runSubagentSubcommand(action, {
+            writeOut: opts.writeOut,
+            writeErr: (t) => process.stderr.write(t),
+        });
+        if (code !== 0)
+            process.exit(code);
+    });
+    program
+        .command('fanout [args...]')
+        .description('Run a parallel agent fanout (Phase v4.1-subagent). ' +
+        'Usage: aiden fanout "<query>" --n=3 --merge=combine [--mode=ensemble] [--dry-run]')
+        .allowUnknownOption()
+        .action(async (args) => {
+        const { runFanoutCli } = await Promise.resolve().then(() => __importStar(require('./commands/fanout')));
+        const code = await runFanoutCli(args, {
+            writeOut: opts.writeOut,
+            writeErr: (t) => process.stderr.write(t),
+        });
+        if (code !== 0)
+            process.exit(code);
     });
     // v4.1 placeholders. (`tui` graduated to a real flag in Phase 15.)
-    for (const cmd of ['batch', 'gateway', 'cron', 'pairing', 'update']) {
+    program
+        .command('cron [args...]')
+        .description('Cron diagnostics + one-shot list / run (Phase v4.1 hardened cron). ' +
+        'Usage: aiden cron status | list | run <id>')
+        .allowUnknownOption()
+        .action(async (args) => {
+        const { runCronSubcommand } = await Promise.resolve().then(() => __importStar(require('./cronCli')));
+        const action = (args[0] ?? 'status').toLowerCase();
+        const rest = args.slice(1);
+        const code = await runCronSubcommand(action, rest, {
+            writeOut: opts.writeOut,
+            writeErr: (t) => process.stderr.write(t),
+        });
+        if (code !== 0)
+            process.exit(code);
+    });
+    for (const cmd of ['batch', 'gateway', 'pairing', 'update']) {
         program
             .command(cmd)
             .description(`(deferred to v4.1)`)
@@ -351,9 +466,70 @@ async function buildAgentRuntime(cliOpts, opts) {
     }
     const config = new config_1.ConfigManager(paths);
     await config.load();
-    if (await (0, setupWizard_1.isFreshInstall)(paths)) {
-        process.stdout.write('Aiden is not configured yet. Running setup wizard…\n');
-        await (0, setupWizard_1.runSetupWizard)({ paths });
+    // 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
+    //      (was working under the old gate; still does).
+    //   2. user with config.yaml pointing at chatgpt-plus but a stale /
+    //      missing OAuth token file → wizard fires (was NOT under old
+    //      code — it saw config.yaml present and proceeded into a
+    //      broken resolve, which surfaced as a confusing rate-limit
+    //      error on the user's first chat).
+    //   3. user with no config but Ollama running OR an env API key
+    //      → wizard fires anyway. ConfigManager's DEFAULT_CONFIG points
+    //      at `anthropic / claude-opus-4-7`, which doesn't match the
+    //      detected env / Ollama, so skipping the wizard would surface
+    //      the same confusing "missing ANTHROPIC_API_KEY" error.
+    //   4. moat-boot test fixtures that stub `providers.fake.apiKey`
+    //      inline in config.yaml count as configured — `isFreshInstall`
+    //      already returns false for them so `wizardNeeded` stays false.
+    const detection = await (0, providerDetection_1.detectAvailableProviders)({ paths });
+    const configuredProviderBroken = !!detection.configProvider &&
+        !detection.configuredProviderHasCredentials;
+    const wizardNeeded = !detection.hasAnyProvider ||
+        configuredProviderBroken ||
+        (await (0, setupWizard_1.isFreshInstall)(paths));
+    // Phase 30.2.1: when the wizard returns 'skipped' (explore mode) we
+    // boot the REPL with a NullAdapter instead of trying to resolve a
+    // real provider. Flagged here, set inside the wizard block, and
+    // 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.
+            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();
     }
     const providerId = cliOpts.provider ??
@@ -385,19 +561,32 @@ async function buildAgentRuntime(cliOpts, opts) {
     const credentialResolver = new credentialResolver_1.CredentialResolver(paths.authJson);
     const resolver = new runtimeResolver_1.RuntimeResolver(credentialResolver);
     let adapter;
-    try {
-        adapter = await resolver.resolve({ providerId, modelId, config, paths });
+    if (exploreMode) {
+        // Phase 30.2.1 — wizard skipped. Use a NullAdapter so AidenAgent
+        // construction succeeds; ChatSession will intercept chat attempts
+        // BEFORE calling the adapter and surface the friendly message.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { NullAdapter } = require('../../providers/v4/nullAdapter');
+        adapter = new NullAdapter();
     }
-    catch (err) {
-        display.printError(`Could not resolve provider '${providerId}' / model '${modelId}': ${err.message}`, 'Run `aiden model` to pick a valid provider, or `aiden doctor`.');
-        process.exit(1);
+    else {
+        try {
+            adapter = await resolver.resolve({ providerId, modelId, config, paths });
+        }
+        catch (err) {
+            display.printError(`Could not resolve provider '${providerId}' / model '${modelId}': ${err.message}`, 'Run `aiden model` to pick a valid provider, or `aiden doctor`.');
+            process.exit(1);
+        }
     }
     // Phase 16b.1: wrap chat_completions providers in a FallbackAdapter so
     // 429s on Groq slot 1 transparently retry Groq slot 2/3 and Together.
     // Only activates when there's at least one *additional* slot configured
     // beyond the primary — otherwise the wrapper would just rethrow.
+    // Phase 30.2.1: skip in explore mode — wrapping a NullAdapter in
+    // FallbackAdapter would just defer the friendly error one layer.
     let fallbackAdapter = null;
-    if (adapter.apiMode === 'chat_completions' &&
+    if (!exploreMode &&
+        adapter.apiMode === 'chat_completions' &&
         (providerId === 'groq' || providerId === 'together')) {
         const slots = buildAgentFallbackSlots(adapter, providerId, modelId);
         const reachable = slots.filter((s) => s.keyPresent);
@@ -698,6 +887,14 @@ async function buildAgentRuntime(cliOpts, opts) {
         personalityOverlay: activeOverlay,
         modelId,
     };
+    // ── Phase v4.1-skill-mining ──────────────────────────────────────────
+    // Construct the miner once — it owns its in-memory session counter +
+    // CandidateStore handle. Skipped entirely in MCP serve mode (the
+    // serve binary doesn't run the agent loop the same way and shouldn't
+    // mutate skill state from inside JSON-RPC handling).
+    const skillMiner = (0, uiBuild_2.isMcpServeMode)()
+        ? undefined
+        : new skillMiner_1.SkillMiner({ auxiliaryClient });
     // ── Build agent with all moat layers attached ────────────────────────
     const agent = new aidenAgent_1.AidenAgent({
         provider: adapter,
@@ -708,6 +905,13 @@ async function buildAgentRuntime(cliOpts, opts) {
         plannerGuard,
         honestyEnforcement,
         skillTeacher,
+        skillMiner,
+        onSkillCandidate: (candidate) => {
+            try {
+                callbacks.onSkillCandidate?.(candidate);
+            }
+            catch { /* notification must not break the turn */ }
+        },
         // Phase 23.5: tool event rows. CliCallbacks.onToolCall
         // emits a single line per call — `· tool <name> <args> [running]`
         // mutates to `[ok 220ms]` / `[fail 1.4s]` / `[blocked]` on resolve.
@@ -761,6 +965,236 @@ async function buildAgentRuntime(cliOpts, opts) {
     memoryManager.onMutation((file) => {
         agent.markMemoryDirty(file === 'user' ? 'user' : 'memory');
     });
+    // ── Phase v4.1-subagent.1 — subagent_fanout wiring is below
+    // (after `bootLogger` is declared and the gateway processor is set
+    // up). Stub registered at boot is replaced there with the real
+    // closures over adapter / sessionManager / promptBuilder / etc.
+    // Phase v4.1-1.3a — boot a unified mode-aware Logger ('cli-interactive'
+    // mode = no stdout sinks, REPL is sacred). Declared here so the gateway
+    // processor + channel manager (later in the function) can both attach
+    // scoped child loggers to the same root.
+    const { logger: bootLogger } = (0, logger_1.createBootLogger)({
+        mode: 'cli-interactive',
+        logsDir: paths.logsDir,
+    });
+    // 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'));
+    // ── 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
+    // to MCP / /tools immediately. NOW that the runtime has a provider
+    // adapter, an active model, sessions, memory, and a built agent, we
+    // re-register subagent_fanout with the real callbacks so live calls
+    // (from REPL, MCP, or `aiden fanout`) actually execute children
+    // instead of returning the "not wired" stub error.
+    //
+    // The closures capture parent runtime handles. Each fanout call
+    // builds a fresh AidenAgent per child — the AidenAgent constructor
+    // is cheap (per-instance state, no module singletons), so N=5
+    // children = 5 instances + 5 cloned FallbackAdapters. The heavy
+    // shared subsystems (registry, skillLoader, paths, memoryManager,
+    // promptBuilder, promptBuilderOptions) are read-only and pass by
+    // reference.
+    toolRegistry.register((0, index_1.makeSubagentFanoutTool)({
+        logger: bootLogger.child('subagent'),
+        resolveActiveModel: () => ({ providerId, modelId }),
+        aggregatorAdapter: adapter,
+        resolveProviders: () => {
+            // When the parent uses FallbackAdapter, expose every key-present
+            // slot's (providerId, modelId) so rotation can spread children
+            // across distinct providers / keys. Otherwise just the active
+            // provider+model pair — single-provider rotation falls back to
+            // slot rotation within the FallbackAdapter at run time, OR to
+            // pure same-provider sampling (singleProviderWarning fires).
+            if (adapter instanceof providerFallback_1.FallbackAdapter) {
+                const diag = adapter.getDiagnostics();
+                const live = diag.slots.filter((s) => s.keyPresent);
+                if (live.length > 0) {
+                    return live.map((s) => ({
+                        providerId: s.providerId,
+                        modelId: s.modelId,
+                        label: s.id,
+                    }));
+                }
+            }
+            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',
+    });
+    // ── Phase v4.1-2.1: gateway message processor ────────────────────
+    //
+    // Channel adapters call `gateway.routeMessage(...)` for every inbound
+    // message; the gateway then invokes the registered processor — that's
+    // the bridge from channel-side I/O to the agent loop. `aiden serve`
+    // wires its own processor in `api/server.ts` (HTTP-hops to /api/chat
+    // because Express is already up). The CLI host (Phase v4.1-1.1)
+    // never had one, so every Telegram inbound was throwing
+    // "No message processor registered" and the user saw the
+    // friendly-fallback "Something went wrong" reply.
+    //
+    // The closure mirrors the api/server processor's intent — one agent
+    // turn per inbound — but invokes `agent.runConversation()` directly
+    // instead of round-tripping through HTTP. Per-(channel, channelId)
+    // history persists through the same SessionStore the REPL uses, so
+    // a Telegram conversation accumulates context across messages, and
+    // a future `/sessions` listing surfaces those threads alongside REPL
+    // sessions.
+    const gatewayProcessorLog = bootLogger.child('gateway.processor');
+    // gateway sessionId (`session_<ts>`) → sessionStore session id.
+    // In-memory only; restart re-creates a fresh sessionStore session
+    // for the same channel+user pair.
+    const gatewaySessionMap = new Map();
+    gateway_1.gateway.setProcessor(async (message) => {
+        try {
+            // 1. Resolve a sessionStore session for this gateway session.
+            //    sessionManager.startSession opens a new row; we cache the
+            //    mapping so subsequent messages from the same chat append
+            //    to the same history.
+            const gatewaySid = message.sessionId
+                ?? `${message.channel}_${message.channelId}`;
+            let storeSid = gatewaySessionMap.get(gatewaySid);
+            if (!storeSid) {
+                const created = sessionManager.startSession({
+                    providerId,
+                    modelId,
+                    title: `${message.channel}:${message.channelId}`,
+                });
+                storeSid = created.id;
+                gatewaySessionMap.set(gatewaySid, storeSid);
+            }
+            // 2. Load past messages for this session and append the new
+            //    user turn so the agent sees full context. We drop tool /
+            //    system rows on load — the agent's prompt builder rebuilds
+            //    those from scratch each call.
+            // Provider Message union has tool-specific variants; we only
+            // load the user/assistant turns and cast to satisfy the union.
+            // Tool-call replay across adapter restarts isn't a feature we
+            // need for chat-channel UX (Phase v4.1-2.1 scope).
+            const past = store.getMessages(storeSid)
+                .filter((r) => r.role === 'user' || r.role === 'assistant')
+                .map((r) => ({ role: r.role, content: r.content }));
+            const userTurn = { role: 'user', content: message.text };
+            const history = [...past, userTurn];
+            // 3. Run one agent turn.
+            const result = await agent.runConversation(history);
+            // 4. Persist the new tail (everything past the loaded history) so
+            //    the next inbound resumes seamlessly. Mirror chatSession's
+            //    record-turn slice convention.
+            const newSlice = result.messages.slice(history.length - 1);
+            sessionManager.recordTurn(storeSid, newSlice, result.totalUsage);
+            return result.finalContent || '(no response)';
+        }
+        catch (err) {
+            // Diagnostics route through the unified logger — nothing reaches
+            // stdout / stderr so the REPL stays clean. The gateway's own
+            // catch returns the friendly fallback to the user.
+            gatewayProcessorLog.error(`processor failed: ${err?.message ?? String(err)}`, { channel: message.channel, channelId: message.channelId });
+            throw err;
+        }
+    });
     // Command registry.
     const commandRegistry = new commandRegistry_1.CommandRegistry();
     for (const cmd of commands_1.allCommands)
@@ -787,6 +1221,59 @@ async function buildAgentRuntime(cliOpts, opts) {
     catch (err) {
         display.dim(`(skill commands unavailable: ${err.message})`);
     }
+    // ── Phase v4.1-1.1: CLI-side channel manager ──────────────────────
+    //
+    // Build a manager local to this CLI process and register the env-driven
+    // adapters that don't need an Express app (Telegram is the only one in
+    // Phase 1 — Discord/Slack/etc. land iteratively). Webhook/Twilio stay
+    // out of CLI scope because they need an HTTP listener.
+    //
+    // Conflict guard: when `aiden serve` is already running locally, BOTH
+    // processes would race the same Telegram bot's long-poll, and the
+    // server would lose every other update with a 409. Probe localhost:4200
+    // briefly; if the server answers, skip auto-start in CLI but still
+    // build the manager so /channel list / status work as a read-only view.
+    //
+    // Phase v4.1-1.3a — `bootLogger` + gateway logger were attached
+    // earlier (right after the agent was constructed) so the gateway
+    // processor closure could share the same scoped sink chain. Here
+    // we just plumb the channels child logger into the manager.
+    const channelManager = new manager_1.ChannelManager({ logger: bootLogger.child('channels') });
+    // Phase v4.1-4.1 — wire active-model lookup into the Telegram
+    // adapter. The closure captures `providerId` / `modelId` from
+    // this scope so the photo-vision module can decide native vs
+    // text routing (and pdf-extract can compute the truncation
+    // budget) using the SAME model the chat path already uses.
+    channelManager.register(new telegram_1.TelegramAdapter({
+        activeModelInfo: () => ({
+            providerId,
+            modelId,
+            contextWindow: (0, modelCatalog_1.findModel)(providerId, modelId)?.contextLength,
+        }),
+    }));
+    let serverIsHosting = false;
+    try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), 250);
+        const probe = await fetch('http://127.0.0.1:4200/health', {
+            signal: ctrl.signal,
+        }).catch(() => null);
+        clearTimeout(timer);
+        if (probe && (probe.status >= 200 && probe.status < 500)) {
+            serverIsHosting = true;
+        }
+    }
+    catch {
+        /* no server — fall through to CLI-host */
+    }
+    if (serverIsHosting) {
+        display.dim('[channels] aiden serve is running locally — channel adapters hosted there, /channel commands stay read-only.');
+    }
+    else {
+        // start() resolves quickly when no token is set (logs "Disabled" and
+        // returns). Errors don't crash boot.
+        channelManager.startAll().catch((e) => display.dim(`[channels] startAll error: ${e.message}`));
+    }
     return {
         paths,
         config,
@@ -820,6 +1307,8 @@ async function buildAgentRuntime(cliOpts, opts) {
         fallbackAdapter,
         personalityManager,
         pluginLoader,
+        exploreMode,
+        channelManager,
     };
 }
 async function runInteractiveChat(cliOpts, opts) {
@@ -846,6 +1335,12 @@ async function runInteractiveChat(cliOpts, opts) {
         paths: runtime.paths,
         personalityManager: runtime.personalityManager,
         pluginLoader: runtime.pluginLoader,
+        // Phase 30.2.1 — boot card renders "model not configured" and
+        // chat attempts get the friendly NotConfiguredError message.
+        unconfigured: runtime.exploreMode,
+        // Phase v4.1-1.1 — live ChannelManager so /channel commands can
+        // list, add, remove, and inspect adapters without an external server.
+        channelManager: runtime.channelManager,
     };
     if (cliOpts.tui) {
         await (0, aidenTUI_1.runTuiMode)({
@@ -863,6 +1358,10 @@ async function runInteractiveChat(cliOpts, opts) {
     // Phase 17 Task 5: fire onTeardown so plugins (e.g. CDP browser) can
     // close their resources before the process exits.
     await runtime.pluginLoader.teardown().catch(() => undefined);
+    // Phase v4.1-1.1 — stop polling adapters before exit so Telegram's
+    // long-poll TCP connection closes cleanly. stopAll() is best-effort
+    // and never throws.
+    await runtime.channelManager.stopAll().catch(() => undefined);
     runtime.store.close?.();
 }
 // ─── setup ─────────────────────────────────────────────────────────────