@ouro.bot/cli 0.1.0-alpha.20 → 0.1.0-alpha.22

package/changelog.json

@@ -0,0 +1,26 @@
+{
+  "_note": "This changelog is maintained as part of the PR/version-bump workflow. Human-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
+  "versions": [
+    {
+      "version": "0.1.0-alpha.22",
+      "changes": [
+        "You now know your runtime version and can see when it changed. Your system prompt shows your current version and what you were running before, so you can track what's new.",
+        "A changelog file is now shipped with the runtime. You can read it to understand exactly what changed between versions.",
+        "When the runtime updates, your bundle-meta.json is automatically updated with the new version info. Your previous version is preserved so you always know your version history.",
+        "The daemon can now check for new versions of the runtime on npm and auto-update with a staged restart that validates hooks before switching to new code.",
+        "The daemon can now be managed as a macOS LaunchAgent for automatic restart on crash.",
+        "The daemon now auto-syncs the ouro.bot npm wrapper version on startup to keep the npx entry point current."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.21",
+      "changes": [
+        "You now know your runtime version and can see when it changed. Your system prompt shows your current version and what you were running before, so you can track what's new.",
+        "A changelog file is now shipped with the runtime. You can read it to understand exactly what changed between versions.",
+        "When the runtime updates, your bundle-meta.json is automatically updated with the new version info. Your previous version is preserved so you always know your version history.",
+        "The daemon can now check for new versions of the runtime on npm and auto-update with a staged restart that validates hooks before switching to new code.",
+        "The daemon can now be managed as a macOS LaunchAgent for automatic restart on crash."
+      ]
+    }
+  ]
+}

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

@@ -55,6 +55,7 @@ const specialist_orchestrator_1 = require("./specialist-orchestrator");
 const specialist_prompt_1 = require("./specialist-prompt");
 const specialist_tools_1 = require("./specialist-tools");
 const runtime_metadata_1 = require("./runtime-metadata");
+const daemon_runtime_sync_1 = require("./daemon-runtime-sync");
 function stringField(value) {
     return typeof value === "string" ? value : null;
 }
@@ -195,10 +196,21 @@ function formatDaemonStatusOutput(response, fallback) {
 async function ensureDaemonRunning(deps) {
     const alive = await deps.checkSocketAlive(deps.socketPath);
     if (alive) {
-        return {
-            alreadyRunning: true,
-            message: `daemon already running (${deps.socketPath})`,
-        };
+        const localRuntime = (0, runtime_metadata_1.getRuntimeMetadata)();
+        return (0, daemon_runtime_sync_1.ensureCurrentDaemonRuntime)({
+            socketPath: deps.socketPath,
+            localVersion: localRuntime.version,
+            fetchRunningVersion: async () => {
+                const status = await deps.sendCommand(deps.socketPath, { kind: "daemon.status" });
+                const payload = parseStatusPayload(status.data);
+                return payload?.overview.version ?? "unknown";
+            },
+            stopDaemon: async () => {
+                await deps.sendCommand(deps.socketPath, { kind: "daemon.stop" });
+            },
+            cleanupStaleSocket: deps.cleanupStaleSocket,
+            startDaemonProcess: deps.startDaemonProcess,
+        });
     }
     deps.cleanupStaleSocket(deps.socketPath);
     const started = await deps.startDaemonProcess(deps.socketPath);

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

@@ -0,0 +1,90 @@
+"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 formatErrorReason(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function ensureCurrentDaemonRuntime(deps) {
+    try {
+        const runningVersion = await deps.fetchRunningVersion();
+        let result;
+        if (isKnownVersion(deps.localVersion) &&
+            isKnownVersion(runningVersion) &&
+            runningVersion !== deps.localVersion) {
+            try {
+                await deps.stopDaemon();
+            }
+            catch (error) {
+                const reason = formatErrorReason(error);
+                result = {
+                    alreadyRunning: true,
+                    message: `daemon already running (${deps.socketPath}; could not replace stale daemon ${runningVersion} -> ${deps.localVersion}: ${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, runningVersion, action: "stale_replace_failed", reason },
+                });
+                return result;
+            }
+            deps.cleanupStaleSocket(deps.socketPath);
+            const started = await deps.startDaemonProcess(deps.socketPath);
+            result = {
+                alreadyRunning: false,
+                message: `restarted stale daemon from ${runningVersion} to ${deps.localVersion} (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, runningVersion, action: "stale_restarted", pid: started.pid ?? null },
+            });
+            return result;
+        }
+        if (!isKnownVersion(deps.localVersion) || !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, runningVersion, 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, 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, action: "already_current" },
+    });
+    return result;
+}

package/dist/heart/daemon/daemon.js

@@ -40,6 +40,9 @@ const path = __importStar(require("path"));
 const identity_1 = require("../identity");
 const runtime_1 = require("../../nerves/runtime");
 const runtime_metadata_1 = require("./runtime-metadata");
+const update_hooks_1 = require("./update-hooks");
+const bundle_meta_1 = require("./hooks/bundle-meta");
+const bundle_manifest_1 = require("../../mind/bundle-manifest");
 function buildWorkerRows(snapshots) {
     return snapshots.map((snapshot) => ({
         agent: snapshot.name,
@@ -107,6 +110,9 @@ 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);
+        await (0, update_hooks_1.applyPendingUpdates)(this.bundlesRoot, (0, bundle_manifest_1.getPackageVersion)());
         await this.processManager.startAutoStartAgents();
         await this.senseManager?.startAutoStartSenses();
         this.scheduler.start?.();

package/dist/heart/daemon/hooks/bundle-meta.js

@@ -0,0 +1,92 @@
+"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 });
+exports.bundleMetaHook = bundleMetaHook;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../../../nerves/runtime");
+async function bundleMetaHook(ctx) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.bundle_meta_hook_start",
+        message: "running bundle-meta update hook",
+        meta: { agentRoot: ctx.agentRoot, currentVersion: ctx.currentVersion },
+    });
+    const metaPath = path.join(ctx.agentRoot, "bundle-meta.json");
+    let existing;
+    try {
+        if (fs.existsSync(metaPath)) {
+            const raw = fs.readFileSync(metaPath, "utf-8");
+            existing = JSON.parse(raw);
+        }
+    }
+    catch {
+        // Malformed JSON -- treat as missing, will overwrite with fresh
+        existing = undefined;
+    }
+    const updated = {
+        runtimeVersion: ctx.currentVersion,
+        bundleSchemaVersion: existing?.bundleSchemaVersion ?? 1,
+        lastUpdated: new Date().toISOString(),
+    };
+    // Save old runtimeVersion as previousRuntimeVersion (if there was one)
+    if (existing?.runtimeVersion) {
+        updated.previousRuntimeVersion = existing.runtimeVersion;
+    }
+    try {
+        fs.writeFileSync(metaPath, JSON.stringify(updated, null, 2) + "\n", "utf-8");
+    }
+    catch (err) {
+        const errorMessage = err instanceof Error ? err.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(err);
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.bundle_meta_hook_error",
+            message: "bundle-meta hook write failed",
+            meta: { agentRoot: ctx.agentRoot, error: errorMessage },
+        });
+        return { ok: false, error: errorMessage };
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.bundle_meta_hook_end",
+        message: "bundle-meta updated",
+        meta: {
+            agentRoot: ctx.agentRoot,
+            runtimeVersion: updated.runtimeVersion,
+            previousRuntimeVersion: updated.previousRuntimeVersion,
+        },
+    });
+    return { ok: true };
+}

