@ouro.bot/cli 0.1.0-alpha.83 → 0.1.0-alpha.831

package/dist/heart/daemon/cli-defaults.js

@@ -0,0 +1,854 @@
+"use strict";
+/**
+ * CLI default dependency wiring.
+ *
+ * Creates the production OuroCliDeps with real filesystem, socket, and
+ * process bindings. Tests inject mocks for all of these.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultStartDaemonProcess = defaultStartDaemonProcess;
+exports.defaultStartDaemonForFrontend = defaultStartDaemonForFrontend;
+exports.readFirstBundleMetaVersion = readFirstBundleMetaVersion;
+exports.isDaemonLaunchAgentLoaded = isDaemonLaunchAgentLoaded;
+exports.waitForBootstrappedDaemonSocket = waitForBootstrappedDaemonSocket;
+exports.defaultListDiscoveredAgents = defaultListDiscoveredAgents;
+exports.defaultRunSerpentGuide = defaultRunSerpentGuide;
+exports.createDefaultOuroCliDeps = createDefaultOuroCliDeps;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const identity_1 = require("../identity");
+const runtime_1 = require("../../nerves/runtime");
+const ouro_path_installer_1 = require("../versioning/ouro-path-installer");
+const ouro_uti_1 = require("../versioning/ouro-uti");
+const ouro_version_manager_1 = require("../versioning/ouro-version-manager");
+const update_checker_1 = require("../versioning/update-checker");
+const skill_management_installer_1 = require("./skill-management-installer");
+const hatch_flow_1 = require("../hatch/hatch-flow");
+const specialist_orchestrator_1 = require("../hatch/specialist-orchestrator");
+const specialist_prompt_1 = require("../hatch/specialist-prompt");
+const specialist_tools_1 = require("../hatch/specialist-tools");
+const runtime_mode_1 = require("./runtime-mode");
+const agent_discovery_1 = require("./agent-discovery");
+const bundle_manifest_1 = require("../../mind/bundle-manifest");
+const ouro_bot_global_installer_1 = require("../versioning/ouro-bot-global-installer");
+const version_intent_1 = require("../versioning/version-intent");
+const logs_prune_1 = require("./logs-prune");
+const daemon_health_1 = require("./daemon-health");
+const log_tailer_1 = require("./log-tailer");
+const launchd_1 = require("./launchd");
+const socket_client_1 = require("./socket-client");
+const session_activity_1 = require("../session-activity");
+const auth_flow_1 = require("../auth/auth-flow");
+const provider_models_1 = require("../provider-models");
+const cli_parse_1 = require("./cli-parse");
+const provider_discovery_1 = require("./provider-discovery");
+const provider_credentials_1 = require("../provider-credentials");
+const startup_tui_1 = require("./startup-tui");
+const daemon_tombstone_1 = require("./daemon-tombstone");
+// ── Default implementations ──
+function spawnDetachedDaemonProcess(socketPath, environment = process.env) {
+    const entry = path.join((0, identity_1.getRepoRoot)(), "dist", "heart", "daemon", "daemon-entry.js");
+    // Redirect stdio to /dev/null via file descriptors — using 'ignore' causes EPIPE
+    // when the daemon's logging system writes to stderr after the parent exits.
+    const outFd = fs.openSync(os.devNull, "w");
+    const errFd = fs.openSync(os.devNull, "w");
+    const child = (0, child_process_1.spawn)(process.execPath, [entry, "--socket", socketPath], {
+        detached: true,
+        stdio: ["ignore", outFd, errFd],
+        env: environment,
+    });
+    child.unref();
+    // Don't close fds — the child process needs them. They'll be cleaned up when the parent exits.
+    return { pid: child.pid ?? null };
+}
+async function defaultStartDaemonProcess(socketPath) {
+    const launchdStarted = await startDaemonProcessViaLaunchd(socketPath);
+    if (launchdStarted)
+        return launchdStarted;
+    return spawnDetachedDaemonProcess(socketPath);
+}
+async function defaultStartDaemonForFrontend(socketPath, agent) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(agent)) {
+        throw new Error("frontend daemon startup requires a safe agent name");
+    }
+    if (process.platform === "darwin") {
+        bootoutDaemonLaunchAgentLabel(currentUserUid());
+    }
+    return spawnDetachedDaemonProcess(socketPath, {
+        ...process.env,
+        OURO_DAEMON_REQUIRED_AGENT: agent,
+    });
+}
+function defaultWriteStdout(text) {
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+/* v8 ignore start -- thin terminal adapter around process stdout @preserve */
+function defaultWriteRaw(text) {
+    process.stdout.write(text);
+}
+/* v8 ignore stop */
+function resolveDaemonBootEntryPath(homeDir) {
+    const repoRoot = (0, identity_1.getRepoRoot)();
+    const versionManagerRootMarker = `${path.sep}.ouro-cli${path.sep}versions${path.sep}`;
+    if ((0, runtime_mode_1.detectRuntimeMode)(repoRoot) === "production" && repoRoot.includes(versionManagerRootMarker)) {
+        return path.join((0, ouro_version_manager_1.getOuroCliHome)(homeDir), "CurrentVersion", "node_modules", "@ouro.bot", "cli", "dist", "heart", "daemon", "daemon-entry.js");
+    }
+    return path.join(repoRoot, "dist", "heart", "daemon", "daemon-entry.js");
+}
+/**
+ * Read the runtimeVersion from the first .ouro bundle's bundle-meta.json.
+ * Returns undefined if none found or unreadable.
+ */
+function readFirstBundleMetaVersion(bundlesRoot) {
+    try {
+        if (!fs.existsSync(bundlesRoot))
+            return undefined;
+        const entries = fs.readdirSync(bundlesRoot, { withFileTypes: true });
+        for (const entry of entries) {
+            /* v8 ignore next -- skip non-.ouro dirs: tested via version-detect tests @preserve */
+            if (!entry.isDirectory() || !entry.name.endsWith(".ouro"))
+                continue;
+            const agentJsonPath = path.join(bundlesRoot, entry.name, "agent.json");
+            if (entry.name === "default.ouro" && !fs.existsSync(agentJsonPath))
+                continue;
+            const metaPath = path.join(bundlesRoot, entry.name, "bundle-meta.json");
+            if (!fs.existsSync(metaPath))
+                continue;
+            const raw = fs.readFileSync(metaPath, "utf-8");
+            const meta = JSON.parse(raw);
+            if (meta.runtimeVersion)
+                return meta.runtimeVersion;
+        }
+    }
+    catch {
+        // Best effort — return undefined on any error
+    }
+    return undefined;
+}
+function defaultCleanupStaleSocket(socketPath) {
+    if (fs.existsSync(socketPath)) {
+        fs.unlinkSync(socketPath);
+    }
+}
+function defaultReadHealthUpdatedAt(healthPath) {
+    try {
+        return fs.statSync(healthPath).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultReadRecentDaemonLogLines(lines = 10) {
+    const files = (0, log_tailer_1.discoverLogFiles)({});
+    const recentLines = [];
+    for (const file of files) {
+        recentLines.push(...(0, log_tailer_1.readLastLines)(file, lines, fs.readFileSync));
+    }
+    return recentLines.slice(-lines).map((line) => (0, log_tailer_1.formatLogLine)(line));
+}
+/* v8 ignore start -- CLI npm registry fetch wrapper: integration code @preserve */
+async function defaultFetchCliRegistryJson(timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    try {
+        const res = await fetch("https://registry.npmjs.org/@ouro.bot/cli", {
+            signal: controller.signal,
+        });
+        return res.json();
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new Error(`update check timed out after ${Math.max(1, Math.round(timeoutMs / 1000))}s`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/* v8 ignore stop */
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function defaultSpawnBackgroundCli(argv) {
+    const child = (0, child_process_1.spawn)(process.execPath, argv, {
+        detached: true,
+        stdio: "ignore",
+    });
+    child.unref();
+    return Promise.resolve({ pid: child.pid ?? null });
+}
+function defaultFallbackPendingMessage(command) {
+    const inboxDir = path.join((0, identity_1.getAgentBundlesRoot)(), `${command.to}.ouro`, "inbox");
+    const pendingPath = path.join(inboxDir, "pending.jsonl");
+    const queuedAt = new Date().toISOString();
+    const payload = {
+        from: command.from,
+        to: command.to,
+        content: command.content,
+        priority: command.priority ?? "normal",
+        sessionId: command.sessionId,
+        taskRef: command.taskRef,
+        queuedAt,
+    };
+    fs.mkdirSync(inboxDir, { recursive: true });
+    fs.appendFileSync(pendingPath, `${JSON.stringify(payload)}\n`, "utf-8");
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "daemon",
+        event: "daemon.message_fallback_queued",
+        message: "queued message to pending fallback file",
+        meta: {
+            to: command.to,
+            path: pendingPath,
+            sessionId: command.sessionId ?? null,
+            taskRef: command.taskRef ?? null,
+        },
+    });
+    return pendingPath;
+}
+function currentUserUid() {
+    return process.getuid?.() ?? 0;
+}
+function launchAgentDomain(userUid = currentUserUid()) {
+    return `gui/${userUid}`;
+}
+function writeDaemonBootPlist(socketPath) {
+    const homeDir = os.homedir();
+    const writeDeps = {
+        writeFile: (filePath, content) => fs.writeFileSync(filePath, content, "utf-8"),
+        mkdirp: (dir) => fs.mkdirSync(dir, { recursive: true }),
+        homeDir,
+    };
+    const entryPath = resolveDaemonBootEntryPath(homeDir);
+    /* v8 ignore next -- covered via mock in daemon-cli-defaults.test.ts; v8 on CI attributes the real fs.existsSync branch to the non-mock load @preserve */
+    if (!fs.existsSync(entryPath)) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.entry_path_missing",
+            message: "entryPath does not exist on disk — plist may point to a stale location. Run 'ouro daemon install' from the correct location.",
+            meta: { entryPath },
+        });
+    }
+    return (0, launchd_1.writeLaunchAgentPlist)(writeDeps, {
+        nodePath: process.execPath,
+        entryPath,
+        socketPath,
+        logDir: path.join((0, ouro_version_manager_1.getOuroCliHome)(homeDir), "daemon", "logs"),
+        envPath: process.env.PATH,
+    });
+}
+function isDaemonLaunchAgentLoaded(deps) {
+    const userUid = deps?.userUid ?? currentUserUid();
+    const exec = deps?.exec ?? ((cmd) => { (0, child_process_1.execSync)(cmd, { stdio: "ignore" }); });
+    try {
+        exec(`launchctl print ${launchAgentDomain(userUid)}/${launchd_1.DAEMON_PLIST_LABEL}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readDaemonLaunchAgentPid() {
+    try {
+        const output = (0, child_process_1.execSync)(`launchctl print ${launchAgentDomain()}/${launchd_1.DAEMON_PLIST_LABEL}`, { encoding: "utf-8" });
+        const match = output.match(/^\s*pid = (\d+)/m);
+        return match ? Number(match[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function launchdExec(cmd) {
+    (0, child_process_1.execSync)(cmd, { stdio: "ignore" });
+}
+function bootstrapDaemonLaunchAgent(domain, plistPath) {
+    launchdExec(`launchctl bootstrap ${domain} "${plistPath}"`);
+}
+function kickstartDaemonLaunchAgent(domain) {
+    launchdExec(`launchctl kickstart -k ${domain}/${launchd_1.DAEMON_PLIST_LABEL}`);
+}
+function bootoutDaemonLaunchAgentLabel(userUid) {
+    (0, launchd_1.bootoutLaunchAgentByLabel)({
+        exec: launchdExec,
+        userUid,
+    });
+}
+async function waitForBootstrappedDaemonSocket(socketPath, deps = {}) {
+    const checkSocketAlive = deps.checkSocketAlive ?? socket_client_1.checkDaemonSocketAlive;
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const timeoutMs = deps.timeoutMs ?? 30_000;
+    const initialSettleMs = deps.initialSettleMs ?? 1_000;
+    const pollIntervalMs = deps.pollIntervalMs ?? 250;
+    const requiredConsecutiveAliveChecks = deps.requiredConsecutiveAliveChecks ?? 2;
+    const deadline = now() + timeoutMs;
+    const firstTrustworthyCheckAt = now() + initialSettleMs;
+    let consecutiveAliveChecks = 0;
+    while (now() < deadline) {
+        await sleep(pollIntervalMs);
+        if (now() < firstTrustworthyCheckAt)
+            continue;
+        if (await checkSocketAlive(socketPath)) {
+            consecutiveAliveChecks += 1;
+            if (consecutiveAliveChecks >= requiredConsecutiveAliveChecks)
+                return;
+        }
+        else {
+            consecutiveAliveChecks = 0;
+        }
+    }
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "daemon",
+        event: "daemon.launchd_bootstrap_socket_wait_timeout",
+        message: "launchd bootstrap finished but daemon socket did not settle before timeout",
+        meta: { socketPath },
+    });
+}
+async function startDaemonProcessViaLaunchd(socketPath) {
+    if (process.platform !== "darwin") {
+        return null;
+    }
+    const plistPath = writeDaemonBootPlist(socketPath);
+    const userUid = currentUserUid();
+    const domain = launchAgentDomain(userUid);
+    try {
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.launchd_bootstrap_start",
+            message: "starting daemon launch agent for current login session",
+            meta: { plistPath, label: launchd_1.DAEMON_PLIST_LABEL },
+        });
+        if (isDaemonLaunchAgentLoaded({ exec: launchdExec, userUid })) {
+            try {
+                kickstartDaemonLaunchAgent(domain);
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "daemon",
+                    event: "daemon.launchd_kickstart_recovering",
+                    message: "daemon launch agent kickstart failed; clearing label and bootstrapping from plist",
+                    meta: { plistPath, label: launchd_1.DAEMON_PLIST_LABEL, error: error instanceof Error ? error.message : String(error) },
+                });
+                try {
+                    bootoutDaemonLaunchAgentLabel(userUid);
+                    bootstrapDaemonLaunchAgent(domain, plistPath);
+                }
+                catch (repairError) {
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn",
+                        component: "daemon",
+                        event: "daemon.launchd_kickstart_recovery_error",
+                        message: "daemon launch agent kickstart recovery failed; preserving launchd ownership instead of falling back to detached spawn",
+                        meta: {
+                            plistPath,
+                            label: launchd_1.DAEMON_PLIST_LABEL,
+                            kickstartError: error instanceof Error ? error.message : String(error),
+                            recoveryError: repairError instanceof Error ? repairError.message : String(repairError),
+                        },
+                    });
+                    return { pid: readDaemonLaunchAgentPid() };
+                }
+            }
+        }
+        else {
+            bootstrapDaemonLaunchAgent(domain, plistPath);
+        }
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.launchd_bootstrap_end",
+            message: "daemon launch agent started for current login session",
+            meta: { plistPath, label: launchd_1.DAEMON_PLIST_LABEL },
+        });
+        await waitForBootstrappedDaemonSocket(socketPath);
+        return { pid: readDaemonLaunchAgentPid() };
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.launchd_bootstrap_error",
+            message: "failed to start daemon launch agent for current login session",
+            meta: { plistPath, label: launchd_1.DAEMON_PLIST_LABEL, error: error instanceof Error ? error.message : String(error) },
+        });
+        return null;
+    }
+}
+async function defaultEnsureDaemonBootPersistence(socketPath) {
+    if (process.platform !== "darwin") {
+        return;
+    }
+    const plistPath = writeDaemonBootPlist(socketPath);
+    const userUid = currentUserUid();
+    if (isDaemonLaunchAgentLoaded({ exec: launchdExec, userUid })) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.launchd_bootstrap_skipped_loaded",
+            message: "daemon launch agent already loaded",
+            meta: { plistPath, label: launchd_1.DAEMON_PLIST_LABEL },
+        });
+        return;
+    }
+}
+function defaultPrepareDaemonRuntimeReplacement() {
+    if (process.platform !== "darwin") {
+        return;
+    }
+    (0, launchd_1.bootoutLaunchAgentByLabel)({
+        exec: launchdExec,
+        userUid: process.getuid?.() ?? 0,
+    });
+    // launchctl bootout may return before the old daemon's SIGTERM cleanup has
+    // finished unlinking its Unix socket. Give that cleanup a short chance to
+    // settle before the replacement daemon binds the same socket path.
+    (0, child_process_1.execSync)("/bin/sleep 1", { stdio: "ignore" });
+}
+async function defaultPromptInput(question) {
+    const readline = await Promise.resolve().then(() => __importStar(require("readline/promises")));
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const response = await rl.question(question);
+        return response.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+async function defaultPromptSecret(question) {
+    if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+        throw new Error("vault unlock secret entry requires an interactive terminal so the secret can be hidden. Re-run this command in a terminal and enter the human-chosen secret when prompted.");
+    }
+    const readline = await Promise.resolve().then(() => __importStar(require("readline")));
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: true,
+    });
+    const mutableRl = rl;
+    const originalWriteToOutput = mutableRl._writeToOutput;
+    let muted = false;
+    if (originalWriteToOutput) {
+        mutableRl._writeToOutput = (stringToWrite) => {
+            if (!muted) {
+                originalWriteToOutput.call(rl, stringToWrite);
+            }
+        };
+    }
+    try {
+        const response = await new Promise((resolve) => {
+            rl.question(question, (answer) => {
+                process.stdout.write("\n");
+                resolve(answer);
+            });
+            muted = true;
+        });
+        return response.trim();
+    }
+    finally {
+        if (originalWriteToOutput) {
+            mutableRl._writeToOutput = originalWriteToOutput;
+        }
+        rl.close();
+    }
+}
+function defaultListDiscoveredAgents() {
+    return (0, agent_discovery_1.listEnabledBundleAgents)({
+        bundlesRoot: (0, identity_1.getAgentBundlesRoot)(),
+        readdirSync: fs.readdirSync,
+        readFileSync: fs.readFileSync,
+    });
+}
+// ── Serpent guide (interactive hatch) ──
+/* v8 ignore start -- integration: interactive terminal specialist session @preserve */
+async function defaultRunSerpentGuide() {
+    const { runCliSession } = await Promise.resolve().then(() => __importStar(require("../../senses/cli")));
+    const { setAgentName, setAgentConfigOverride } = await Promise.resolve().then(() => __importStar(require("../identity")));
+    const readlinePromises = await Promise.resolve().then(() => __importStar(require("readline/promises")));
+    const crypto = await Promise.resolve().then(() => __importStar(require("crypto")));
+    // Phase 1: cold CLI — collect provider/credentials with a simple readline
+    const coldRl = readlinePromises.createInterface({ input: process.stdin, output: process.stdout });
+    const coldPrompt = async (q) => {
+        const answer = await coldRl.question(q);
+        return answer.trim();
+    };
+    let providerRaw;
+    let credentials = {};
+    let providerConfig = {};
+    let selectedCredentialPayload = {};
+    const tempDir = path.join(os.tmpdir(), `ouro-hatch-${crypto.randomUUID()}`);
+    try {
+        const discovered = [];
+        const existingBundles = (0, specialist_orchestrator_1.listExistingBundles)((0, identity_1.getAgentBundlesRoot)());
+        const existingBundleCount = existingBundles.length;
+        const hatchVerb = existingBundleCount > 0 ? "let's hatch a new agent." : "let's hatch your first agent.";
+        // Default models per provider (used when entering new credentials)
+        const defaultModels = provider_models_1.DEFAULT_PROVIDER_MODELS;
+        const { pingProvider } = await Promise.resolve().then(() => __importStar(require("../provider-ping")));
+        const installedAgentCreds = await (0, provider_discovery_1.discoverInstalledAgentCredentials)(existingBundles);
+        for (const cred of installedAgentCreds) {
+            discovered.push({
+                ...cred,
+                providerConfig: { model: defaultModels[cred.provider], ...cred.providerConfig },
+            });
+        }
+        // Scan environment variables for API keys using the shared helper
+        const envCreds = (0, provider_discovery_1.scanEnvVarCredentials)(process.env);
+        const envDiscovered = [];
+        for (const cred of envCreds) {
+            // Enrich with default model and first matching env var name (for display)
+            const desc = identity_1.PROVIDER_CREDENTIALS[cred.provider];
+            const firstEnvVar = Object.entries(desc.envVars).find(([envVar]) => process.env[envVar])?.[0] ?? "";
+            const provCfg = { model: defaultModels[cred.provider], ...cred.providerConfig };
+            if (cred.provider === "azure" && cred.credentials.deployment)
+                provCfg.deployment = cred.credentials.deployment;
+            const enriched = { ...cred, providerConfig: provCfg };
+            envDiscovered.push({ ...enriched, envVar: firstEnvVar });
+            discovered.push(enriched);
+        }
+        let welcomed = false;
+        while (true) {
+            if (!welcomed) {
+                process.stdout.write(`\n\ud83d\udc0d welcome to ouroboros! ${hatchVerb}\n`);
+                welcomed = true;
+            }
+            if (discovered.length > 0) {
+                process.stdout.write("i found existing API credentials:\n\n");
+                const credentialOptions = discovered;
+                for (let i = 0; i < credentialOptions.length; i++) {
+                    const model = credentialOptions[i].providerConfig.model || credentialOptions[i].providerConfig.deployment || "";
+                    const modelLabel = model ? `, ${model}` : "";
+                    const envMatch = envDiscovered.find((e) => e.provider === credentialOptions[i].provider && credentialOptions[i].agentName === "env");
+                    const sourceLabel = (0, provider_discovery_1.describeDiscoveredCredentialSource)(credentialOptions[i], envMatch?.envVar);
+                    process.stdout.write(`  ${i + 1}. ${credentialOptions[i].provider}${modelLabel} (${sourceLabel})\n`);
+                }
+                process.stdout.write("\n");
+                const choice = await coldPrompt("use one of these? enter number, or 'new' for a different key, or 'q' to cancel: ");
+                if (["q", "quit", "cancel"].includes(choice.toLowerCase())) {
+                    coldRl.close();
+                    return null;
+                }
+                const idx = parseInt(choice, 10) - 1;
+                if (idx >= 0 && idx < credentialOptions.length) {
+                    providerRaw = credentialOptions[idx].provider;
+                    credentials = credentialOptions[idx].credentials;
+                    providerConfig = credentialOptions[idx].providerConfig;
+                }
+                else {
+                    const pRaw = await coldPrompt("provider (anthropic/azure/minimax/openai-codex/github-copilot): ");
+                    if (!(0, cli_parse_1.isAgentProvider)(pRaw)) {
+                        process.stdout.write("unknown provider. run `ouro hatch` to try again.\n");
+                        coldRl.close();
+                        return null;
+                    }
+                    providerRaw = pRaw;
+                    providerConfig = { model: defaultModels[providerRaw] };
+                    credentials = await (0, auth_flow_1.collectRuntimeAuthCredentials)({ agentName: "SerpentGuide", provider: providerRaw, promptInput: coldPrompt }, {});
+                }
+            }
+            else {
+                process.stdout.write("i need an API key to power our conversation.\n\n");
+                const pRaw = await coldPrompt("provider (anthropic/azure/minimax/openai-codex/github-copilot): ");
+                if (!(0, cli_parse_1.isAgentProvider)(pRaw)) {
+                    process.stdout.write("unknown provider. run `ouro hatch` to try again.\n");
+                    coldRl.close();
+                    return null;
+                }
+                providerRaw = pRaw;
+                providerConfig = { model: defaultModels[providerRaw] };
+                credentials = await (0, auth_flow_1.collectRuntimeAuthCredentials)({ agentName: "SerpentGuide", provider: providerRaw, promptInput: coldPrompt }, {});
+            }
+            selectedCredentialPayload = { ...providerConfig, ...credentials };
+            const pingResult = await pingProvider(providerRaw, selectedCredentialPayload);
+            if (pingResult.ok) {
+                break;
+            }
+            process.stdout.write(`credentials didn't work (${pingResult.message}). `);
+            if (discovered.length > 0) {
+                process.stdout.write("choose another saved credential or enter 'new'.\n\n");
+            }
+            else {
+                process.stdout.write("let's try again.\n\n");
+            }
+        }
+        coldRl.close();
+        process.stdout.write("\n");
+        const split = (0, provider_credentials_1.splitProviderCredentialFields)(providerRaw, selectedCredentialPayload);
+        (0, provider_credentials_1.cacheProviderCredentialRecords)("SerpentGuide", [
+            (0, provider_credentials_1.createProviderCredentialRecord)({
+                provider: providerRaw,
+                credentials: split.credentials,
+                config: split.config,
+                provenance: { source: "manual" },
+            }),
+        ]);
+        // Phase 2: configure runtime for serpent guide
+        const bundleSourceDir = path.resolve(__dirname, "..", "..", "..", "SerpentGuide.ouro");
+        const bundlesRoot = (0, identity_1.getAgentBundlesRoot)();
+        // Suppress non-critical log noise during hatch.
+        const { setRuntimeLogger } = await Promise.resolve().then(() => __importStar(require("../../nerves/runtime")));
+        const { createLogger } = await Promise.resolve().then(() => __importStar(require("../../nerves")));
+        setRuntimeLogger(createLogger({ level: "error" }));
+        // Configure runtime: set agent identity + config override so runAgent
+        // doesn't try to read from ~/AgentBundles/SerpentGuide.ouro/. (As of
+        // Layer 3, SerpentGuide identities live in-repo only — the
+        // `~/AgentBundles/SerpentGuide.ouro/psyche/identities` override path
+        // was removed. The override path is no longer read or honored.)
+        setAgentName("SerpentGuide");
+        // Build specialist system prompt
+        const soulText = (0, specialist_orchestrator_1.loadSoulText)(bundleSourceDir);
+        const identitiesDir = path.join(bundleSourceDir, "psyche", "identities");
+        const identity = (0, specialist_orchestrator_1.pickRandomIdentity)(identitiesDir);
+        // Load identity-specific spinner phrases (falls back to DEFAULT_AGENT_PHRASES)
+        const { loadIdentityPhrases } = await Promise.resolve().then(() => __importStar(require("../hatch/specialist-orchestrator")));
+        const phrases = loadIdentityPhrases(bundleSourceDir, identity.fileName);
+        const resolvedModel = providerConfig.model || providerConfig.deployment || "";
+        setAgentConfigOverride({
+            version: 2,
+            enabled: true,
+            provider: providerRaw,
+            humanFacing: { provider: providerRaw, model: resolvedModel },
+            agentFacing: { provider: providerRaw, model: resolvedModel },
+            phrases,
+        });
+        const systemPrompt = (0, specialist_prompt_1.buildSpecialistSystemPrompt)(soulText, identity.content, existingBundles, {
+            tempDir,
+            provider: providerRaw,
+            model: providerConfig.model ?? "",
+        });
+        // Build specialist tools
+        const specialistTools = (0, specialist_tools_1.getSpecialistTools)();
+        const specialistExecTool = (0, specialist_tools_1.createSpecialistExecTool)({
+            tempDir,
+            credentials: selectedCredentialPayload,
+            provider: providerRaw,
+            bundlesRoot,
+            animationWriter: (text) => process.stdout.write(text),
+            promptSecret: defaultPromptSecret,
+        });
+        // Run the serpent guide session via runCliSession
+        const result = await runCliSession({
+            agentName: "SerpentGuide",
+            tools: specialistTools,
+            execTool: specialistExecTool,
+            exitOnToolCall: "complete_adoption",
+            autoFirstTurn: true,
+            banner: false,
+            disableCommands: true,
+            skipSystemPromptRefresh: true,
+            messages: [
+                { role: "system", content: systemPrompt },
+                { role: "user", content: "hi" },
+            ],
+        });
+        if (result.exitReason === "tool_exit" && result.toolResult) {
+            const parsed = typeof result.toolResult === "string" ? JSON.parse(result.toolResult) : result.toolResult;
+            if (parsed.success && parsed.agentName) {
+                return parsed.agentName;
+            }
+        }
+        return null;
+    }
+    catch (err) {
+        process.stderr.write(`\nouro hatch error: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+        coldRl.close();
+        return null;
+    }
+    finally {
+        // Clear specialist config/identity so the hatched agent gets its own
+        setAgentConfigOverride(null);
+        const { resetProviderRuntime } = await Promise.resolve().then(() => __importStar(require("../core")));
+        resetProviderRuntime();
+        const { resetConfigCache } = await Promise.resolve().then(() => __importStar(require("../config")));
+        resetConfigCache();
+        // Restore default logging
+        const { setRuntimeLogger: restoreLogger } = await Promise.resolve().then(() => __importStar(require("../../nerves/runtime")));
+        restoreLogger(null);
+        // Clean up temp dir if it still exists
+        try {
+            if (fs.existsSync(tempDir)) {
+                fs.rmSync(tempDir, { recursive: true, force: true });
+            }
+        }
+        catch {
+            // Best effort cleanup
+        }
+    }
+}
+/* v8 ignore stop */
+// ── Factory ──
+function createDefaultOuroCliDeps(socketPath = socket_client_1.DEFAULT_DAEMON_SOCKET_PATH) {
+    return {
+        socketPath,
+        sendCommand: (commandSocketPath, command) => (0, socket_client_1.sendDaemonCommand)(commandSocketPath, command, {
+            timeoutMs: command.kind === "daemon.status"
+                ? socket_client_1.DEFAULT_DAEMON_STATUS_TIMEOUT_MS
+                : socket_client_1.DEFAULT_DAEMON_COMMAND_TIMEOUT_MS,
+        }),
+        startDaemonProcess: defaultStartDaemonProcess,
+        startDaemonForFrontend: defaultStartDaemonForFrontend,
+        writeStdout: defaultWriteStdout,
+        setExitCode: (code) => {
+            const current = typeof process.exitCode === "number" ? process.exitCode : 0;
+            process.exitCode = Math.max(current, code);
+        },
+        writeRaw: defaultWriteRaw,
+        isTTY: process.stdout.isTTY === true,
+        checkSocketAlive: socket_client_1.checkDaemonSocketAlive,
+        cleanupStaleSocket: defaultCleanupStaleSocket,
+        fallbackPendingMessage: defaultFallbackPendingMessage,
+        tailLogs: (options) => (0, log_tailer_1.tailLogs)(options),
+        healthFilePath: (0, daemon_health_1.getDefaultHealthPath)(),
+        readHealthState: daemon_health_1.readHealth,
+        readHealthUpdatedAt: defaultReadHealthUpdatedAt,
+        readRecentDaemonLogLines: defaultReadRecentDaemonLogLines,
+        readDaemonStartupTombstone: daemon_tombstone_1.readDaemonTombstone,
+        sleep: defaultSleep,
+        spawnBackgroundCli: defaultSpawnBackgroundCli,
+        now: () => Date.now(),
+        updateCheckTimeoutMs: update_checker_1.CLI_UPDATE_CHECK_TIMEOUT_MS,
+        startupPollIntervalMs: 250,
+        startupStabilityWindowMs: 1_500,
+        startupTimeoutMs: 60_000,
+        startupRetryLimit: 1,
+        isProcessAlive: startup_tui_1.defaultIsProcessAlive,
+        listDiscoveredAgents: defaultListDiscoveredAgents,
+        runHatchFlow: hatch_flow_1.runHatchFlow,
+        promptInput: defaultPromptInput,
+        promptSecret: defaultPromptSecret,
+        runSerpentGuide: defaultRunSerpentGuide,
+        runAuthFlow: auth_flow_1.runRuntimeAuthFlow,
+        registerOuroBundleType: ouro_uti_1.registerOuroBundleUti,
+        installOuroCommand: ouro_path_installer_1.installOuroCommand,
+        /* v8 ignore start -- self-healing: ensures active symlink matches running runtime version @preserve */
+        ensureCurrentVersionInstalled: () => {
+            const linkedVersion = (0, ouro_version_manager_1.getCurrentVersion)({});
+            const version = (0, bundle_manifest_1.getPackageVersion)();
+            if (linkedVersion === version)
+                return;
+            (0, ouro_version_manager_1.ensureLayout)({});
+            const cliHome = (0, ouro_version_manager_1.getOuroCliHome)();
+            const versionEntry = path.join(cliHome, "versions", version, "node_modules", "@ouro.bot", "cli", "dist", "heart", "daemon", "ouro-entry.js");
+            if (!fs.existsSync(versionEntry)) {
+                (0, ouro_version_manager_1.installVersion)(version, {});
+            }
+            (0, ouro_version_manager_1.activateVersion)(version, {});
+            // Self-prune: every successful version activation cleans up old
+            // versions outside the retention window. Without this, every CLI
+            // version ever installed accumulates indefinitely under
+            // ~/.ouro-cli/versions/ — the user observed installs going back to
+            // alpha.85 from March 20 (~100MB of dead node_modules trees).
+            // pruneOldVersions keeps the 5 most recent + the active + the
+            // previous version, so rollback stays one command away.
+            (0, ouro_version_manager_1.pruneOldVersions)(undefined, {});
+        },
+        /* v8 ignore stop */
+        /* v8 ignore start -- CLI version management defaults: integration code @preserve */
+        checkForCliUpdate: async () => {
+            const { checkForUpdate } = await Promise.resolve().then(() => __importStar(require("../versioning/update-checker")));
+            return checkForUpdate((0, bundle_manifest_1.getPackageVersion)(), {
+                fetchRegistryJson: () => defaultFetchCliRegistryJson(update_checker_1.CLI_UPDATE_CHECK_TIMEOUT_MS),
+                distTag: update_checker_1.CLI_UPDATE_DIST_TAG,
+            });
+        },
+        readVersionIntent: () => (0, version_intent_1.readVersionIntent)(),
+        writeVersionIntent: (intent) => (0, version_intent_1.writeVersionIntent)(intent),
+        installCliVersion: async (version) => { (0, ouro_version_manager_1.installVersion)(version, {}); },
+        validateCliVersionForActivation: (version) => (0, ouro_version_manager_1.validateInstalledVersionForActivation)(version, {}),
+        activateCliVersion: (version) => {
+            (0, ouro_version_manager_1.activateVersion)(version, {});
+            // Same self-prune as ensureCurrentVersionInstalled — fires from the
+            // checkForCliUpdate path 1 (in-process update detected → activate
+            // → re-exec). Without this, the path 1 code path never triggers
+            // a prune.
+            (0, ouro_version_manager_1.pruneOldVersions)(undefined, {});
+        },
+        getCurrentCliVersion: () => (0, ouro_version_manager_1.getCurrentVersion)({}),
+        getPreviousCliVersion: () => (0, ouro_version_manager_1.getPreviousVersion)({}),
+        listCliVersions: () => (0, ouro_version_manager_1.listInstalledVersions)({}),
+        reExecFromNewVersion: (reArgs) => {
+            const entry = path.join((0, ouro_version_manager_1.getOuroCliHome)(), "CurrentVersion", "node_modules", "@ouro.bot", "cli", "dist", "heart", "daemon", "ouro-entry.js");
+            require("child_process").execFileSync("node", [entry, ...reArgs], { stdio: "inherit" });
+            process.exit(0);
+        },
+        /* v8 ignore stop */
+        syncGlobalOuroBotWrapper: ouro_bot_global_installer_1.syncGlobalOuroBotWrapper,
+        pruneDaemonLogs: logs_prune_1.pruneDaemonLogs,
+        ensureSkillManagement: skill_management_installer_1.ensureSkillManagement,
+        prepareDaemonRuntimeReplacement: defaultPrepareDaemonRuntimeReplacement,
+        ensureDaemonBootPersistence: defaultEnsureDaemonBootPersistence,
+        /* v8 ignore start -- dev-mode defaults: tests inject mocks for mode detection and binary resolution @preserve */
+        detectMode: () => (0, runtime_mode_1.detectRuntimeMode)((0, identity_1.getRepoRoot)()),
+        getInstalledBinaryPath: () => {
+            const cliHome = (0, ouro_version_manager_1.getOuroCliHome)();
+            const binaryPath = path.join(cliHome, "bin", "ouro");
+            return fs.existsSync(binaryPath) ? binaryPath : null;
+        },
+        execInstalledBinary: (binaryPath, binArgs) => {
+            const { execFileSync } = require("child_process");
+            execFileSync(binaryPath, binArgs, { stdio: "inherit" });
+            process.exit(0);
+        },
+        /* v8 ignore stop */
+        /* v8 ignore next 3 -- integration: launches interactive CLI session @preserve */
+        startChat: async (agentName) => {
+            const { main } = await Promise.resolve().then(() => __importStar(require("../../senses/cli")));
+            await main(agentName);
+        },
+        scanSessions: async (agentName) => {
+            const agentRoot = (0, identity_1.getAgentRoot)(agentName);
+            return (0, session_activity_1.listSessionActivity)({
+                sessionsDir: path.join(agentRoot, "state", "sessions"),
+                friendsDir: path.join(agentRoot, "friends"),
+                agentName,
+            }).map((entry) => ({
+                friendId: entry.friendId,
+                friendName: entry.friendName,
+                channel: entry.channel,
+                lastActivity: entry.lastActivityAt,
+            }));
+        },
+    };
+}