@ouro.bot/cli 0.1.0-alpha.62 → 0.1.0-alpha.636

package/dist/heart/daemon/daemon.js

@@ -34,21 +34,340 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OuroDaemon = void 0;
+exports.parseOrphanPidsFromPs = parseOrphanPidsFromPs;
+exports.filterPidfilePidsToActualOrphans = filterPidfilePidsToActualOrphans;
+exports.mergeUniqueOrphanPids = mergeUniqueOrphanPids;
+exports.waitForOrphanProcessesToSettle = waitForOrphanProcessesToSettle;
+exports.killOrphanProcesses = killOrphanProcesses;
+exports.writePidfile = writePidfile;
+exports.handleAgentSenseTurn = handleAgentSenseTurn;
+exports.handleAgentAskTurn = handleAgentAskTurn;
 const fs = __importStar(require("fs"));
 const net = __importStar(require("net"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const identity_1 = require("../identity");
+const agent_discovery_1 = require("./agent-discovery");
 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 update_hooks_1 = require("../versioning/update-hooks");
 const bundle_meta_1 = require("./hooks/bundle-meta");
+const agent_config_v2_1 = require("./hooks/agent-config-v2");
 const bundle_manifest_1 = require("../../mind/bundle-manifest");
-const update_checker_1 = require("./update-checker");
-const staged_restart_1 = require("./staged-restart");
+const update_checker_1 = require("../versioning/update-checker");
 const child_process_1 = require("child_process");
 const pending_1 = require("../../mind/pending");
+const agent_service_1 = require("./agent-service");
 const channel_1 = require("../../mind/friends/channel");
+const mcp_manager_1 = require("../../repertoire/mcp-manager");
+const mailbox_http_1 = require("../mailbox/mailbox-http");
+const mailbox_types_1 = require("../mailbox/mailbox-types");
+const mailbox_read_1 = require("../mailbox/mailbox-read");
+const mailbox_view_1 = require("../mailbox/mailbox-view");
+const provider_visibility_1 = require("../provider-visibility");
+const socket_client_1 = require("./socket-client");
+const PIDFILE_PATH = path.join(os.homedir(), ".ouro-cli", "daemon.pids");
+/**
+ * Defense-in-depth: detect if we're running under vitest. The pidfile lives
+ * at a hardcoded path under the user's real ~/.ouro-cli/ — there's no DI
+ * seam to redirect it. So when a test creates a real OuroDaemon and calls
+ * start(), the daemon's killOrphanProcesses() reads the REAL pidfile,
+ * ps-verifies the PIDs, and SIGTERMs the production daemon. We saw this
+ * cause an outage on 2026-04-08 (alpha.265 daemon killed 93s after startup
+ * by a vitest test that called daemon.start()).
+ *
+ * Both killOrphanProcesses() and writePidfile() short-circuit under vitest
+ * to make the production pidfile sacred. Tests that need to verify these
+ * functions' behavior should use the extracted pure helpers
+ * (parseOrphanPidsFromPs, filterPidfilePidsToActualOrphans).
+ */
+function isVitestProcess() {
+    /* v8 ignore next -- defensive: process and process.argv always exist in node @preserve */
+    if (typeof process === "undefined" || !Array.isArray(process.argv))
+        return false;
+    return process.argv.some((arg) => typeof arg === "string" && arg.includes("vitest"));
+}
+/**
+ * Scan `ps -eo pid,ppid,command` output for daemon-owned entry points whose
+ * parent has died (PPID reparented to init/PID 1). Returns the list of PIDs
+ * that are safe to SIGTERM — true orphans, not children of live sibling
+ * daemons running from worktrees, test suites, or other users of the harness.
+ *
+ * Exported so unit tests can exercise the filter without shelling out.
+ */
+function parseOrphanPidsFromPs(psOutput, selfPid) {
+    const orphans = [];
+    for (const line of psOutput.split("\n")) {
+        // Explicitly exclude MCP server processes — they share a harness entry
+        // point but are not daemon children and must never be killed.
+        if (line.includes("mcp-serve") || line.includes("mcp serve"))
+            continue;
+        // Match only daemon-owned JS entry points.
+        if (!line.includes("agent-entry.js")
+            && !line.includes("daemon-entry.js")
+            && !line.includes("bluebubbles/entry.js")
+            && !line.includes("mail-entry.js")
+            && !line.includes("teams-entry.js"))
+            continue;
+        // Parse `<pid> <ppid> <command...>`. ps pads these with leading spaces.
+        // Regex guarantees both groups are \d+ so parseInt can't produce NaN.
+        const match = line.trim().match(/^(\d+)\s+(\d+)\s/);
+        if (!match)
+            continue;
+        const pid = parseInt(match[1], 10);
+        const ppid = parseInt(match[2], 10);
+        if (pid === selfPid)
+            continue;
+        // CRITICAL: only kill processes whose parent is init (PID 1). A live
+        // PPID means the process belongs to another daemon instance (parallel
+        // test run, sibling worktree, another user of /tmp/ouroboros-daemon.sock).
+        // Killing those will crash unrelated harnesses — we saw this in B6
+        // when a vitest worker's daemon killed a production agent's children.
+        if (ppid !== 1)
+            continue;
+        orphans.push(pid);
+    }
+    return orphans;
+}
+/**
+ * Given a list of PIDs from the pidfile, return only those that are actual
+ * orphans (PPID reparented to init/PID 1). Protects against a polluted
+ * pidfile killing a PID that the OS has reassigned to an unrelated process.
+ *
+ * Implementation: shells out to `ps -p <csv> -o pid,ppid` for a batch lookup.
+ * Returns the empty list if ps fails — safer to skip cleanup than to
+ * wildcard-kill on a bad read.
+ *
+ * Exported for direct unit coverage.
+ */
+function filterPidfilePidsToActualOrphans(candidatePids, psRunner = runPsCheck) {
+    if (candidatePids.length === 0)
+        return [];
+    const psOutput = psRunner(candidatePids);
+    if (psOutput === null)
+        return [];
+    const survivingOrphans = [];
+    // `ps -p x,y,z -o pid,ppid` emits a header line then one row per found PID.
+    // PIDs not found (already exited) are silently omitted — which is the
+    // correct behavior for us: we only want to kill live orphans.
+    for (const line of psOutput.split("\n")) {
+        const match = line.trim().match(/^(\d+)\s+(\d+)$/);
+        if (!match)
+            continue;
+        const pid = parseInt(match[1], 10);
+        const ppid = parseInt(match[2], 10);
+        if (ppid !== 1)
+            continue;
+        if (!candidatePids.includes(pid))
+            continue;
+        survivingOrphans.push(pid);
+    }
+    return survivingOrphans;
+}
+function mergeUniqueOrphanPids(...sources) {
+    const merged = [];
+    const seen = new Set();
+    for (const source of sources) {
+        for (const pid of source) {
+            if (seen.has(pid))
+                continue;
+            seen.add(pid);
+            merged.push(pid);
+        }
+    }
+    return merged;
+}
+const ORPHAN_CLEANUP_SETTLE_TIMEOUT_MS = 5_000;
+const ORPHAN_CLEANUP_SETTLE_POLL_INTERVAL_MS = 50;
+/* v8 ignore start -- process liveness probe; pure wait behavior covered via injected deps @preserve */
+function defaultIsPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/* v8 ignore stop */
+/* v8 ignore start -- real timer wiring; wait behavior covered via injected sleep @preserve */
+async function defaultSettleSleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+/* v8 ignore stop */
+async function waitForOrphanProcessesToSettle(pids, deps = {}) {
+    if (pids.length === 0)
+        return [];
+    const isPidAlive = deps.isPidAlive ?? defaultIsPidAlive;
+    const now = deps.now ?? Date.now;
+    const sleep = deps.sleep ?? defaultSettleSleep;
+    const timeoutMs = deps.timeoutMs ?? ORPHAN_CLEANUP_SETTLE_TIMEOUT_MS;
+    const pollIntervalMs = deps.pollIntervalMs ?? ORPHAN_CLEANUP_SETTLE_POLL_INTERVAL_MS;
+    const deadline = now() + timeoutMs;
+    let survivors = pids.filter(isPidAlive);
+    while (survivors.length > 0 && now() < deadline) {
+        await sleep(pollIntervalMs);
+        survivors = pids.filter(isPidAlive);
+    }
+    return survivors;
+}
+/* v8 ignore start -- shells out to ps; covered by filterPidfilePidsToActualOrphans unit tests via injected runner @preserve */
+function runPsCheck(pids) {
+    try {
+        const csv = pids.join(",");
+        return (0, child_process_1.execSync)(`ps -p ${csv} -o pid=,ppid=`, { encoding: "utf-8", timeout: 5000 });
+    }
+    catch {
+        // ps returns non-zero when none of the requested PIDs exist. Treat as
+        // "no survivors" rather than an error.
+        return "";
+    }
+}
+/* v8 ignore stop */
+/**
+ * Kill all ouro processes from the previous daemon instance using the pidfile.
+ * On startup, reads PIDs from ~/.ouro-cli/daemon.pids, kills them all, then
+ * deletes the file. The new daemon writes its own PIDs after spawning.
+ *
+ * Safety: pidfile contents are verified before being killed — each PID must
+ * be an actual orphan (PPID reparented to init/PID 1) via
+ * `filterPidfilePidsToActualOrphans`. Otherwise a polluted pidfile (written
+ * by a test, or a crashed daemon whose PIDs have since been reused by the
+ * OS) could SIGTERM unrelated processes.
+ *
+ * Falls back to ps-based scanning scoped to true orphans (PPID=1) if the
+ * pidfile doesn't exist (first run, previous daemon crashed before writing,
+ * manual cleanup). The scope is narrow on purpose — see parseOrphanPidsFromPs.
+ */
+/* v8 ignore start -- process lifecycle: uses kill/ps, tested via deployment @preserve */
+function isProductionDaemonSocketPath(socketPath) {
+    return socketPath === socket_client_1.DEFAULT_DAEMON_SOCKET_PATH;
+}
+function killOrphanProcesses(socketPath = socket_client_1.DEFAULT_DAEMON_SOCKET_PATH) {
+    if (!isProductionDaemonSocketPath(socketPath)) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.orphan_cleanup_nonproduction_blocked",
+            message: "blocked orphan cleanup for non-production daemon socket",
+            meta: { socketPath, pidfilePath: PIDFILE_PATH },
+        });
+        return [];
+    }
+    if (isVitestProcess()) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.orphan_cleanup_test_blocked",
+            message: "blocked killOrphanProcesses from touching real pidfile under vitest",
+            meta: { pidfilePath: PIDFILE_PATH },
+        });
+        return [];
+    }
+    try {
+        let pidfileOrphans = [];
+        let scanOrphans = [];
+        // Primary: read pidfile from previous daemon
+        try {
+            const raw = fs.readFileSync(PIDFILE_PATH, "utf-8");
+            const candidates = raw.split("\n")
+                .map((s) => parseInt(s.trim(), 10))
+                .filter((n) => !isNaN(n) && n !== process.pid);
+            // Verify each candidate is an actual live orphan before killing. See
+            // docstring above for why this matters.
+            pidfileOrphans = filterPidfilePidsToActualOrphans(candidates);
+            fs.unlinkSync(PIDFILE_PATH);
+        }
+        catch {
+            // No pidfile — the ps scan below still covers true orphans.
+        }
+        // Always supplement the pidfile with the scoped ps scan. A stale or
+        // partial pidfile can otherwise kill one old daemon while leaving a
+        // sibling PPID=1 daemon alive without a socket.
+        try {
+            const result = (0, child_process_1.execSync)("ps -eo pid,ppid,command", { encoding: "utf-8", timeout: 5000 });
+            scanOrphans = parseOrphanPidsFromPs(result, process.pid);
+        }
+        catch { /* ps failed — best effort */ }
+        const pidsToKill = mergeUniqueOrphanPids(pidfileOrphans, scanOrphans);
+        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 },
+            });
+        }
+        return 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) },
+        });
+        return [];
+    }
+}
+/**
+ * Write all managed PIDs (daemon + children) to the pidfile.
+ * Called after all agents and senses are spawned.
+ */
+function writePidfile(extraPids = [], socketPath = socket_client_1.DEFAULT_DAEMON_SOCKET_PATH) {
+    if (!isProductionDaemonSocketPath(socketPath)) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.write_pidfile_nonproduction_blocked",
+            message: "blocked production pidfile write for non-production daemon socket",
+            meta: { socketPath, pidfilePath: PIDFILE_PATH, attemptedPids: extraPids.length },
+        });
+        return;
+    }
+    if (isVitestProcess()) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.write_pidfile_test_blocked",
+            message: "blocked writePidfile from clobbering real pidfile under vitest",
+            meta: { pidfilePath: PIDFILE_PATH, attemptedPids: extraPids.length },
+        });
+        return;
+    }
+    try {
+        const pids = [process.pid, ...extraPids].filter(Boolean);
+        fs.mkdirSync(path.dirname(PIDFILE_PATH), { recursive: true });
+        fs.writeFileSync(PIDFILE_PATH, pids.join("\n") + "\n", "utf-8");
+    }
+    catch { /* best effort */ }
+}
+function readSocketIdentity(socketPath) {
+    try {
+        const stats = fs.lstatSync(socketPath);
+        return {
+            dev: stats.dev,
+            ino: stats.ino,
+            ctimeMs: stats.ctimeMs,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function sameSocketIdentity(left, right) {
+    if (!left || !right)
+        return false;
+    return left.dev === right.dev && left.ino === right.ino && left.ctimeMs === right.ctimeMs;
+}
 function buildWorkerRows(snapshots) {
     return snapshots.map((snapshot) => ({
         agent: snapshot.name,
@@ -57,19 +376,60 @@ function buildWorkerRows(snapshots) {
         pid: snapshot.pid,
         restartCount: snapshot.restartCount,
         startedAt: snapshot.startedAt,
+        lastExitCode: snapshot.lastExitCode ?? null,
+        lastSignal: snapshot.lastSignal ?? null,
+        errorReason: snapshot.errorReason ?? null,
+        fixHint: snapshot.fixHint ?? null,
     }));
 }
+function unhealthySenseRows(senses) {
+    return senses.filter((row) => {
+        if (!row.enabled)
+            return false;
+        if (row.status === "disabled" || row.status === "not_attached")
+            return false;
+        if (row.status === "interactive" || row.status === "running")
+            return false;
+        return true;
+    });
+}
+function unhealthyHealthChecks(healthChecks) {
+    return healthChecks.filter((row) => row.status !== "ok");
+}
+function overviewHealth(workers, senses, healthChecks = []) {
+    if (!workers.every((worker) => worker.status === "running"))
+        return "warn";
+    if (unhealthySenseRows(senses).length > 0)
+        return "warn";
+    if (unhealthyHealthChecks(healthChecks).length > 0)
+        return "warn";
+    return "ok";
+}
 function formatStatusSummary(payload) {
-    if (payload.overview.workerCount === 0 && payload.overview.senseCount === 0) {
+    if (payload.overview.workerCount === 0 && payload.overview.senseCount === 0 && (payload.healthChecks ?? []).length === 0) {
         return "no managed agents";
     }
-    const rows = [
-        ...payload.workers.map((row) => `${row.agent}/${row.worker}:${row.status}`),
-        ...payload.senses
-            .filter((row) => row.enabled)
-            .map((row) => `${row.agent}/${row.sense}:${row.status}`),
+    const degraded = [
+        ...payload.workers
+            .filter((row) => row.status !== "running")
+            .map((row) => `worker:${row.agent}/${row.worker}:${row.status}`),
+        ...unhealthySenseRows(payload.senses)
+            .map((row) => `sense:${row.agent}/${row.sense}:${row.status}`),
+        ...(payload.healthChecks ?? [])
+            .filter((row) => row.status !== "ok")
+            .map((row) => `health-check:${row.name}:${row.status}`),
     ];
-    const detail = rows.length > 0 ? `\titems=${rows.join(",")}` : "";
+    const detail = degraded.length > 0 ? `\tdegraded=${degraded.join(",")}` : "";
+    if (!detail) {
+        const rows = [
+            ...payload.workers.map((row) => `${row.agent}/${row.worker}:${row.status}`),
+            ...payload.senses
+                .filter((row) => row.enabled)
+                .map((row) => `${row.agent}/${row.sense}:${row.status}`),
+        ];
+        const items = rows.length > 0 ? `\titems=${rows.join(",")}` : "";
+        return `daemon=${payload.overview.daemon}\tworkers=${payload.overview.workerCount}\tsenses=${payload.overview.senseCount}\thealth=${payload.overview.health}${items}`;
+    }
     return `daemon=${payload.overview.daemon}\tworkers=${payload.overview.workerCount}\tsenses=${payload.overview.senseCount}\thealth=${payload.overview.health}${detail}`;
 }
 function parseIncomingCommand(raw) {
@@ -89,6 +449,59 @@ function parseIncomingCommand(raw) {
     }
     return parsed;
 }
+function isValidSenseReviveCommand(command) {
+    return typeof command.agent === "string"
+        && typeof command.sense === "string"
+        && typeof command.reason === "string";
+}
+/**
+ * Handle agent.senseTurn command: runs a full agent turn via the daemon process.
+ * Dynamic import lazy-loads shared-turn. Hot-reload works because ouro dev
+ * restarts the daemon process (fresh module cache).
+ */
+async function handleAgentSenseTurn(command) {
+    try {
+        const { setAgentName } = await Promise.resolve().then(() => __importStar(require("../identity")));
+        setAgentName(command.agent);
+        const { runSenseTurn } = await Promise.resolve().then(() => __importStar(require("../../senses/shared-turn")));
+        const result = await runSenseTurn({
+            agentName: command.agent,
+            channel: command.channel,
+            sessionKey: command.sessionKey,
+            friendId: command.friendId,
+            userMessage: command.message,
+        });
+        return {
+            ok: true,
+            message: result.response,
+            data: { ponderDeferred: result.ponderDeferred },
+        };
+    }
+    catch (error) {
+        /* v8 ignore next -- branch: String(error) fallback only for non-Error throws @preserve */
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: `sense turn failed: ${errorMessage}` };
+    }
+}
+async function handleAgentAskTurn(command) {
+    /* v8 ignore start -- ask command parameter defaults are legacy MCP compatibility; send_message shares the primary path @preserve */
+    const question = typeof command.question === "string" ? command.question : "";
+    if (!question.trim())
+        return { ok: false, error: "Missing required parameter: question" };
+    const channel = typeof command.channel === "string" && command.channel.trim() ? command.channel.trim() : "mcp";
+    const sessionKey = typeof command.sessionKey === "string" && command.sessionKey.trim()
+        ? command.sessionKey.trim()
+        : `agent-ask:${command.friendId}`;
+    /* v8 ignore stop */
+    return handleAgentSenseTurn({
+        kind: "agent.senseTurn",
+        agent: command.agent,
+        friendId: command.friendId,
+        channel,
+        sessionKey,
+        message: question,
+    });
+}
 class OuroDaemon {
     socketPath;
     processManager;
@@ -97,7 +510,13 @@ class OuroDaemon {
     router;
     senseManager;
     bundlesRoot;
+    mode;
     server = null;
+    mailboxServer = null;
+    socketIdentity = null;
+    senseAutostartTimer = null;
+    mailboxServerFactory;
+    onStopCommandComplete;
     constructor(options) {
         this.socketPath = options.socketPath;
         this.processManager = options.processManager;
@@ -106,6 +525,77 @@ class OuroDaemon {
         this.router = options.router;
         this.senseManager = options.senseManager ?? null;
         this.bundlesRoot = options.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
+        this.mode = options.mode ?? "production";
+        this.mailboxServerFactory = options.mailboxServerFactory ?? this.createDefaultMailboxServer.bind(this);
+        this.onStopCommandComplete = options.onStopCommandComplete ?? null;
+    }
+    /* v8 ignore start -- default mailbox server wiring: production-only path, tests inject mailboxServerFactory stub instead. startMailboxHttpServer itself has full coverage in mailbox-http.test.ts @preserve */
+    createDefaultMailboxServer() {
+        return (0, mailbox_http_1.startMailboxHttpServer)({
+            host: "127.0.0.1",
+            port: mailbox_types_1.MAILBOX_DEFAULT_PORT,
+            bundlesRoot: this.bundlesRoot,
+            readMachineState: () => (0, mailbox_read_1.readMailboxMachineState)({ bundlesRoot: this.bundlesRoot }),
+            readMachineView: ({ machine }) => {
+                const overview = this.buildStatusPayload().overview;
+                return (0, mailbox_view_1.buildMailboxMachineView)({
+                    machine,
+                    daemon: {
+                        status: overview.daemon,
+                        health: overview.health,
+                        mode: overview.mode,
+                        socketPath: overview.socketPath,
+                        mailboxUrl: overview.mailboxUrl,
+                        entryPath: overview.entryPath,
+                        workerCount: overview.workerCount,
+                        senseCount: overview.senseCount,
+                    },
+                });
+            },
+            readAgentState: (agentName) => (0, mailbox_read_1.readMailboxAgentState)(agentName, { bundlesRoot: this.bundlesRoot }),
+            readAgentView: (agentName) => {
+                const agent = (0, mailbox_read_1.readMailboxAgentState)(agentName, { bundlesRoot: this.bundlesRoot });
+                return (0, mailbox_view_1.buildMailboxAgentView)({
+                    agent,
+                    viewer: { kind: "human" },
+                });
+            },
+        });
+    }
+    /* v8 ignore stop */
+    buildStatusPayload() {
+        const snapshots = this.processManager.listAgentSnapshots();
+        const workers = buildWorkerRows(snapshots);
+        const senses = this.senseManager?.listSenseRows() ?? [];
+        const healthChecks = this.healthMonitor.getLastResults?.() ?? [];
+        const repoRoot = (0, identity_1.getRepoRoot)();
+        const sync = (0, agent_discovery_1.listBundleSyncRows)({ bundlesRoot: this.bundlesRoot });
+        const agents = (0, agent_discovery_1.listAllBundleAgents)({ bundlesRoot: this.bundlesRoot });
+        const providers = agents.flatMap((agent) => (0, provider_visibility_1.providerVisibilityStatusRows)((0, provider_visibility_1.buildAgentProviderVisibility)({
+            agentName: agent.name,
+            agentRoot: path.join(this.bundlesRoot, `${agent.name}.ouro`),
+        })));
+        const mailboxUrl = this.mailboxServer?.origin ?? "http://127.0.0.1:0";
+        return {
+            overview: {
+                daemon: "running",
+                health: overviewHealth(workers, senses, healthChecks),
+                socketPath: this.socketPath,
+                mailboxUrl,
+                outlookUrl: mailboxUrl,
+                ...(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,
+            ...(healthChecks.length > 0 ? { healthChecks } : {}),
+            sync,
+            agents,
+            ...(providers.length > 0 ? { providers } : {}),
+        };
     }
     async start() {
         if (this.server)
@@ -116,62 +606,180 @@ class OuroDaemon {
             message: "starting daemon server",
             meta: { socketPath: this.socketPath },
         });
+        try {
+            await this.startInner();
+        }
+        catch (err) {
+            // Emit a paired terminating event (`_error`) so the nerves audit's
+            // start_end_pairing rule is satisfied when startup throws mid-sequence
+            // and `stop()` (which emits `server_end`) is never called.
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "daemon",
+                event: "daemon.server_error",
+                message: "daemon start failed",
+                meta: {
+                    error: err instanceof Error ? err.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(err),
+                },
+            });
+            throw err;
+        }
+    }
+    async startInner() {
         // Register update hooks and apply pending updates before starting agents
         (0, update_hooks_1.registerUpdateHook)(bundle_meta_1.bundleMetaHook);
+        (0, update_hooks_1.registerUpdateHook)(agent_config_v2_1.agentConfigV2Hook);
         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;
-                        }
+        // Skip in dev mode — dev builds should not auto-update from npm
+        if (this.mode === "dev") {
+            (0, runtime_1.emitNervesEvent)({
+                component: "daemon",
+                event: "daemon.update_checker_skip",
+                message: "skipping update checker in dev mode",
+                meta: { reason: "dev mode" },
+            });
+        }
+        else {
+            (0, update_checker_1.startUpdateChecker)({
+                currentVersion,
+                deps: {
+                    distTag: update_checker_1.CLI_UPDATE_DIST_TAG,
+                    fetchRegistryJson: /* v8 ignore next -- integration: real HTTP fetch @preserve */ async () => {
+                        const res = await fetch("https://registry.npmjs.org/@ouro.bot/cli");
+                        return res.json();
                     },
-                    gracefulShutdown: () => daemon.stop(),
-                    nodePath: process.execPath,
-                    bundlesRoot,
-                });
-            },
-            /* v8 ignore stop */
-        });
-        await this.processManager.startAutoStartAgents();
-        await this.senseManager?.startAutoStartSenses();
+                },
+            });
+        }
+        // MCP connections are lazily initialized per-agent during senseTurn
+        // (daemon manages multiple agents; agent identity must be set before loading MCP config)
+        /* v8 ignore start -- orphan cleanup + pidfile: calls process management functions @preserve */
+        const killedOrphanPids = killOrphanProcesses(this.socketPath);
+        await waitForOrphanProcessesToSettle(killedOrphanPids);
+        /* v8 ignore stop */
+        await this.openCommandSocket();
+        this.triggerAutoStartAgents();
+        this.triggerAutoStartSensesWhenAgentsSettled();
+        // Write all managed PIDs to disk so the next daemon can clean up
+        /* v8 ignore start -- pidfile write: collects PIDs from process managers @preserve */
+        const agentPids = this.processManager.listAgentSnapshots().map((s) => s.pid).filter((p) => p !== null);
+        const sensePids = this.senseManager?.listManagedPids?.() ?? [];
+        writePidfile([...agentPids, ...sensePids], this.socketPath);
+        /* v8 ignore stop */
         this.scheduler.start?.();
         await this.scheduler.reconcile?.();
         await this.drainPendingBundleMessages();
         await this.drainPendingSenseMessages();
+        // startInner is only reachable when this.server is null (guarded in
+        // start()), and stop() nulls out this.mailboxServer alongside this.server,
+        // so mailboxServer is guaranteed unset here — no need for a guard.
+        try {
+            this.mailboxServer = await this.mailboxServerFactory();
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "daemon",
+                event: "daemon.mailbox_start_failed",
+                message: `Mailbox server failed to start: ${String(error)}`,
+                meta: { port: mailbox_types_1.MAILBOX_DEFAULT_PORT },
+            });
+        }
+    }
+    triggerAutoStartAgents() {
+        if (this.processManager.triggerAutoStartAgents) {
+            this.processManager.triggerAutoStartAgents();
+            return;
+        }
+        void this.processManager.startAutoStartAgents().catch((error) => {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "daemon",
+                event: "daemon.agent_autostart_error",
+                message: "agent autostart failed after daemon socket opened",
+                meta: { error: error instanceof Error ? error.message : String(error) },
+            });
+        });
+    }
+    triggerAutoStartSenses() {
+        /* v8 ignore next -- defensive: callers already check senseManager before delegating here @preserve */
+        if (!this.senseManager)
+            return;
+        if (this.senseManager.triggerAutoStartSenses) {
+            this.senseManager.triggerAutoStartSenses();
+            return;
+        }
+        void this.senseManager.startAutoStartSenses().catch((error) => {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "daemon",
+                event: "daemon.sense_autostart_error",
+                message: "sense autostart failed after daemon socket opened",
+                meta: { error: error instanceof Error ? error.message : String(error) },
+            });
+        });
+    }
+    triggerAutoStartSensesWhenAgentsSettled() {
+        if (!this.senseManager)
+            return;
+        const waitingOnAgents = this.processManager.listAgentSnapshots()
+            .some((snapshot) => snapshot.status === "starting");
+        if (!waitingOnAgents) {
+            this.triggerAutoStartSenses();
+            return;
+        }
+        this.senseAutostartTimer = setTimeout(() => {
+            this.senseAutostartTimer = null;
+            this.triggerAutoStartSensesWhenAgentsSettled();
+        }, 250);
+    }
+    async openCommandSocket() {
         if (fs.existsSync(this.socketPath)) {
             fs.unlinkSync(this.socketPath);
         }
-        this.server = net.createServer((connection) => {
+        // allowHalfOpen: true lets the server keep its writable side open after
+        // the client sends FIN. Without this, when a client calls `client.end()`
+        // after writing a command, node closes the server's writable side
+        // automatically — so a long-running response (like an agent.senseTurn
+        // LLM turn that takes 5+ seconds) never reaches the client. The
+        // socket-client fix in #303/#334 also removed client.end() on the
+        // sending side, but this option is defense in depth: even if a future
+        // caller half-closes, the server still writes its response correctly.
+        this.server = net.createServer({ allowHalfOpen: true }, (connection) => {
             let raw = "";
             let responded = false;
+            /* v8 ignore start — connection error handler requires real socket error @preserve */
+            connection.on("error", (err) => {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "daemon",
+                    event: "daemon.connection_error",
+                    message: "socket connection error",
+                    meta: { error: err.message, code: err.code ?? null },
+                });
+            });
+            /* v8 ignore stop */
             const flushResponse = async () => {
                 if (responded)
                     return;
                 responded = true;
                 const response = await this.handleRawPayload(raw);
-                connection.end(response);
+                try {
+                    connection.end(response);
+                    /* v8 ignore start — EPIPE catch requires real socket disconnect @preserve */
+                }
+                catch (err) {
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn",
+                        component: "daemon",
+                        event: "daemon.connection_end_error",
+                        message: "failed to send response to client (EPIPE)",
+                        meta: { error: err instanceof Error ? err.message : String(err) },
+                    });
+                }
+                /* v8 ignore stop */
             };
             connection.on("data", (chunk) => {
                 raw += chunk.toString("utf-8");
@@ -184,7 +792,23 @@ class OuroDaemon {
         const server = this.server;
         await new Promise((resolve, reject) => {
             server.once("error", reject);
-            server.listen(this.socketPath, () => resolve());
+            server.listen(this.socketPath, () => {
+                // Replace the one-time error listener with a persistent one after successful listen
+                server.removeAllListeners("error");
+                this.socketIdentity = readSocketIdentity(this.socketPath);
+                /* v8 ignore start — server error after listen requires real socket race condition @preserve */
+                server.on("error", (err) => {
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "error",
+                        component: "daemon",
+                        event: "daemon.server_error",
+                        message: "daemon server error after listen",
+                        meta: { error: err.message, code: err.code ?? null },
+                    });
+                });
+                /* v8 ignore stop */
+                resolve();
+            });
         });
     }
     async drainPendingBundleMessages() {
@@ -323,25 +947,87 @@ class OuroDaemon {
         }
     }
     async stop() {
+        // Must be named `_end` (not `_stop`) to satisfy the nerves audit's
+        // start/end pairing rule — see src/nerves/coverage/audit-rules.ts.
+        // This is the counterpart to `daemon.server_start` emitted at line 480.
         (0, runtime_1.emitNervesEvent)({
             component: "daemon",
-            event: "daemon.server_stop",
+            event: "daemon.server_end",
             message: "stopping daemon server",
             meta: { socketPath: this.socketPath },
         });
         (0, update_checker_1.stopUpdateChecker)();
+        (0, mcp_manager_1.shutdownSharedMcpManager)();
         this.scheduler.stop?.();
+        this.healthMonitor.stopPeriodicChecks?.();
+        if (this.senseAutostartTimer) {
+            clearTimeout(this.senseAutostartTimer);
+            this.senseAutostartTimer = null;
+        }
         await this.processManager.stopAll();
         await this.senseManager?.stopAll();
         if (this.server) {
-            await new Promise((resolve) => {
-                this.server?.close(() => resolve());
-            });
+            // DO NOT `await` server.close() here. server.close() resolves only
+            // after every open connection has closed. When stop() is invoked
+            // from the daemon.stop command handler, the calling client's
+            // connection is STILL open — its flushResponse() is currently
+            // awaiting THIS function. Awaiting close() creates a deadlock:
+            //
+            //   client → flushResponse → handleRawPayload → daemon.stop case
+            //   → stop() → await server.close() (waits for client's connection)
+            //   → client's connection waits for flushResponse to call
+            //     connection.end() → DEADLOCK
+            //
+            // Both processes sit in kevent forever. Verified live on
+            // 2026-04-08: alpha.268 daemon hung at `daemon.server_end` log
+            // line for 5+ minutes after a client sent daemon.stop, while the
+            // client (alpha.270 ouro up) hung waiting for the response.
+            //
+            // This regressed when #303/#334/#339 stopped half-closing the
+            // client socket and switched the server to allowHalfOpen: true.
+            // Previously, the client called .end() after writing its command,
+            // which (with allowHalfOpen: false) caused node to auto-tear-down
+            // the server's writable side — incidentally unblocking
+            // server.close() before the response was sent. The half-close
+            // breakage masked this deadlock; the fix exposed it.
+            //
+            // Solution: fire close() and let it complete asynchronously. Once
+            // stop() returns, the daemon.stop case returns its response,
+            // flushResponse() calls connection.end(response), the connection
+            // closes, and server.close()'s pending callback fires. The event
+            // loop drains and the daemon exits cleanly.
+            this.server.close();
             this.server = null;
         }
-        if (fs.existsSync(this.socketPath)) {
+        if (this.mailboxServer) {
+            await this.mailboxServer.stop();
+            this.mailboxServer = null;
+        }
+        const socketPathExists = fs.existsSync(this.socketPath);
+        const currentSocketIdentity = socketPathExists ? readSocketIdentity(this.socketPath) : null;
+        if (sameSocketIdentity(this.socketIdentity, currentSocketIdentity)) {
             fs.unlinkSync(this.socketPath);
         }
+        else if (socketPathExists) {
+            const expectedSocketIdentity = { dev: null, ino: null, ctimeMs: null, ...this.socketIdentity };
+            const actualSocketIdentity = { dev: null, ino: null, ctimeMs: null, ...currentSocketIdentity };
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "daemon",
+                event: "daemon.socket_cleanup_skipped",
+                message: "skipped daemon socket cleanup because the socket path no longer belongs to this daemon",
+                meta: {
+                    socketPath: this.socketPath,
+                    expectedDev: expectedSocketIdentity.dev,
+                    expectedIno: expectedSocketIdentity.ino,
+                    expectedCtimeMs: expectedSocketIdentity.ctimeMs,
+                    actualDev: actualSocketIdentity.dev,
+                    actualIno: actualSocketIdentity.ino,
+                    actualCtimeMs: actualSocketIdentity.ctimeMs,
+                },
+            });
+        }
+        this.socketIdentity = null;
     }
     async handleRawPayload(raw) {
         try {
@@ -363,32 +1049,58 @@ class OuroDaemon {
             message: "handling daemon command",
             meta: { kind: command.kind },
         });
+        try {
+            return await this.handleCommandInner(command);
+            /* v8 ignore start — command error catch tested in daemon-command-error.test; instanceof branches defensive @preserve */
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "daemon",
+                event: "daemon.command_error",
+                message: "unexpected error handling daemon command",
+                meta: {
+                    kind: command.kind,
+                    error: error instanceof Error ? error.message : String(error),
+                    stack: error instanceof Error ? error.stack ?? null : null,
+                },
+            });
+            throw error;
+        }
+        /* v8 ignore stop */
+    }
+    async handleCommandInner(command) {
         switch (command.kind) {
             case "daemon.start":
                 await this.start();
                 return { ok: true, message: "daemon started" };
             case "daemon.stop":
                 await this.stop();
+                this.onStopCommandComplete?.();
                 return { ok: true, message: "daemon stopped" };
-            case "daemon.status": {
-                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),
+            case "daemon.restart": {
+                // Restart is "stop + let launchctl respawn." Under launchctl's KeepAlive
+                // policy the process is auto-restarted on exit, so daemon.restart and
+                // daemon.stop differ only in intent + audit trail. In dev (no launchctl),
+                // the process simply exits — same observable behavior as daemon.stop.
+                (0, runtime_1.emitNervesEvent)({
+                    component: "daemon",
+                    event: "daemon.restart_requested",
+                    message: "daemon restart requested",
+                    meta: {
+                        reason: command.reason ?? null,
+                        requestedBy: command.requestedBy ?? null,
                     },
-                    workers,
-                    senses,
+                });
+                await this.stop();
+                this.onStopCommandComplete?.();
+                return {
+                    ok: true,
+                    message: "daemon restarting — launchctl will respawn",
                 };
+            }
+            case "daemon.status": {
+                const data = this.buildStatusPayload();
                 return {
                     ok: true,
                     summary: formatStatusSummary(data),
@@ -407,6 +1119,48 @@ class OuroDaemon {
                     message: "log streaming available via ouro logs",
                     data: { logDir: "~/AgentBundles/<agent>.ouro/state/daemon/logs" },
                 };
+            case "daemon.sense_revive": {
+                if (!isValidSenseReviveCommand(command)) {
+                    return {
+                        ok: false,
+                        error: "Invalid daemon.sense_revive payload: expected string fields 'agent', 'sense', and 'reason'.",
+                    };
+                }
+                const revivedSenseRow = await this.senseManager?.reviveSense?.(command.agent, command.sense);
+                if (revivedSenseRow) {
+                    return {
+                        ok: true,
+                        message: `revived ${command.agent}/${command.sense}`,
+                        data: revivedSenseRow,
+                    };
+                }
+                const managedSenseSnapshots = this.processManager.listAgentSnapshots()
+                    .filter((snapshot) => snapshot.name.startsWith(`${command.agent}:`));
+                if (managedSenseSnapshots.length === 0) {
+                    return {
+                        ok: false,
+                        error: `No managed agent '${command.agent}' is registered with daemon-managed senses.`,
+                    };
+                }
+                const exactTargetName = `${command.agent}:${command.sense}`;
+                const target = managedSenseSnapshots.find((snapshot) => snapshot.name === exactTargetName)
+                    ?? managedSenseSnapshots.find((snapshot) => snapshot.channel === command.sense);
+                if (!target) {
+                    return {
+                        ok: false,
+                        error: `No managed sense '${command.sense}' is registered for agent '${command.agent}'.`,
+                    };
+                }
+                this.processManager.resetAgentFailureState(target.name);
+                await this.processManager.startAgent(target.name);
+                const freshSnapshot = this.processManager.listAgentSnapshots()
+                    .find((snapshot) => snapshot.name === target.name) ?? target;
+                return {
+                    ok: true,
+                    message: `revived ${command.agent}/${command.sense}`,
+                    data: freshSnapshot,
+                };
+            }
             case "agent.start":
                 await this.processManager.startAgent(command.agent);
                 return { ok: true, message: `started ${command.agent}` };
@@ -416,6 +1170,35 @@ class OuroDaemon {
             case "agent.restart":
                 await this.processManager.restartAgent?.(command.agent);
                 return { ok: true, message: `restarted ${command.agent}` };
+            case "agent.ask":
+                return handleAgentAskTurn(command);
+            case "agent.status":
+                return (0, agent_service_1.handleAgentStatus)(command);
+            case "agent.catchup":
+                return (0, agent_service_1.handleAgentCatchup)(command);
+            case "agent.delegate":
+                return (0, agent_service_1.handleAgentDelegate)(command);
+            case "agent.getContext":
+                return (0, agent_service_1.handleAgentGetContext)(command);
+            case "agent.searchNotes":
+                return (0, agent_service_1.handleAgentSearchNotes)(command);
+            case "agent.getTask":
+                return (0, agent_service_1.handleAgentGetTask)(command);
+            case "agent.checkScope":
+                return (0, agent_service_1.handleAgentCheckScope)(command);
+            case "agent.requestDecision":
+                return (0, agent_service_1.handleAgentRequestDecision)(command);
+            case "agent.checkGuidance":
+                return (0, agent_service_1.handleAgentCheckGuidance)(command);
+            case "agent.reportProgress":
+                return (0, agent_service_1.handleAgentReportProgress)(command);
+            case "agent.reportBlocker":
+                return (0, agent_service_1.handleAgentReportBlocker)(command);
+            case "agent.reportComplete":
+                return (0, agent_service_1.handleAgentReportComplete)(command);
+            case "agent.senseTurn":
+                return handleAgentSenseTurn(command);
+            /* v8 ignore stop */
             case "cron.list": {
                 const jobs = this.scheduler.listJobs();
                 const summary = jobs.length === 0
@@ -428,6 +1211,20 @@ class OuroDaemon {
                 return { ok: result.ok, message: result.message };
             }
             case "message.send": {
+                // Pure queue-only delivery. We DO NOT wake the recipient — that was
+                // the 2026-05-11 $50 bleed. The Claude Code post-tool-use hook
+                // (cli-exec.ts) intentionally sends only message.send for tool-use
+                // events to avoid waking the agent on every tool call. The hook's
+                // intent was completely defeated by this handler calling
+                // `sendToAgent({type: "message"})`, which woke the inner-dialog
+                // worker on EVERY message.send anyway. ~30 message.send/min × the
+                // 3-turn instinct-loop cap = ~90 turns/min sustained for hours.
+                //
+                // Callers that want immediate processing must send `inner.wake`
+                // explicitly after message.send. The CLI `ouro msg` does so
+                // (lifecycle-boundary delivery should wake); the hook does so
+                // only on session-start / stop, not per tool-use; the API does
+                // not (notifications go to the queue).
                 const receipt = await this.router.send({
                     from: command.from,
                     to: command.to,
@@ -436,7 +1233,6 @@ class OuroDaemon {
                     sessionId: command.sessionId,
                     taskRef: command.taskRef,
                 });
-                this.processManager.sendToAgent?.(command.to, { type: "message" });
                 return { ok: true, message: `queued message ${receipt.id}`, data: receipt };
             }
             case "message.poll": {
@@ -476,10 +1272,48 @@ class OuroDaemon {
                     data: receipt,
                 };
             }
+            case "habit.poke": {
+                this.processManager.sendToAgent?.(command.agent, { type: "habit", habitName: command.habitName });
+                return {
+                    ok: true,
+                    message: `poked habit ${command.habitName} for ${command.agent}`,
+                };
+            }
+            case "await.poke": {
+                this.processManager.sendToAgent?.(command.agent, { type: "await", awaitName: command.awaitName });
+                return {
+                    ok: true,
+                    message: `poked await ${command.awaitName} for ${command.agent}`,
+                };
+            }
+            case "mcp.list": {
+                (0, identity_1.setAgentName)(command.agent ?? "default");
+                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": {
+                (0, identity_1.setAgentName)(command.agent ?? "default");
+                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,
-                    message: "hatch flow is stubbed in Gate 3 and completed in Gate 6",
+                    message: "hatch flow is stubbed; the interactive implementation lands in a later milestone",
                 };
             default:
                 return {