package/dist/heart/daemon/launchd.js

@@ -0,0 +1,134 @@
+"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 });
+exports.DAEMON_PLIST_LABEL = void 0;
+exports.generateDaemonPlist = generateDaemonPlist;
+exports.installLaunchAgent = installLaunchAgent;
+exports.uninstallLaunchAgent = uninstallLaunchAgent;
+exports.isDaemonInstalled = isDaemonInstalled;
+const path = __importStar(require("path"));
+const runtime_1 = require("../../nerves/runtime");
+exports.DAEMON_PLIST_LABEL = "bot.ouro.daemon";
+function plistFilePath(homeDir) {
+    return path.join(homeDir, "Library", "LaunchAgents", `${exports.DAEMON_PLIST_LABEL}.plist`);
+}
+function generateDaemonPlist(options) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.launchd_generate_plist",
+        message: "generating daemon plist",
+        meta: { entryPath: options.entryPath, socketPath: options.socketPath },
+    });
+    const lines = [
+        `<?xml version="1.0" encoding="UTF-8"?>`,
+        `<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">`,
+        `<plist version="1.0">`,
+        `<dict>`,
+        `  <key>Label</key>`,
+        `  <string>${exports.DAEMON_PLIST_LABEL}</string>`,
+        `  <key>ProgramArguments</key>`,
+        `  <array>`,
+        `    <string>${options.nodePath}</string>`,
+        `    <string>${options.entryPath}</string>`,
+        `    <string>--socket</string>`,
+        `    <string>${options.socketPath}</string>`,
+        `  </array>`,
+        `  <key>KeepAlive</key>`,
+        `  <true/>`,
+    ];
+    if (options.logDir) {
+        lines.push(`  <key>StandardOutPath</key>`, `  <string>${path.join(options.logDir, "ouro-daemon-stdout.log")}</string>`, `  <key>StandardErrorPath</key>`, `  <string>${path.join(options.logDir, "ouro-daemon-stderr.log")}</string>`);
+    }
+    lines.push(`</dict>`, `</plist>`, ``);
+    return lines.join("\n");
+}
+function installLaunchAgent(deps, options) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.launchd_install",
+        message: "installing launch agent",
+        meta: { entryPath: options.entryPath, socketPath: options.socketPath },
+    });
+    const launchAgentsDir = path.join(deps.homeDir, "Library", "LaunchAgents");
+    deps.mkdirp(launchAgentsDir);
+    const fullPath = plistFilePath(deps.homeDir);
+    // Unload existing (best effort) for idempotent re-install
+    if (deps.existsFile(fullPath)) {
+        try {
+            deps.exec(`launchctl unload "${fullPath}"`);
+        }
+        catch { /* best effort */ }
+    }
+    const xml = generateDaemonPlist(options);
+    deps.writeFile(fullPath, xml);
+    deps.exec(`launchctl load "${fullPath}"`);
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.launchd_installed",
+        message: "launch agent installed",
+        meta: { plistPath: fullPath },
+    });
+}
+function uninstallLaunchAgent(deps) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.launchd_uninstall",
+        message: "uninstalling launch agent",
+        meta: {},
+    });
+    const fullPath = plistFilePath(deps.homeDir);
+    if (deps.existsFile(fullPath)) {
+        try {
+            deps.exec(`launchctl unload "${fullPath}"`);
+        }
+        catch { /* best effort */ }
+        deps.removeFile(fullPath);
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.launchd_uninstalled",
+        message: "launch agent uninstalled",
+        meta: { plistPath: fullPath },
+    });
+}
+function isDaemonInstalled(deps) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.launchd_check_installed",
+        message: "checking if daemon is installed",
+        meta: {},
+    });
+    return deps.existsFile(plistFilePath(deps.homeDir));
+}

