@ouro.bot/cli 0.1.0-alpha.12 → 0.1.0-alpha.121

package/dist/heart/daemon/daemon-entry.js

@@ -1,6 +1,41 @@
 #!/usr/bin/env node
 "use strict";
+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 });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
 const process_manager_1 = require("./process-manager");
 const daemon_1 = require("./daemon");
 const runtime_1 = require("../../nerves/runtime");
@@ -9,6 +44,9 @@ const health_monitor_1 = require("./health-monitor");
 const task_scheduler_1 = require("./task-scheduler");
 const runtime_logging_1 = require("./runtime-logging");
 const sense_manager_1 = require("./sense-manager");
+const agent_discovery_1 = require("./agent-discovery");
+const identity_1 = require("../identity");
+const runtime_mode_1 = require("./runtime-mode");
 function parseSocketPath(argv) {
     const socketIndex = argv.indexOf("--socket");
     if (socketIndex >= 0) {
@@ -20,13 +58,15 @@ function parseSocketPath(argv) {
 }
 const socketPath = parseSocketPath(process.argv);
 (0, runtime_logging_1.configureDaemonRuntimeLogger)("daemon");
+const entryPath = path.resolve(__dirname, "daemon-entry.js");
+const mode = (0, runtime_mode_1.detectRuntimeMode)((0, identity_1.getRepoRoot)());
 (0, runtime_1.emitNervesEvent)({
     component: "daemon",
     event: "daemon.entry_start",
     message: "starting daemon entrypoint",
-    meta: { socketPath },
+    meta: { socketPath, entryPath, mode },
 });
-const managedAgents = ["ouroboros", "slugger"];
+const managedAgents = (0, agent_discovery_1.listEnabledBundleAgents)();
 const processManager = new process_manager_1.DaemonProcessManager({
     agents: managedAgents.map((agent) => ({
         name: agent,
@@ -34,6 +74,7 @@ const processManager = new process_manager_1.DaemonProcessManager({
         channel: "inner-dialog",
         autoStart: true,
     })),
+    existsSync: fs.existsSync,
 });
 const scheduler = new task_scheduler_1.TaskDrivenScheduler({
     agents: [...managedAgents],

package/dist/heart/daemon/daemon-runtime-sync.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureCurrentDaemonRuntime = ensureCurrentDaemonRuntime;
+const runtime_1 = require("../../nerves/runtime");
+function isKnownVersion(version) {
+    return version !== "unknown" && version.trim().length > 0;
+}
+function isKnownRuntimeValue(value) {
+    return typeof value === "string" && value.trim().length > 0 && value !== "unknown";
+}
+function formatErrorReason(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function normalizeRuntimeIdentity(value) {
+    return {
+        version: typeof value.version === "string" ? value.version : "unknown",
+        lastUpdated: typeof value.lastUpdated === "string" ? value.lastUpdated : "unknown",
+        repoRoot: typeof value.repoRoot === "string" ? value.repoRoot : "unknown",
+        configFingerprint: typeof value.configFingerprint === "string" ? value.configFingerprint : "unknown",
+    };
+}
+async function readRunningRuntimeIdentity(deps) {
+    if (!deps.fetchRunningRuntimeMetadata) {
+        return normalizeRuntimeIdentity({
+            version: await deps.fetchRunningVersion(),
+        });
+    }
+    const metadata = normalizeRuntimeIdentity(await deps.fetchRunningRuntimeMetadata());
+    if (isKnownVersion(metadata.version))
+        return metadata;
+    return normalizeRuntimeIdentity({
+        ...metadata,
+        version: await deps.fetchRunningVersion(),
+    });
+}
+function collectRuntimeDriftReasons(local, running) {
+    const reasons = [];
+    const comparableVersions = isKnownVersion(local.version) && isKnownVersion(running.version);
+    if (comparableVersions && local.version !== running.version) {
+        reasons.push({ key: "version", label: "version", local: local.version, running: running.version });
+    }
+    if (comparableVersions && isKnownRuntimeValue(local.lastUpdated) && isKnownRuntimeValue(running.lastUpdated) && local.lastUpdated !== running.lastUpdated) {
+        reasons.push({ key: "lastUpdated", label: "last updated", local: local.lastUpdated, running: running.lastUpdated });
+    }
+    if (isKnownRuntimeValue(local.repoRoot) && isKnownRuntimeValue(running.repoRoot) && local.repoRoot !== running.repoRoot) {
+        reasons.push({ key: "repoRoot", label: "code path", local: local.repoRoot, running: running.repoRoot });
+    }
+    if (isKnownRuntimeValue(local.configFingerprint)
+        && isKnownRuntimeValue(running.configFingerprint)
+        && local.configFingerprint !== running.configFingerprint) {
+        reasons.push({
+            key: "configFingerprint",
+            label: "config fingerprint",
+            local: local.configFingerprint,
+            running: running.configFingerprint,
+        });
+    }
+    return reasons;
+}
+function formatRuntimeValue(reason) {
+    if (reason.key === "configFingerprint") {
+        return `${reason.running.slice(0, 12)} -> ${reason.local.slice(0, 12)}`;
+    }
+    return `${reason.running} -> ${reason.local}`;
+}
+function formatRuntimeDriftSummary(reasons) {
+    return reasons.map((reason) => `${reason.label} ${formatRuntimeValue(reason)}`).join("; ");
+}
+async function ensureCurrentDaemonRuntime(deps) {
+    const localRuntime = normalizeRuntimeIdentity({
+        version: deps.localVersion,
+        lastUpdated: deps.localLastUpdated,
+        repoRoot: deps.localRepoRoot,
+        configFingerprint: deps.localConfigFingerprint,
+    });
+    try {
+        const runningRuntime = await readRunningRuntimeIdentity(deps);
+        const runningVersion = runningRuntime.version;
+        const driftReasons = collectRuntimeDriftReasons(localRuntime, runningRuntime);
+        let result;
+        if (driftReasons.length > 0) {
+            const includesVersionDrift = driftReasons.some((entry) => entry.key === "version");
+            const driftSummary = formatRuntimeDriftSummary(driftReasons);
+            try {
+                await deps.stopDaemon();
+            }
+            catch (error) {
+                const reason = formatErrorReason(error);
+                result = {
+                    alreadyRunning: true,
+                    message: includesVersionDrift
+                        ? `daemon already running (${deps.socketPath}; could not replace stale daemon ${runningVersion} -> ${deps.localVersion}: ${reason})`
+                        : `daemon already running (${deps.socketPath}; could not replace drifted daemon ${driftSummary}: ${reason})`,
+                };
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "daemon",
+                    event: "daemon.runtime_sync_decision",
+                    message: "evaluated daemon runtime sync outcome",
+                    meta: {
+                        socketPath: deps.socketPath,
+                        localVersion: deps.localVersion,
+                        localLastUpdated: localRuntime.lastUpdated,
+                        localRepoRoot: localRuntime.repoRoot,
+                        localConfigFingerprint: localRuntime.configFingerprint,
+                        runningVersion,
+                        runningLastUpdated: runningRuntime.lastUpdated,
+                        runningRepoRoot: runningRuntime.repoRoot,
+                        runningConfigFingerprint: runningRuntime.configFingerprint,
+                        action: "stale_replace_failed",
+                        driftKeys: driftReasons.map((entry) => entry.key),
+                        reason,
+                    },
+                });
+                return result;
+            }
+            deps.cleanupStaleSocket(deps.socketPath);
+            const started = await deps.startDaemonProcess(deps.socketPath);
+            result = {
+                alreadyRunning: false,
+                message: includesVersionDrift
+                    ? `restarted stale daemon from ${runningVersion} to ${deps.localVersion} (pid ${started.pid ?? "unknown"})`
+                    : `restarted drifted daemon (${driftSummary}) (pid ${started.pid ?? "unknown"})`,
+            };
+            (0, runtime_1.emitNervesEvent)({
+                component: "daemon",
+                event: "daemon.runtime_sync_decision",
+                message: "evaluated daemon runtime sync outcome",
+                meta: {
+                    socketPath: deps.socketPath,
+                    localVersion: deps.localVersion,
+                    localLastUpdated: localRuntime.lastUpdated,
+                    localRepoRoot: localRuntime.repoRoot,
+                    localConfigFingerprint: localRuntime.configFingerprint,
+                    runningVersion,
+                    runningLastUpdated: runningRuntime.lastUpdated,
+                    runningRepoRoot: runningRuntime.repoRoot,
+                    runningConfigFingerprint: runningRuntime.configFingerprint,
+                    action: "stale_restarted",
+                    driftKeys: driftReasons.map((entry) => entry.key),
+                    pid: started.pid ?? null,
+                },
+            });
+            return result;
+        }
+        if (!isKnownVersion(localRuntime.version) || !isKnownVersion(runningVersion)) {
+            result = {
+                alreadyRunning: true,
+                message: `daemon already running (${deps.socketPath}; unable to verify version)`,
+            };
+            (0, runtime_1.emitNervesEvent)({
+                component: "daemon",
+                event: "daemon.runtime_sync_decision",
+                message: "evaluated daemon runtime sync outcome",
+                meta: {
+                    socketPath: deps.socketPath,
+                    localVersion: deps.localVersion,
+                    localLastUpdated: localRuntime.lastUpdated,
+                    localRepoRoot: localRuntime.repoRoot,
+                    localConfigFingerprint: localRuntime.configFingerprint,
+                    runningVersion,
+                    runningLastUpdated: runningRuntime.lastUpdated,
+                    runningRepoRoot: runningRuntime.repoRoot,
+                    runningConfigFingerprint: runningRuntime.configFingerprint,
+                    action: "unknown_version",
+                },
+            });
+            return result;
+        }
+    }
+    catch (error) {
+        const reason = formatErrorReason(error);
+        const result = {
+            alreadyRunning: true,
+            message: `daemon already running (${deps.socketPath}; unable to verify version: ${reason})`,
+        };
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.runtime_sync_decision",
+            message: "evaluated daemon runtime sync outcome",
+            meta: {
+                socketPath: deps.socketPath,
+                localVersion: deps.localVersion,
+                localLastUpdated: localRuntime.lastUpdated,
+                localRepoRoot: localRuntime.repoRoot,
+                localConfigFingerprint: localRuntime.configFingerprint,
+                action: "status_lookup_failed",
+                reason,
+            },
+        });
+        return result;
+    }
+    const result = {
+        alreadyRunning: true,
+        message: `daemon already running (${deps.socketPath})`,
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.runtime_sync_decision",
+        message: "evaluated daemon runtime sync outcome",
+        meta: {
+            socketPath: deps.socketPath,
+            localVersion: deps.localVersion,
+            localLastUpdated: localRuntime.lastUpdated,
+            localRepoRoot: localRuntime.repoRoot,
+            localConfigFingerprint: localRuntime.configFingerprint,
+            action: "already_current",
+        },
+    });
+    return result;
+}

package/dist/heart/daemon/daemon.js

@@ -34,11 +34,71 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OuroDaemon = void 0;
+exports.killOrphanProcesses = killOrphanProcesses;
 const fs = __importStar(require("fs"));
 const net = __importStar(require("net"));
 const path = __importStar(require("path"));
 const identity_1 = require("../identity");
 const runtime_1 = require("../../nerves/runtime");
+const runtime_metadata_1 = require("./runtime-metadata");
+const runtime_mode_1 = require("./runtime-mode");
+const update_hooks_1 = require("./update-hooks");
+const bundle_meta_1 = require("./hooks/bundle-meta");
+const bundle_manifest_1 = require("../../mind/bundle-manifest");
+const update_checker_1 = require("./update-checker");
+const staged_restart_1 = require("./staged-restart");
+const child_process_1 = require("child_process");
+const pending_1 = require("../../mind/pending");
+const channel_1 = require("../../mind/friends/channel");
+const mcp_manager_1 = require("../../repertoire/mcp-manager");
+/**
+ * Kill ALL orphaned ouro processes from previous daemon instances.
+ * On each `ouro up`, old daemon AND agent processes persist because:
+ * - Daemons are spawned detached and never killed on restart
+ * - Each old daemon keeps respawning agents from its own (stale) code
+ * This scans for both daemon-entry.js and agent-entry.js processes
+ * and kills everything except the current process.
+ */
+/* v8 ignore start -- orphan cleanup: uses ps/kill, tested via deployment @preserve */
+function killOrphanProcesses() {
+    try {
+        const myPid = process.pid;
+        const result = (0, child_process_1.execSync)("ps -eo pid,command", { encoding: "utf-8", timeout: 5000 });
+        const pidsToKill = [];
+        for (const line of result.split("\n")) {
+            if (!line.includes("agent-entry.js") && !line.includes("daemon-entry.js") && !line.includes("-entry.js --agent"))
+                continue;
+            const trimmed = line.trim();
+            const pid = parseInt(trimmed, 10);
+            if (isNaN(pid) || pid === myPid)
+                continue;
+            pidsToKill.push(pid);
+        }
+        if (pidsToKill.length > 0) {
+            for (const pid of pidsToKill) {
+                try {
+                    process.kill(pid, "SIGTERM");
+                }
+                catch { /* already exited */ }
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "daemon",
+                event: "daemon.orphan_cleanup",
+                message: `killed ${pidsToKill.length} orphaned ouro processes`,
+                meta: { pids: pidsToKill },
+            });
+        }
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.orphan_cleanup_error",
+            message: "failed to clean up orphaned ouro processes",
+            meta: { error: error instanceof Error ? error.message : String(error) },
+        });
+    }
+}
 function buildWorkerRows(snapshots) {
     return snapshots.map((snapshot) => ({
         agent: snapshot.name,
@@ -106,11 +166,54 @@ class OuroDaemon {
             message: "starting daemon server",
             meta: { socketPath: this.socketPath },
         });
+        // Register update hooks and apply pending updates before starting agents
+        (0, update_hooks_1.registerUpdateHook)(bundle_meta_1.bundleMetaHook);
+        const currentVersion = (0, bundle_manifest_1.getPackageVersion)();
+        await (0, update_hooks_1.applyPendingUpdates)(this.bundlesRoot, currentVersion);
+        // Start periodic update checker (polls npm registry every 30 minutes)
+        const bundlesRoot = this.bundlesRoot;
+        const daemon = this;
+        (0, update_checker_1.startUpdateChecker)({
+            currentVersion,
+            deps: {
+                distTag: "alpha",
+                fetchRegistryJson: /* v8 ignore next -- integration: real HTTP fetch @preserve */ async () => {
+                    const res = await fetch("https://registry.npmjs.org/@ouro.bot/cli");
+                    return res.json();
+                },
+            },
+            onUpdate: /* v8 ignore start -- integration: real npm install + process spawn @preserve */ async (result) => {
+                if (!result.latestVersion)
+                    return;
+                await (0, staged_restart_1.performStagedRestart)(result.latestVersion, {
+                    execSync: (cmd) => (0, child_process_1.execSync)(cmd, { stdio: "inherit" }),
+                    spawnSync: child_process_1.spawnSync,
+                    resolveNewCodePath: (_version) => {
+                        try {
+                            const resolved = (0, child_process_1.execSync)(`node -e "console.log(require.resolve('@ouro.bot/cli/package.json'))"`, { encoding: "utf-8" }).trim();
+                            return resolved ? path.dirname(resolved) : null;
+                        }
+                        catch {
+                            return null;
+                        }
+                    },
+                    gracefulShutdown: () => daemon.stop(),
+                    nodePath: process.execPath,
+                    bundlesRoot,
+                });
+            },
+            /* v8 ignore stop */
+        });
+        // Pre-initialize MCP connections so they're ready for the first command (non-blocking)
+        /* v8 ignore next -- catch callback: getSharedMcpManager logs errors internally @preserve */
+        (0, mcp_manager_1.getSharedMcpManager)().catch(() => { });
+        killOrphanProcesses();
         await this.processManager.startAutoStartAgents();
         await this.senseManager?.startAutoStartSenses();
         this.scheduler.start?.();
         await this.scheduler.reconcile?.();
         await this.drainPendingBundleMessages();
+        await this.drainPendingSenseMessages();
         if (fs.existsSync(this.socketPath)) {
             fs.unlinkSync(this.socketPath);
         }
@@ -186,6 +289,93 @@ class OuroDaemon {
             fs.writeFileSync(pendingPath, next, "utf-8");
         }
     }
+    /** Drains per-sense pending dirs for always-on senses across all agents. */
+    static ALWAYS_ON_SENSES = new Set((0, channel_1.getAlwaysOnSenseNames)());
+    async drainPendingSenseMessages() {
+        if (!fs.existsSync(this.bundlesRoot))
+            return;
+        let bundleDirs;
+        try {
+            bundleDirs = fs.readdirSync(this.bundlesRoot, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const bundleDir of bundleDirs) {
+            if (!bundleDir.isDirectory() || !bundleDir.name.endsWith(".ouro"))
+                continue;
+            const agentName = bundleDir.name.replace(/\.ouro$/, "");
+            const pendingRoot = path.join(this.bundlesRoot, bundleDir.name, "state", "pending");
+            if (!fs.existsSync(pendingRoot))
+                continue;
+            let friendDirs;
+            try {
+                friendDirs = fs.readdirSync(pendingRoot, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const friendDir of friendDirs) {
+                if (!friendDir.isDirectory())
+                    continue;
+                const friendPath = path.join(pendingRoot, friendDir.name);
+                let channelDirs;
+                try {
+                    channelDirs = fs.readdirSync(friendPath, { withFileTypes: true });
+                }
+                catch {
+                    continue;
+                }
+                for (const channelDir of channelDirs) {
+                    if (!channelDir.isDirectory())
+                        continue;
+                    if (!OuroDaemon.ALWAYS_ON_SENSES.has(channelDir.name))
+                        continue;
+                    const channelPath = path.join(friendPath, channelDir.name);
+                    let keyDirs;
+                    try {
+                        keyDirs = fs.readdirSync(channelPath, { withFileTypes: true });
+                    }
+                    catch {
+                        continue;
+                    }
+                    for (const keyDir of keyDirs) {
+                        if (!keyDir.isDirectory())
+                            continue;
+                        const leafDir = path.join(channelPath, keyDir.name);
+                        const messages = (0, pending_1.drainPending)(leafDir);
+                        for (const msg of messages) {
+                            try {
+                                await this.router.send({
+                                    from: msg.from,
+                                    to: agentName,
+                                    content: msg.content,
+                                    priority: "normal",
+                                });
+                            }
+                            catch {
+                                // Best-effort delivery — log and continue
+                            }
+                        }
+                        if (messages.length > 0) {
+                            (0, runtime_1.emitNervesEvent)({
+                                component: "daemon",
+                                event: "daemon.startup_sense_drain",
+                                message: "drained pending sense messages on startup",
+                                meta: {
+                                    agent: agentName,
+                                    channel: channelDir.name,
+                                    friendId: friendDir.name,
+                                    key: keyDir.name,
+                                    count: messages.length,
+                                },
+                            });
+                        }
+                    }
+                }
+            }
+        }
+    }
     async stop() {
         (0, runtime_1.emitNervesEvent)({
             component: "daemon",
@@ -193,6 +383,8 @@ class OuroDaemon {
             message: "stopping daemon server",
             meta: { socketPath: this.socketPath },
         });
+        (0, update_checker_1.stopUpdateChecker)();
+        (0, mcp_manager_1.shutdownSharedMcpManager)();
         this.scheduler.stop?.();
         await this.processManager.stopAll();
         await this.senseManager?.stopAll();
@@ -237,13 +429,17 @@ class OuroDaemon {
                 const snapshots = this.processManager.listAgentSnapshots();
                 const workers = buildWorkerRows(snapshots);
                 const senses = this.senseManager?.listSenseRows() ?? [];
+                const repoRoot = (0, identity_1.getRepoRoot)();
                 const data = {
                     overview: {
                         daemon: "running",
                         health: workers.every((worker) => worker.status === "running") ? "ok" : "warn",
                         socketPath: this.socketPath,
+                        ...(0, runtime_metadata_1.getRuntimeMetadata)(),
                         workerCount: workers.length,
                         senseCount: senses.length,
+                        entryPath: path.join(repoRoot, "dist", "heart", "daemon", "daemon-entry.js"),
+                        mode: (0, runtime_mode_1.detectRuntimeMode)(repoRoot),
                     },
                     workers,
                     senses,
@@ -264,7 +460,7 @@ class OuroDaemon {
                     ok: true,
                     summary: "logs: use `ouro logs` to tail daemon and agent output",
                     message: "log streaming available via ouro logs",
-                    data: { logDir: "~/.agentstate/daemon/logs" },
+                    data: { logDir: "~/AgentBundles/<agent>.ouro/state/daemon/logs" },
                 };
             case "agent.start":
                 await this.processManager.startAgent(command.agent);
@@ -306,6 +502,13 @@ class OuroDaemon {
                     data: messages,
                 };
             }
+            case "inner.wake":
+                await this.processManager.startAgent(command.agent);
+                this.processManager.sendToAgent?.(command.agent, { type: "message" });
+                return {
+                    ok: true,
+                    message: `woke inner dialog for ${command.agent}`,
+                };
             case "chat.connect":
                 await this.processManager.startAgent(command.agent);
                 return {
@@ -328,6 +531,28 @@ class OuroDaemon {
                     data: receipt,
                 };
             }
+            case "mcp.list": {
+                const mcpManager = await (0, mcp_manager_1.getSharedMcpManager)();
+                if (!mcpManager) {
+                    return { ok: true, data: [], message: "no MCP servers configured" };
+                }
+                return { ok: true, data: mcpManager.listAllTools() };
+            }
+            case "mcp.call": {
+                const mcpCallManager = await (0, mcp_manager_1.getSharedMcpManager)();
+                if (!mcpCallManager) {
+                    return { ok: false, error: "no MCP servers configured" };
+                }
+                try {
+                    const parsedArgs = command.args ? JSON.parse(command.args) : {};
+                    const result = await mcpCallManager.callTool(command.server, command.tool, parsedArgs);
+                    return { ok: true, data: result };
+                }
+                catch (error) {
+                    /* v8 ignore next -- defensive: callTool errors are always Error instances @preserve */
+                    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+                }
+            }
             case "hatch.start":
                 return {
                     ok: true,

package/dist/heart/daemon/hatch-animation.js

@@ -20,9 +20,16 @@ async function playHatchAnimation(hatchlingName, writer) {
         meta: { hatchlingName },
     });
     const write = writer ?? ((text) => process.stderr.write(text));
+    // Total animation time randomized between 3–5 seconds
+    const totalMs = 3000 + Math.floor(Math.random() * 2000);
+    const eggPhase = Math.floor(totalMs * 0.4);
+    const dotsPhase = Math.floor(totalMs * 0.4);
+    const revealPause = totalMs - eggPhase - dotsPhase;
     write(`\n  ${EGG}`);
-    await wait(400);
+    await wait(eggPhase);
     write(DOTS);
-    await wait(400);
-    write(`${SNAKE} \x1b[1m${hatchlingName}\x1b[0m\n\n`);
+    await wait(dotsPhase);
+    write(`${SNAKE} \x1b[1m${hatchlingName}\x1b[0m`);
+    await wait(revealPause);
+    write("\n\n");
 }