pikiloop 0.4.0

package/dist/cli/main.js

@@ -0,0 +1,726 @@
+#!/usr/bin/env node
+/**
+ * cli.ts — CLI entry point for pikiloop.
+ */
+// Mark this process as a Claude Code context so nested claude launches are blocked.
+// The spawn framework in code-agent.ts strips this before launching agent subprocesses.
+process.env.CLAUDECODE = '1';
+import { hydrateLegacyEnv, migrateLegacyStateDir } from '../core/legacy-compat.js';
+// Backward-compat for the pikiclaw → pikiloop rename. Runs before any config is
+// read or lock taken: mirror PIKICLAW_* → PIKILOOP_* and move ~/.pikiclaw →
+// ~/.pikiloop. Both are idempotent no-ops once an install has migrated.
+hydrateLegacyEnv();
+migrateLegacyStateDir();
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { startAgentAutoUpdate } from '../agent/auto-update.js';
+import { envBool, DEFAULT_RUN_TIMEOUT_S } from '../bot/bot.js';
+import { DAEMON_TIMEOUTS } from '../core/constants.js';
+import { hasConfiguredChannelToken, resolveConfiguredChannels } from './channels.js';
+import { ChannelSupervisor } from './channel-supervisor.js';
+import { listAgents } from '../agent/index.js';
+import { startDashboard } from '../dashboard/server.js';
+import { buildSetupGuide, collectSetupState, hasReadyAgent, isSetupReady } from './onboarding.js';
+import { buildRestartCommand, clearDaemonPidFile, clearRestartStateFile, consumeRestartStateFile, createRestartStateFilePath, isProcessAlive, PROCESS_RESTART_EXIT_CODE, readDaemonPidFile, requestProcessRestart, writeDaemonPidFile, } from '../core/process-control.js';
+import { runSetupWizard } from './setup-wizard.js';
+import { FROM_LAUNCHD_ENV, maybePromptAutostart } from './autostart.js';
+import { applyUserConfig, loadUserConfig, startUserConfigSync, updateUserConfig, } from '../core/config/user-config.js';
+import { VERSION } from '../core/version.js';
+/* ── Daemon (watchdog) mode ─────────────────────────────────────────── */
+const DAEMON_RESTART_DELAY_MS = DAEMON_TIMEOUTS.restartDelay;
+const DAEMON_MAX_RESTART_DELAY_MS = DAEMON_TIMEOUTS.maxRestartDelay;
+const DAEMON_RAPID_CRASH_WINDOW_MS = DAEMON_TIMEOUTS.rapidCrashWindow;
+function daemonLog(msg) {
+    const ts = new Date().toTimeString().slice(0, 8);
+    process.stdout.write(`[daemon ${ts}] ${msg}\n`);
+}
+/** Args that are daemon-specific and should not be forwarded to the child. */
+const DAEMON_STRIP_ARGS = new Set(['--daemon', '--no-daemon']);
+/**
+ * Runs the bot as a supervised child process. On non-zero exit the child is
+ * restarted with exponential back-off. A clean exit (code 0) stops the daemon.
+ * Restart requests use a dedicated exit code and are respawned immediately.
+ */
+async function runDaemon(userArgs) {
+    // Forward user's CLI args (strip daemon-related flags).
+    const forwardedArgs = userArgs.filter(a => !DAEMON_STRIP_ARGS.has(a));
+    const restartCmd = process.env.PIKILOOP_RESTART_CMD;
+    const restartStateFile = createRestartStateFilePath(process.pid);
+    // Publish the daemon PID so `pikiloop stop` can find it. Clean up on any
+    // exit path so a stale file never points at someone else's PID.
+    writeDaemonPidFile(process.pid);
+    process.once('exit', clearDaemonPidFile);
+    // Auto-start enrollment: only when the user explicitly typed `--daemon`
+    // (the watchdog itself is on by default, so we use the explicit flag as
+    // the signal of "I'm settling in for long-term use"). Fire-and-forget so
+    // the bot still comes up immediately; the dialog appears a few seconds
+    // later. No-op when already enrolled, declined, non-interactive, or
+    // already running under launchd — see src/cli/autostart.ts.
+    if (userArgs.includes('--daemon')) {
+        maybePromptAutostart(daemonLog);
+    }
+    let restartDelay = DAEMON_RESTART_DELAY_MS;
+    let attempt = 0;
+    let nextRestartEnv = {};
+    const spawnChild = (extraEnv = {}) => {
+        clearRestartStateFile(restartStateFile);
+        const { bin, args } = buildRestartCommand(forwardedArgs, restartCmd);
+        daemonLog(`exec: ${bin} ${args.join(' ')}`);
+        // npx/npx.cmd needs shell resolution; node.exe does not
+        const needsShell = process.platform === 'win32' && !bin.endsWith('node.exe');
+        return spawn(needsShell ? `"${bin}"` : bin, args, {
+            stdio: 'inherit',
+            shell: needsShell || undefined,
+            env: {
+                ...process.env,
+                ...extraEnv,
+                PIKILOOP_DAEMON_CHILD: '1',
+                PIKILOOP_RESTART_STATE_FILE: restartStateFile,
+                npm_config_yes: 'true',
+            },
+        });
+    };
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        attempt++;
+        daemonLog(`starting child process (attempt #${attempt})`);
+        const child = spawnChild(nextRestartEnv);
+        nextRestartEnv = {};
+        daemonLog(`child running (pid=${child.pid})`);
+        const startedAt = Date.now();
+        let shutdownSignal = null;
+        // Forward termination and restart signals to the active child.
+        const forwardShutdownSignal = (sig) => {
+            shutdownSignal = sig;
+            child.kill(sig);
+        };
+        const forwardRestartSignal = () => {
+            child.kill('SIGUSR2');
+        };
+        process.on('SIGINT', forwardShutdownSignal);
+        process.on('SIGTERM', forwardShutdownSignal);
+        process.on('SIGUSR2', forwardRestartSignal);
+        const code = await new Promise(resolve => {
+            child.on('exit', (c) => resolve(c));
+        });
+        process.removeListener('SIGINT', forwardShutdownSignal);
+        process.removeListener('SIGTERM', forwardShutdownSignal);
+        process.removeListener('SIGUSR2', forwardRestartSignal);
+        if (shutdownSignal) {
+            const exitCode = shutdownSignal === 'SIGINT' ? 130 : 143;
+            daemonLog(`received ${shutdownSignal}, daemon stopping`);
+            process.exit(exitCode);
+        }
+        if (code === PROCESS_RESTART_EXIT_CODE) {
+            nextRestartEnv = consumeRestartStateFile(restartStateFile);
+            restartDelay = DAEMON_RESTART_DELAY_MS;
+            daemonLog('child requested restart, respawning immediately');
+            continue;
+        }
+        // Clean exit → stop daemon.
+        if (code === 0 || code === null) {
+            daemonLog(`child exited cleanly (code=${code}), daemon stopping`);
+            process.exit(0);
+        }
+        // Exponential back-off for rapid crashes.
+        const uptime = Date.now() - startedAt;
+        if (uptime > DAEMON_RAPID_CRASH_WINDOW_MS) {
+            restartDelay = DAEMON_RESTART_DELAY_MS; // reset if it ran for a while
+        }
+        else {
+            restartDelay = Math.min(restartDelay * 2, DAEMON_MAX_RESTART_DELAY_MS);
+        }
+        daemonLog(`child crashed (code=${code}, uptime=${Math.round(uptime / 1000)}s), restarting in ${Math.round(restartDelay / 1000)}s...`);
+        await new Promise(resolve => setTimeout(resolve, restartDelay));
+    }
+}
+function parseArgs(argv) {
+    const args = {
+        token: null, agent: null, model: null, workdir: null,
+        fullAccess: null, safeMode: false, allowedIds: null,
+        timeout: null, version: false, help: false, doctor: false, setup: false,
+        noDashboard: false, dashboardPort: null, daemon: true,
+        stop: false,
+    };
+    const it = argv[Symbol.iterator]();
+    for (const arg of it) {
+        switch (arg) {
+            case 'stop':
+                args.stop = true;
+                break;
+            case '-t':
+            case '--token':
+                args.token = it.next().value;
+                break;
+            case '-a':
+            case '--agent':
+                args.agent = it.next().value;
+                break;
+            case '-m':
+            case '--model':
+                args.model = it.next().value;
+                break;
+            case '-w':
+            case '--workdir':
+                args.workdir = it.next().value;
+                break;
+            case '--full-access':
+                args.fullAccess = true;
+                break;
+            case '--safe-mode':
+                args.safeMode = true;
+                break;
+            case '--allowed-ids':
+                args.allowedIds = it.next().value;
+                break;
+            case '--timeout':
+                args.timeout = parseInt(it.next().value ?? '', 10);
+                break;
+            case '--doctor':
+                args.doctor = true;
+                break;
+            case '--setup':
+                args.setup = true;
+                break;
+            case '--no-dashboard':
+                args.noDashboard = true;
+                break;
+            case '--dashboard-port':
+                args.dashboardPort = parseInt(it.next().value ?? '', 10);
+                break;
+            case '--daemon':
+                args.daemon = true;
+                break;
+            case '--no-daemon':
+                args.daemon = false;
+                break;
+            case '-v':
+            case '--version':
+                args.version = true;
+                break;
+            case '-h':
+            case '--help':
+                args.help = true;
+                break;
+            default:
+                if (arg.startsWith('-')) {
+                    process.stderr.write(`Unknown option: ${arg}\n`);
+                    process.exit(1);
+                }
+        }
+    }
+    return args;
+}
+/* ── Shared helpers ────────────────────────────────────────────────── */
+function processLog(message) {
+    const ts = new Date().toTimeString().slice(0, 8);
+    process.stdout.write(`[pikiloop ${ts}] ${message}\n`);
+}
+const listStartupAgents = () => listAgents().agents;
+const listVerboseAgents = () => listAgents({ includeVersion: true }).agents;
+/* ── Phase: early exits (MCP serve, --version, --help) ────────────── */
+/** If launched as an MCP stdio server, run that and exit. */
+async function handleMcpServeMode() {
+    if (process.argv.includes('--mcp-serve')) {
+        await import('../agent/mcp/session-server.js');
+        return true;
+    }
+    return false;
+}
+/** Print help text and exit. */
+function printHelp() {
+    process.stdout.write(`pikiloop v${VERSION} — Run local coding agents through IM.
+
+Run a bot that forwards IM messages to a local AI coding agent
+(Claude Code or Codex CLI), streams responses in real-time, and manages
+sessions, models, and workdirs.
+
+Channels are auto-detected from configured credentials. If multiple
+validated channels are enabled, they launch simultaneously.
+
+Usage:
+  npx pikiloop                              # auto-detect from config/env
+  npx pikiloop -w ~/project                 # set working directory
+  npx pikiloop stop                         # stop the running daemon
+
+Options:
+  -t, --token <token>       Channel auth token (env: PIKILOOP_TOKEN)
+  -a, --agent <agent>       AI agent: claude | codex  [default: codex]
+  -m, --model <model>       Default model, switchable in chat via /models
+  -w, --workdir <dir>       Working directory for the agent  [default: current process cwd]
+  --full-access             Codex full-access + Claude bypassPermissions + Gemini yolo/no-sandbox  [default]
+  --safe-mode               Use safer agent permission modes
+  --allowed-ids <id,id>     Comma-separated chat/user ID whitelist
+  --timeout <seconds>       Max seconds per agent request  [default: ${DEFAULT_RUN_TIMEOUT_S}]
+  --doctor                  Run setup checks and exit
+  --setup                   Run the interactive setup wizard
+  --no-daemon               Disable watchdog (auto-restart on crash is ON by default)
+  --no-dashboard            Skip the web dashboard
+  --dashboard-port <port>   Dashboard port  [default: 3939]
+  -v, --version             Print version
+  -h, --help                Print this help
+
+Environment variables (general):
+  PIKILOOP_TOKEN             Channel auth token (same as -t, channel-agnostic)
+  DEFAULT_AGENT              Default agent (same as -a)
+  PIKILOOP_WORKDIR           Working directory (same as -w)
+  PIKILOOP_TIMEOUT           Timeout in seconds (same as --timeout)
+  PIKILOOP_ALLOWED_IDS       Comma-separated chat/user ID whitelist
+  PIKILOOP_FULL_ACCESS       Default full-access behavior (true/false)
+
+Environment variables (Telegram):
+  TELEGRAM_BOT_TOKEN         Telegram bot token (from @BotFather)
+  TELEGRAM_ALLOWED_CHAT_IDS  Comma-separated allowed Telegram chat IDs
+
+Environment variables (Weixin):
+  WEIXIN_BASE_URL            Weixin API base URL (default: https://ilinkai.weixin.qq.com)
+  WEIXIN_BOT_TOKEN           Weixin bot token (normally configured from dashboard QR login)
+  WEIXIN_ACCOUNT_ID          Weixin bot account ID
+
+Environment variables (per agent):
+  CLAUDE_MODEL               Claude model name
+  CLAUDE_PERMISSION_MODE     Permission mode (default: bypassPermissions)
+  CLAUDE_EXTRA_ARGS          Extra CLI args for claude
+  CODEX_MODEL                Codex model name
+  CODEX_REASONING_EFFORT     Reasoning effort (default: xhigh)
+  CODEX_FULL_ACCESS          Full-access mode (default: true)
+  CODEX_EXTRA_ARGS           Extra CLI args for codex
+  GEMINI_MODEL               Gemini model name
+  GEMINI_APPROVAL_MODE       Approval mode (default: yolo)
+  GEMINI_SANDBOX             Sandbox mode (default: false)
+  GEMINI_EXTRA_ARGS          Extra CLI args for gemini
+
+Bot commands (available once running):
+  /sessions   List or switch coding sessions
+  /agents     List or switch AI agents
+  /models     List or switch models
+  /status     Bot status, uptime, and token usage
+  /host       Host machine info (CPU, memory, disk, battery)
+  /switch     Browse and change working directory
+  /restart    Restart with latest version
+
+Environment variables (Feishu):
+  FEISHU_APP_ID              Feishu app ID (from Feishu Open Platform)
+  FEISHU_APP_SECRET          Feishu app secret
+  FEISHU_DOMAIN              API domain (default: https://open.feishu.cn)
+  FEISHU_ALLOWED_CHAT_IDS    Comma-separated allowed Feishu chat IDs
+
+Notes:
+  - weixin setup is QR-based in the dashboard and currently supports text-only replies.
+  - --safe-mode delegates to the agent's own permission model; it does not add
+    a pikiloop-specific approval workflow.
+
+Prerequisites: Node.js >= 18, and at least one agent CLI installed (claude or codex).
+Docs: https://github.com/xiaotonng/pikiloop
+`);
+    process.exit(0);
+}
+/* ── Phase: workdir persistence & daemon handoff ──────────────────── */
+/**
+ * For a fresh CLI launch (not a daemon-managed child), persist the working
+ * directory into setting.json so the bot defaults to where the user invoked
+ * the command. Without `-w`, fall back to the cwd; this is preserved across
+ * non-daemon self-restarts because process-control inherits cwd when spawning
+ * the replacement process.
+ */
+function persistWorkdir(args, userConfig) {
+    if (process.env.PIKILOOP_DAEMON_CHILD)
+        return userConfig;
+    // launchd launches the process from `/`; without `-w`, that would clobber
+    // the user's saved workdir to "/". Skip persistence so the config stays
+    // whatever the user previously chose interactively.
+    if (process.env[FROM_LAUNCHD_ENV])
+        return userConfig;
+    const nextWorkdir = path.resolve(args.workdir || process.cwd());
+    if (userConfig.workdir === nextWorkdir)
+        return userConfig;
+    updateUserConfig({ workdir: nextWorkdir });
+    return loadUserConfig();
+}
+/**
+ * If daemon mode is active and we are the top-level process, become the
+ * watchdog. This function never returns in daemon mode.
+ */
+async function enterDaemonIfNeeded(args) {
+    if (args.daemon && !process.env.PIKILOOP_DAEMON_CHILD) {
+        await runDaemon(process.argv.slice(2));
+    }
+    if (!args.daemon) {
+        // --no-daemon: clear inherited env so requestProcessRestart uses the
+        // direct-spawn path instead of handing off to a non-existent daemon.
+        delete process.env.PIKILOOP_DAEMON_CHILD;
+    }
+}
+/** Install SIGUSR2 restart handler and clean it up on exit. */
+function installRestartSignalHandler() {
+    const onSigusr2 = () => {
+        processLog('SIGUSR2 received, restarting...');
+        void requestProcessRestart({ log: processLog });
+    };
+    process.on('SIGUSR2', onSigusr2);
+    process.once('exit', () => {
+        process.off('SIGUSR2', onSigusr2);
+    });
+}
+/**
+ * Top-level shutdown safety net. Channels install their own SIGINT/SIGTERM
+ * handlers that do per-channel cleanup with a 3 s unref-ed force-exit timer,
+ * but those handlers only exist while a channel is running and silently fail
+ * if cleanup throws before the timer is set. This handler is the last-resort
+ * guarantee: once the user hits Ctrl+C, the process exits within the grace
+ * window no matter what state we're in.
+ */
+function installTopLevelShutdownHandler() {
+    const GRACE_MS = 5_000;
+    let shuttingDown = false;
+    const onSignal = (sig) => {
+        const exitCode = sig === 'SIGINT' ? 130 : 143;
+        if (shuttingDown) {
+            // Second Ctrl+C — bail immediately.
+            processLog(`${sig} again, forcing immediate exit`);
+            process.exit(exitCode);
+        }
+        shuttingDown = true;
+        processLog(`${sig} received, shutting down (force exit in ${GRACE_MS / 1000}s)...`);
+        setTimeout(() => process.exit(exitCode), GRACE_MS);
+    };
+    process.on('SIGINT', () => onSignal('SIGINT'));
+    process.on('SIGTERM', () => onSignal('SIGTERM'));
+}
+/* ── Phase: stop subcommand ───────────────────────────────────────── */
+/**
+ * Find and terminate the running daemon. Reads the PID file written by
+ * `runDaemon`, sends SIGTERM, waits briefly, escalates to SIGKILL if the
+ * process is still alive. Never returns — always exits.
+ */
+async function handleStopCommand() {
+    const pid = readDaemonPidFile();
+    if (!pid) {
+        process.stderr.write('pikiloop stop: no daemon PID file found (is pikiloop running in daemon mode?)\n');
+        process.exit(1);
+    }
+    if (!isProcessAlive(pid)) {
+        process.stdout.write(`pikiloop stop: daemon (pid ${pid}) is not running, clearing stale PID file\n`);
+        clearDaemonPidFile();
+        process.exit(0);
+    }
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 'ESRCH') {
+            process.stdout.write(`pikiloop stop: daemon (pid ${pid}) already exited\n`);
+            clearDaemonPidFile();
+            process.exit(0);
+        }
+        process.stderr.write(`pikiloop stop: failed to signal pid ${pid}: ${err}\n`);
+        process.exit(1);
+    }
+    process.stdout.write(`pikiloop stop: SIGTERM → pid ${pid}\n`);
+    // Poll for up to 8 s; daemon's child needs ~3 s for its force-exit timer.
+    const deadline = Date.now() + 8_000;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid)) {
+            clearDaemonPidFile();
+            process.stdout.write(`pikiloop stop: daemon (pid ${pid}) stopped\n`);
+            process.exit(0);
+        }
+        await new Promise(resolve => setTimeout(resolve, 250));
+    }
+    // Escalate to SIGKILL.
+    process.stderr.write(`pikiloop stop: daemon (pid ${pid}) still alive after 8s, sending SIGKILL\n`);
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch { }
+    clearDaemonPidFile();
+    process.exit(0);
+}
+/* ── Phase: doctor check ──────────────────────────────────────────── */
+/** Run setup diagnostics and exit (--doctor). */
+function runDoctorCheck(channel, tokenProvided) {
+    const setupState = collectSetupState({
+        agents: listVerboseAgents(),
+        channel,
+        tokenProvided,
+    });
+    const guide = buildSetupGuide(setupState, VERSION, { doctor: true });
+    const ready = isSetupReady(setupState);
+    if (ready)
+        process.stdout.write(`${guide}\nSetup looks ready.\n`);
+    else
+        process.stderr.write(guide);
+    process.exit(ready ? 0 : 1);
+}
+/* ── Phase: setup (dashboard / wizard / guide) ────────────────────── */
+/**
+ * Poll the dashboard until the user completes configuration.
+ * Mutates `ctx` in place with freshly resolved channels.
+ */
+async function awaitDashboardConfig(dashboard, ctx) {
+    const ts = new Date().toTimeString().slice(0, 8);
+    process.stdout.write(`[pikiloop ${ts}] waiting for configuration via dashboard...\n`);
+    process.stdout.write(`[pikiloop ${ts}] configure at ${dashboard.url}; startup will continue automatically once ready.\n`);
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        await new Promise(resolve => setTimeout(resolve, DAEMON_TIMEOUTS.configPollInterval));
+        ctx.userConfig = loadUserConfig();
+        const channels = resolveConfiguredChannels({
+            config: { ...ctx.userConfig, ...ctx.configOverrides },
+            tokenOverride: ctx.args.token,
+        });
+        const channel = channels[0] || 'feishu';
+        const nextSetupState = collectSetupState({
+            agents: listStartupAgents(),
+            channel,
+            tokenProvided: channels.length > 0 && hasConfiguredChannelToken({ ...ctx.userConfig, ...ctx.configOverrides }, channel, ctx.args.token),
+        });
+        // Dashboard-as-terminal: an installed agent is the only prerequisite to
+        // start. IM channels are optional — the dashboard is itself a terminal, so
+        // don't block startup waiting for a channel token.
+        const nextNeedsSetup = !hasReadyAgent(nextSetupState);
+        if (!nextNeedsSetup) {
+            const resumeTs = new Date().toTimeString().slice(0, 8);
+            process.stdout.write(`[pikiloop ${resumeTs}] configuration detected, starting bot channels...\n`);
+            return { channels, channel };
+        }
+    }
+}
+/**
+ * Run the setup phase: dashboard wait-loop, terminal wizard, or guide printout.
+ * Returns the dashboard instance (if started) and possibly-updated userConfig.
+ */
+async function runSetupPhase(args, userConfig, configOverrides, channels, channel, tokenProvided) {
+    const setupState = collectSetupState({
+        agents: listStartupAgents(),
+        channel,
+        tokenProvided,
+    });
+    const useDashboard = !args.noDashboard && !args.setup;
+    let dashboard = null;
+    // With the dashboard as a terminal, an installed agent is enough to start.
+    // Without the dashboard (headless server / --no-dashboard), an IM channel is
+    // still required as the only terminal.
+    const needsSetup = useDashboard
+        ? !hasReadyAgent(setupState)
+        : (channels.length === 0 || !tokenProvided || !hasReadyAgent(setupState));
+    if (useDashboard) {
+        // Suppress the browser pop on auto-start when there's no user-facing
+        // terminal: launchd-spawned bots, Docker/headless server runs, or when
+        // the user explicitly set PIKILOOP_OPEN_BROWSER=0.
+        const openBrowser = !process.env[FROM_LAUNCHD_ENV]
+            && !envBool('PIKILOOP_DOCKER', false)
+            && envBool('PIKILOOP_OPEN_BROWSER', true);
+        dashboard = await startDashboard({
+            port: args.dashboardPort || 3939,
+            open: openBrowser,
+        });
+        if (needsSetup) {
+            const ctx = { userConfig, configOverrides, args };
+            const resolved = await awaitDashboardConfig(dashboard, ctx);
+            userConfig = ctx.userConfig;
+            channels = resolved.channels;
+            channel = resolved.channel;
+        }
+    }
+    else if (args.setup) {
+        const canPromptInteractively = !!(process.stdin.isTTY && process.stdout.isTTY);
+        if (!canPromptInteractively) {
+            process.stderr.write('--setup requires an interactive terminal.\n');
+            process.exit(1);
+        }
+        const wizard = await runSetupWizard({
+            version: VERSION,
+            channel,
+            argsAgent: args.agent || userConfig.defaultAgent || null,
+            currentToken: args.token || userConfig.telegramBotToken || null,
+            initialState: setupState,
+            listAgents: listVerboseAgents,
+        });
+        if (!wizard.completed)
+            process.exit(1);
+        userConfig = loadUserConfig();
+    }
+    else if (needsSetup) {
+        process.stdout.write(buildSetupGuide(setupState, VERSION));
+        process.exit(0);
+    }
+    return { dashboard, userConfig, channels, channel };
+}
+/* ── Phase: post-setup validation ─────────────────────────────────── */
+/**
+ * Re-resolve channels after the setup phase and validate we have a runnable
+ * terminal: an installed agent is mandatory; an IM channel is required only
+ * when the dashboard isn't serving as the terminal. Exits on failure.
+ * Returns the (possibly empty) channel set — empty is valid in dashboard mode.
+ */
+function validatePostSetupChannels(configOverrides, userConfig, args, useDashboard) {
+    const effectiveConfig = { ...userConfig, ...configOverrides };
+    const channels = resolveConfiguredChannels({
+        config: effectiveConfig,
+        tokenOverride: args.token,
+    });
+    const channel = channels[0] || 'feishu';
+    const refreshedSetupState = collectSetupState({
+        agents: listStartupAgents(),
+        channel,
+        tokenProvided: channels.length > 0,
+    });
+    // An installed agent is the hard requirement — no terminal can run a session
+    // without one.
+    if (!hasReadyAgent(refreshedSetupState)) {
+        process.stderr.write(buildSetupGuide(refreshedSetupState, VERSION, { doctor: true }));
+        process.exit(1);
+    }
+    // Zero IM channels is fine when the dashboard is the terminal; only bail when
+    // there's no terminal at all (dashboard disabled AND no channel configured).
+    if (channels.length === 0 && !useDashboard) {
+        process.stdout.write(buildSetupGuide(refreshedSetupState, VERSION));
+        process.exit(0);
+    }
+    return { channels, channel };
+}
+/* ── Phase: runtime config & env setup ────────────────────────────── */
+/**
+ * Build the final runtime config, apply token/model/permission overrides to
+ * the environment, start config file sync, and kick off agent auto-update.
+ */
+function applyRuntimeConfig(args, userConfig, configOverrides, channel) {
+    const runtimeConfig = { ...userConfig, ...configOverrides };
+    // Inject CLI token into channel-specific config fields.
+    if (args.token) {
+        if (channel === 'telegram')
+            runtimeConfig.telegramBotToken = args.token;
+        else if (channel === 'feishu') {
+            const [appId, ...rest] = args.token.split(':');
+            runtimeConfig.feishuAppId = appId;
+            runtimeConfig.feishuAppSecret = rest.join(':');
+        }
+    }
+    if (args.allowedIds && channel === 'telegram')
+        runtimeConfig.telegramAllowedChatIds = args.allowedIds;
+    applyUserConfig(runtimeConfig, undefined, { overwrite: true, clearMissing: true });
+    startAgentAutoUpdate({
+        config: runtimeConfig,
+        agents: listAgents({ includeVersion: true, refresh: true }).agents,
+        log: processLog,
+    });
+    // Model override: route to the correct agent env var.
+    if (args.model) {
+        const ag = args.agent || runtimeConfig.defaultAgent || 'codex';
+        if (ag === 'codex')
+            process.env.CODEX_MODEL = args.model;
+        else if (ag === 'gemini')
+            process.env.GEMINI_MODEL = args.model;
+        else
+            process.env.CLAUDE_MODEL = args.model;
+    }
+    if (args.timeout != null)
+        process.env.PIKILOOP_TIMEOUT = String(args.timeout);
+    // Permission mode: safe vs full-access.
+    if (args.safeMode) {
+        process.env.CODEX_FULL_ACCESS = 'false';
+        process.env.CLAUDE_PERMISSION_MODE = 'default';
+        process.env.GEMINI_APPROVAL_MODE = 'default';
+        process.env.GEMINI_SANDBOX = 'true';
+    }
+    else if (args.fullAccess || envBool('PIKILOOP_FULL_ACCESS', true)) {
+        process.env.CODEX_FULL_ACCESS = 'true';
+        process.env.CLAUDE_PERMISSION_MODE = 'bypassPermissions';
+        process.env.GEMINI_APPROVAL_MODE = 'yolo';
+        process.env.GEMINI_SANDBOX = 'false';
+    }
+    // Live-reload config file sync.
+    //
+    // Only pass overrides that came from CLI flags / explicit args, NOT the full
+    // runtimeConfig. Otherwise a snapshot of every user-managed field (model,
+    // effort, workdir, etc.) gets re-applied on every sync tick, silently
+    // reverting changes the user just made via the menu or dashboard.
+    const syncOverrides = {};
+    if (args.agent)
+        syncOverrides.defaultAgent = args.agent;
+    if (args.token) {
+        if (channel === 'telegram')
+            syncOverrides.telegramBotToken = args.token;
+        else if (channel === 'feishu') {
+            const [appId, ...rest] = args.token.split(':');
+            syncOverrides.feishuAppId = appId;
+            syncOverrides.feishuAppSecret = rest.join(':');
+        }
+    }
+    if (args.allowedIds && channel === 'telegram')
+        syncOverrides.telegramAllowedChatIds = args.allowedIds;
+    const stopUserConfigSync = startUserConfigSync({
+        overrides: syncOverrides,
+        log: message => processLog(message),
+    });
+    process.once('exit', stopUserConfigSync);
+    return runtimeConfig;
+}
+/* ── Phase: channel launch ────────────────────────────────────────── */
+/**
+ * Hand off channel lifecycle to ChannelSupervisor and block forever. The
+ * supervisor reconciles bots against the user config — adding, removing,
+ * or replacing channels in response to dashboard saves without restarting
+ * the pikiloop process.
+ *
+ * Per-bot signal handlers (and the daemon supervisor when present) drive
+ * process exit; this promise is just a foreground keep-alive.
+ */
+async function launchChannels(channels, dashboard) {
+    processLog(`launching channels: ${channels.join(', ')}`);
+    const supervisor = new ChannelSupervisor({ dashboard, log: processLog });
+    await supervisor.start();
+    // Block forever — the dashboard HTTP listener and per-channel signal
+    // handlers keep the process alive and drive shutdown.
+    await new Promise(() => { });
+}
+/* ── main() ───────────────────────────────────────────────────────── */
+export async function main() {
+    if (await handleMcpServeMode())
+        return;
+    const args = parseArgs(process.argv.slice(2));
+    let userConfig = loadUserConfig();
+    if (args.version) {
+        process.stdout.write(`pikiloop ${VERSION}\n`);
+        process.exit(0);
+    }
+    if (args.help)
+        printHelp();
+    if (args.stop)
+        await handleStopCommand();
+    // Persist workdir for fresh (non-daemon-child) launches.
+    userConfig = persistWorkdir(args, userConfig);
+    // Daemon mode: become watchdog (never returns in daemon mode).
+    await enterDaemonIfNeeded(args);
+    // Child / no-daemon process: install restart signal handler + top-level
+    // shutdown safety net so Ctrl+C always brings the process down.
+    installRestartSignalHandler();
+    installTopLevelShutdownHandler();
+    // Apply config overrides from CLI args.
+    const configOverrides = {};
+    if (args.agent)
+        configOverrides.defaultAgent = args.agent;
+    applyUserConfig({ ...userConfig, ...configOverrides }, undefined, { overwrite: true, clearMissing: true });
+    // Resolve initial channels.
+    const effectiveConfig = () => ({ ...userConfig, ...configOverrides });
+    let channels = resolveConfiguredChannels({ config: effectiveConfig(), tokenOverride: args.token });
+    let channel = channels[0] || 'feishu';
+    const tokenProvided = channels.length > 0 && hasConfiguredChannelToken(effectiveConfig(), channel, args.token);
+    // Doctor mode: check and exit.
+    if (args.doctor)
+        runDoctorCheck(channel, tokenProvided);
+    // Setup phase: dashboard, wizard, or guide.
+    const useDashboard = !args.noDashboard && !args.setup;
+    let dashboard;
+    ({ dashboard, userConfig, channels, channel } = await runSetupPhase(args, userConfig, configOverrides, channels, channel, tokenProvided));
+    // Validate the terminal is runnable after setup (channels may be empty when
+    // the dashboard is serving as the terminal).
+    ({ channels, channel } = validatePostSetupChannels(configOverrides, userConfig, args, useDashboard));
+    // Apply runtime config, env overrides, and start config sync.
+    applyRuntimeConfig(args, userConfig, configOverrides, channel);
+    // Launch bot channel(s).
+    await launchChannels(channels, dashboard);
+}
+main().catch(err => { console.error(err); process.exit(1); });