package/dist/heart/daemon/ouro-path-installer.js

@@ -38,8 +38,9 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const runtime_1 = require("../../nerves/runtime");
+const CLI_PACKAGE_SPECIFIER = "@ouro.bot/cli@alpha";
 const WRAPPER_SCRIPT = `#!/bin/sh
-exec npx --yes ouro.bot "$@"
+exec npx --yes ${CLI_PACKAGE_SPECIFIER} "$@"
 `;
 function detectShellProfile(homeDir, shell) {
     if (!shell)

package/dist/heart/daemon/run-hooks.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runHooks = runHooks;
+const runtime_1 = require("../../nerves/runtime");
+const bundle_meta_1 = require("./hooks/bundle-meta");
+async function runHooks(deps) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.run_hooks_start",
+        message: "running update hooks",
+        meta: { bundlesRoot: deps.bundlesRoot },
+    });
+    try {
+        deps.registerUpdateHook(bundle_meta_1.bundleMetaHook);
+        const currentVersion = deps.getPackageVersion();
+        await deps.applyPendingUpdates(deps.bundlesRoot, currentVersion);
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.run_hooks_success",
+            message: "update hooks completed successfully",
+            meta: { bundlesRoot: deps.bundlesRoot },
+        });
+        return 0;
+    }
+    catch (err) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.run_hooks_error",
+            message: "update hooks failed",
+            meta: {
+                bundlesRoot: deps.bundlesRoot,
+                error: err instanceof Error ? err.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(err),
+            },
+        });
+        return 1;
+    }
+}

package/dist/heart/daemon/staged-restart.js

@@ -0,0 +1,114 @@
+"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 });
+exports.performStagedRestart = performStagedRestart;
+const path = __importStar(require("path"));
+const runtime_1 = require("../../nerves/runtime");
+async function performStagedRestart(version, deps) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.staged_restart_start",
+        message: "starting staged restart",
+        meta: { version },
+    });
+    // Step 1: Install new version
+    try {
+        deps.execSync(`npm install -g @ouro.bot/cli@${version}`);
+    }
+    catch (err) {
+        const errorMessage = err instanceof Error ? err.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(err);
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.staged_restart_install_failed",
+            message: "npm install failed",
+            meta: { version, error: errorMessage },
+        });
+        return { ok: false, error: errorMessage };
+    }
+    // Step 2: Resolve new code path
+    const newCodePath = deps.resolveNewCodePath(version);
+    if (!newCodePath) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.staged_restart_path_failed",
+            message: "could not resolve new code path",
+            meta: { version },
+        });
+        return { ok: false, error: "could not resolve new code path after install" };
+    }
+    // Step 3: Spawn hook runner on NEW code
+    const hookRunnerPath = path.join(newCodePath, "dist", "heart", "daemon", "run-hooks.js");
+    const spawnResult = deps.spawnSync(deps.nodePath, [hookRunnerPath, "--bundles-root", deps.bundlesRoot], { stdio: "inherit" });
+    if (spawnResult.error) {
+        const errorMessage = spawnResult.error.message;
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.staged_restart_spawn_failed",
+            message: "hook runner spawn failed",
+            meta: { version, error: errorMessage },
+        });
+        return { ok: false, error: errorMessage };
+    }
+    if (spawnResult.status !== 0) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.staged_restart_hooks_failed",
+            message: "hook runner exited with non-zero status",
+            meta: { version, exitCode: spawnResult.status },
+        });
+        return { ok: false, error: `hook runner exited with code ${spawnResult.status}` };
+    }
+    // Step 4: Graceful shutdown (launchd will restart with new code)
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.staged_restart_hooks_passed",
+        message: "hooks passed, shutting down for restart",
+        meta: { version },
+    });
+    try {
+        await deps.gracefulShutdown();
+    }
+    catch (err) {
+        const shutdownError = err instanceof Error ? err.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(err);
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.staged_restart_shutdown_error",
+            message: "graceful shutdown encountered error",
+            meta: { version, error: shutdownError },
+        });
+        return { ok: true, shutdownError };
+    }
+    return { ok: true };
+}

package/dist/heart/daemon/update-checker.js

@@ -0,0 +1,103 @@
+"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 });
+exports.checkForUpdate = checkForUpdate;
+exports.startUpdateChecker = startUpdateChecker;
+exports.stopUpdateChecker = stopUpdateChecker;
+const semver = __importStar(require("semver"));
+const runtime_1 = require("../../nerves/runtime");
+const DEFAULT_INTERVAL_MS = 30 * 60 * 1000; // 30 minutes
+async function checkForUpdate(currentVersion, deps) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.update_check",
+        message: "checking for update",
+        meta: { currentVersion, distTag: deps.distTag },
+    });
+    let registryData;
+    try {
+        registryData = (await deps.fetchRegistryJson());
+    }
+    catch (err) {
+        const errorMessage = err instanceof Error ? err.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(err);
+        return { available: false, error: errorMessage };
+    }
+    const distTags = registryData?.["dist-tags"];
+    if (!distTags) {
+        return { available: false, error: "registry response missing dist-tags" };
+    }
+    const latestVersion = distTags[deps.distTag];
+    if (!latestVersion) {
+        return { available: false, error: `dist-tag "${deps.distTag}" not found in registry` };
+    }
+    const available = semver.gt(latestVersion, currentVersion);
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.update_check_result",
+        message: available ? "update available" : "no update available",
+        meta: { currentVersion, latestVersion, available },
+    });
+    return { available, latestVersion };
+}
+let _intervalId = null;
+function startUpdateChecker(options) {
+    const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.update_checker_start",
+        message: "starting update checker",
+        meta: { intervalMs, currentVersion: options.currentVersion },
+    });
+    _intervalId = setInterval(() => {
+        void (async () => {
+            const result = await checkForUpdate(options.currentVersion, options.deps);
+            if (result.available && options.onUpdate) {
+                await options.onUpdate(result);
+            }
+        })();
+    }, intervalMs);
+}
+function stopUpdateChecker() {
+    if (_intervalId) {
+        clearInterval(_intervalId);
+        _intervalId = null;
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.update_checker_stop",
+        message: "stopping update checker",
+        meta: {},
+    });
+}

package/dist/heart/daemon/update-hooks.js

@@ -0,0 +1,120 @@
+"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 });
+exports.registerUpdateHook = registerUpdateHook;
+exports.getRegisteredHooks = getRegisteredHooks;
+exports.clearRegisteredHooks = clearRegisteredHooks;
+exports.applyPendingUpdates = applyPendingUpdates;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../../nerves/runtime");
+const _hooks = [];
+function registerUpdateHook(hook) {
+    _hooks.push(hook);
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.update_hook_registered",
+        message: "registered update hook",
+        meta: {},
+    });
+}
+function getRegisteredHooks() {
+    return _hooks;
+}
+function clearRegisteredHooks() {
+    _hooks.length = 0;
+}
+async function applyPendingUpdates(bundlesRoot, currentVersion) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.apply_pending_updates_start",
+        message: "applying pending updates",
+        meta: { bundlesRoot, currentVersion },
+    });
+    if (!fs.existsSync(bundlesRoot)) {
+        return;
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(bundlesRoot, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.endsWith(".ouro"))
+            continue;
+        const agentRoot = path.join(bundlesRoot, entry.name);
+        let previousVersion;
+        const metaPath = path.join(agentRoot, "bundle-meta.json");
+        try {
+            if (fs.existsSync(metaPath)) {
+                const raw = fs.readFileSync(metaPath, "utf-8");
+                const meta = JSON.parse(raw);
+                previousVersion = meta.runtimeVersion;
+                if (previousVersion === currentVersion) {
+                    continue;
+                }
+            }
+        }
+        catch {
+            // Malformed or unreadable bundle-meta.json -- treat as needing update
+            previousVersion = undefined;
+        }
+        const ctx = { agentRoot, currentVersion, previousVersion };
+        for (const hook of _hooks) {
+            try {
+                await hook(ctx);
+            }
+            catch (err) {
+                (0, runtime_1.emitNervesEvent)({
+                    component: "daemon",
+                    event: "daemon.update_hook_error",
+                    message: "update hook threw",
+                    meta: {
+                        agentRoot,
+                        error: err instanceof Error ? err.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(err),
+                    },
+                });
+            }
+        }
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.apply_pending_updates_end",
+        message: "pending updates applied",
+        meta: { bundlesRoot },
+    });
+}

package/dist/heart/daemon/wrapper-publish-guard.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assessWrapperPublishSync = assessWrapperPublishSync;
+const runtime_1 = require("../../nerves/runtime");
+function wrapperPackageChanged(changedFiles) {
+    return changedFiles.some((file) => file.startsWith("packages/ouro.bot/"));
+}
+function assessWrapperPublishSync(input) {
+    let result;
+    if (!wrapperPackageChanged(input.changedFiles)) {
+        result = {
+            ok: true,
+            message: "wrapper package unchanged",
+        };
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.wrapper_publish_guard_checked",
+            message: "evaluated wrapper publish sync",
+            meta: { changed: false, localVersion: input.localVersion, publishedVersion: input.publishedVersion, ok: result.ok },
+        });
+        return result;
+    }
+    if (input.publishedVersion === input.localVersion) {
+        result = {
+            ok: false,
+            message: `ouro.bot wrapper changed but ouro.bot@${input.localVersion} is already published; bump packages/ouro.bot/package.json before merging`,
+        };
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.wrapper_publish_guard_checked",
+            message: "evaluated wrapper publish sync",
+            meta: { changed: true, localVersion: input.localVersion, publishedVersion: input.publishedVersion, ok: result.ok },
+        });
+        return result;
+    }
+    result = {
+        ok: true,
+        message: "wrapper package changed and local wrapper version is unpublished",
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.wrapper_publish_guard_checked",
+        message: "evaluated wrapper publish sync",
+        meta: { changed: true, localVersion: input.localVersion, publishedVersion: input.publishedVersion, ok: result.ok },
+    });
+    return result;
+}

package/dist/mind/bundle-manifest.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CANONICAL_BUNDLE_MANIFEST = void 0;
+exports.getChangelogPath = getChangelogPath;
 exports.getPackageVersion = getPackageVersion;
 exports.createBundleMeta = createBundleMeta;
 exports.backfillBundleMeta = backfillBundleMeta;
@@ -58,6 +59,16 @@ exports.CANONICAL_BUNDLE_MANIFEST = [
     { path: "senses", kind: "dir" },
     { path: "senses/teams", kind: "dir" },
 ];
+function getChangelogPath() {
+    const changelogPath = path.resolve(__dirname, "../../changelog.json");
+    (0, runtime_1.emitNervesEvent)({
+        component: "mind",
+        event: "mind.changelog_path_resolved",
+        message: "resolved changelog path",
+        meta: { path: changelogPath },
+    });
+    return changelogPath;
+}
 function getPackageVersion() {
     const packageJsonPath = path.resolve(__dirname, "../../package.json");
     const raw = fs.readFileSync(packageJsonPath, "utf-8");

package/dist/mind/prompt.js

@@ -190,11 +190,28 @@ function aspirationsSection() {
         return "";
     return `## my aspirations\n${text}`;
 }
+function readBundleMeta() {
+    try {
+        const metaPath = path.join((0, identity_1.getAgentRoot)(), "bundle-meta.json");
+        const raw = fs.readFileSync(metaPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
 function runtimeInfoSection(channel) {
     const lines = [];
     const agentName = (0, identity_1.getAgentName)();
+    const currentVersion = (0, bundle_manifest_1.getPackageVersion)();
     lines.push(`## runtime`);
     lines.push(`agent: ${agentName}`);
+    lines.push(`runtime version: ${currentVersion}`);
+    const bundleMeta = readBundleMeta();
+    if (bundleMeta?.previousRuntimeVersion && bundleMeta.previousRuntimeVersion !== currentVersion) {
+        lines.push(`previously: ${bundleMeta.previousRuntimeVersion}`);
+    }
+    lines.push(`changelog available at: ${(0, bundle_manifest_1.getChangelogPath)()}`);
     lines.push(`cwd: ${process.cwd()}`);
     lines.push(`channel: ${channel}`);
     lines.push(`current sense: ${channel}`);

package/dist/senses/cli.js

@@ -62,6 +62,9 @@ const cli_logging_1 = require("../nerves/cli-logging");
 const runtime_1 = require("../nerves/runtime");
 const trust_gate_1 = require("./trust-gate");
 const session_lock_1 = require("./session-lock");
+const update_hooks_1 = require("../heart/daemon/update-hooks");
+const bundle_meta_1 = require("../heart/daemon/hooks/bundle-meta");
+const bundle_manifest_1 = require("../mind/bundle-manifest");
 // spinner that only touches stderr, cleans up after itself
 // exported for direct testability (stop-without-start branch)
 class Spinner {
@@ -662,6 +665,9 @@ async function main(agentName, options) {
     if (agentName)
         (0, identity_1.setAgentName)(agentName);
     const pasteDebounceMs = options?.pasteDebounceMs ?? 50;
+    // Fallback: apply pending updates for daemon-less direct CLI usage
+    (0, update_hooks_1.registerUpdateHook)(bundle_meta_1.bundleMetaHook);
+    await (0, update_hooks_1.applyPendingUpdates)((0, identity_1.getAgentBundlesRoot)(), (0, bundle_manifest_1.getPackageVersion)());
     // Fail fast if provider is misconfigured (triggers human-readable error + exit)
     (0, core_1.getProvider)();
     // Resolve context kernel (identity + channel) for CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.22",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",
@@ -11,7 +11,8 @@
     "dist/",
     "AdoptionSpecialist.ouro/",
     "subagents/",
-    "assets/"
+    "assets/",
+    "changelog.json"
   ],
   "exports": {
     ".": "./dist/heart/daemon/daemon-cli.js",
@@ -34,13 +35,15 @@
     "@anthropic-ai/sdk": "^0.78.0",
     "@microsoft/teams.apps": "^2.0.5",
     "@microsoft/teams.dev": "^2.0.5",
-    "openai": "^6.27.0"
+    "openai": "^6.27.0",
+    "semver": "^7.7.4"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/ouroborosbot/ouroboros"
   },
   "devDependencies": {
+    "@types/semver": "^7.7.1",
     "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^10.0.2",
     "typescript": "^5.7.0",