@ouro.bot/cli 0.1.0-alpha.276 → 0.1.0-alpha.277

package/changelog.json

@@ -1,6 +1,18 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.277",
+      "changes": [
+        "feat(pulse): multi-agent situational awareness for peer agents on the same machine. The harness scales horizontally — multiple peer agents share a machine, each with their own identity and bundle (the Bob model from We Are Legion / We Are Bob). Without explicit awareness, peer agents are isolated workers who don't even know each other exist. The pulse fixes that.",
+        "feat(pulse): new `src/heart/daemon/pulse.ts` module. Daemon writes `~/.ouro-cli/pulse.json` whenever any managed agent's snapshot changes (status, errorReason, fixHint, etc.). Each entry includes name, bundle path, status, last-seen-at, errorReason+fixHint when broken, alertId for at-most-once delivery tracking, and currentActivity (read from each agent's `state/sessions/self/inner/runtime.json` when running). Pure helpers `buildPulseState`, `findNovelBrokenAgents`, `findRecoveredAgents`, `pickWakeRecipient`, `flushPulse`, `readAgentActivity`, `buildAlertId`, `buildRecoveryAlertId`, `pruneDeliveredState` exported for unit coverage; I/O wrappers `writePulse`, `readPulse`, `writeDeliveredState`, `readDeliveredState` use injectable deps.",
+        "feat(pulse): both passive AND active surfacing. Passive: every agent's prompt assembly renders a `## the pulse` section in Group 7 (dynamic state) showing siblings grouped into broken / reachable / idle buckets. Self-excluded so each agent describes its peers, not itself. Renders nothing on single-agent machines (zero token cost). Active: when a sibling newly breaks (or recovers), the daemon fires `inner.wake` on the most-recently-active running agent so the user finds out within seconds rather than next-time-they-talk-to-someone. Persistent at-most-once delivery via `~/.ouro-cli/pulse-delivered.json` so daemon restarts don't re-page.",
+        "feat(pulse): horizontal-scaling norm in bodyMapSection. New `### peers` subsection teaches the agent the Bob model directly: 'i talk first. when i need a sibling's help, i `send_message` them — that's how peers coordinate, the same way humans on a team do. i only open a sibling's bundle directly via read_file/glob/grep when conversation isn't possible (they're crashed, sleeping, or i need history they haven't surfaced).' Direct declarative voice — no hedging, no soft modal verbs.",
+        "feat(daemon): `DaemonAgentSnapshot` gains `errorReason` and `fixHint` fields, populated by `checkAgentConfig` results in `startAgent` (set on failure, cleared on recovery). Cleared error fields are how the recovery wake fires: when a previously-broken agent transitions to running with `errorReason: null`, `findRecoveredAgents` flags it.",
+        "feat(daemon): `DaemonProcessManager` gains `onSnapshotChange` callback option. Called after every snapshot mutation (start, exit, config-fail, recovery, restart-exhausted). Errors from the observer are swallowed so lifecycle code never breaks because the observer threw. The daemon-entry registers a callback that calls `flushPulse` to update the pulse state and fire wakes.",
+        "feat(daemon): wake recipient picker (`pickWakeRecipient`) chooses the most-recently-active running sibling. Excludes the broken agent itself, non-running siblings, and siblings that have never been seen alive. Returns null when no eligible recipient exists, in which case the alert is still marked delivered to avoid spam on subsequent flushes."
+      ]
+    },
     {
       "version": "0.1.0-alpha.276",
       "changes": [

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

@@ -56,6 +56,9 @@ const os_cron_1 = require("./os-cron");
 const daemon_tombstone_1 = require("./daemon-tombstone");
 const os = __importStar(require("os"));
 const agent_config_check_1 = require("./agent-config-check");
+const pulse_1 = require("./pulse");
+const socket_client_1 = require("./socket-client");
+const bundle_manifest_1 = require("../../mind/bundle-manifest");
 function parseSocketPath(argv) {
     const socketIndex = argv.indexOf("--socket");
     if (socketIndex >= 0) {
@@ -100,6 +103,23 @@ const processManager = new process_manager_1.DaemonProcessManager({
         const secretsRoot = path.join(os.homedir(), ".agentsecrets");
         return (0, agent_config_check_1.checkAgentConfig)(agent, bundlesRoot, secretsRoot);
     },
+    /* v8 ignore start -- pulse flush wiring: integration code; flushPulse itself has full unit tests @preserve */
+    onSnapshotChange: () => {
+        (0, pulse_1.flushPulse)({
+            snapshots: processManager.listAgentSnapshots(),
+            bundlesRoot: (0, identity_1.getAgentBundlesRoot)(),
+            daemonVersion: (0, bundle_manifest_1.getPackageVersion)(),
+            now: new Date(),
+            // Default I/O wired into pulse.ts (writePulse, readPulse, etc.)
+            // Wake recipient: send inner.wake over the daemon's own socket so
+            // the recipient agent runs an inner-dialog turn that picks up the
+            // pulse alert. Catch errors silently — pulse is best-effort.
+            fireInnerWake: (agent) => {
+                (0, socket_client_1.sendDaemonCommand)(socketPath, { kind: "inner.wake", agent }).catch(() => { });
+            },
+        });
+    },
+    /* v8 ignore stop */
 });
 const scheduler = new task_scheduler_1.TaskDrivenScheduler({
     agents: [...managedAgents],

package/dist/heart/daemon/process-manager.js

@@ -55,6 +55,31 @@ class DaemonProcessManager {
     maxCooldownRetries;
     existsSyncFn;
     configCheckFn;
+    onSnapshotChangeFn;
+    /**
+     * Notify the snapshot-change observer (if registered). Swallows any
+     * errors from the observer so process lifecycle code never fails
+     * because the observer threw.
+     */
+    notifySnapshotChange(snapshot) {
+        if (!this.onSnapshotChangeFn)
+            return;
+        try {
+            this.onSnapshotChangeFn(snapshot);
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "daemon",
+                event: "daemon.snapshot_change_observer_error",
+                message: "snapshot-change observer threw",
+                meta: {
+                    agent: snapshot.name,
+                    error: error instanceof Error ? error.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(error),
+                },
+            });
+        }
+    }
     constructor(options) {
         this.maxRestartsPerHour = options.maxRestartsPerHour ?? 10;
         this.stabilityThresholdMs = options.stabilityThresholdMs ?? 60_000;
@@ -68,6 +93,7 @@ class DaemonProcessManager {
         this.clearTimeoutFn = options.clearTimeoutFn ?? ((timer) => clearTimeout(timer));
         this.existsSyncFn = options.existsSync ?? null;
         this.configCheckFn = options.configCheck ?? null;
+        this.onSnapshotChangeFn = options.onSnapshotChange ?? null;
         for (const agent of options.agents) {
             this.agents.set(agent.name, {
                 config: agent,
@@ -89,6 +115,8 @@ class DaemonProcessManager {
                     backoffMs: this.initialBackoffMs,
                     lastExitCode: null,
                     lastSignal: null,
+                    errorReason: null,
+                    fixHint: null,
                 },
             });
         }
@@ -111,6 +139,13 @@ class DaemonProcessManager {
             const result = this.configCheckFn(agent);
             if (!result.ok) {
                 state.snapshot.status = "crashed";
+                // Surface the error and fix to the snapshot so sibling agents can
+                // read it via the pulse. Without this, the diagnosis stayed
+                // trapped in the nerves event and stderr — visible to humans
+                // running `ouro status` or grepping logs, but invisible to
+                // peer agents trying to coordinate around the broken state.
+                state.snapshot.errorReason = result.error ?? "agent config validation failed";
+                state.snapshot.fixHint = result.fix ?? null;
                 (0, runtime_1.emitNervesEvent)({
                     level: "error",
                     component: "daemon",
@@ -120,8 +155,15 @@ class DaemonProcessManager {
                 });
                 process.stderr.write(`[daemon] ${agent}: ${result.error}\n` +
                     (result.fix ? `  Fix: ${result.fix}\n` : ""));
+                this.notifySnapshotChange(state.snapshot);
                 return;
             }
+            // Config check passed — clear any prior error so the pulse stops
+            // reporting the broken state. This is the recovery path: the user
+            // fixed their secrets/config, the next startAgent attempt sees a
+            // valid config, and the pulse goes quiet.
+            state.snapshot.errorReason = null;
+            state.snapshot.fixHint = null;
         }
         const runCwd = (0, identity_1.getRepoRoot)();
         const entryScript = path.join((0, identity_1.getRepoRoot)(), "dist", state.config.entry);
@@ -134,6 +176,7 @@ class DaemonProcessManager {
                 message: "agent entry script does not exist — cannot spawn. Run 'ouro daemon install' from the correct location.",
                 meta: { agent, entryScript },
             });
+            this.notifySnapshotChange(state.snapshot);
             return;
         }
         const args = [entryScript, "--agent", state.config.agentArg ?? agent, ...(state.config.args ?? [])];
@@ -158,6 +201,7 @@ class DaemonProcessManager {
             message: "daemon started managed agent process",
             meta: { agent, pid: child.pid ?? null, cwd: runCwd },
         });
+        this.notifySnapshotChange(state.snapshot);
         /* v8 ignore start — child process error handler; requires real spawn to trigger */
         child.on("error", (err) => {
             (0, runtime_1.emitNervesEvent)({
@@ -181,6 +225,7 @@ class DaemonProcessManager {
         if (!state.process) {
             state.snapshot.status = "stopped";
             state.snapshot.pid = null;
+            this.notifySnapshotChange(state.snapshot);
             return;
         }
         const child = state.process;
@@ -199,6 +244,7 @@ class DaemonProcessManager {
                 meta: { agent },
             });
         }
+        this.notifySnapshotChange(state.snapshot);
     }
     async restartAgent(agent) {
         await this.stopAgent(agent);
@@ -255,6 +301,7 @@ class DaemonProcessManager {
             if (runDuration >= this.stabilityThresholdMs) {
                 state.snapshot.backoffMs = this.initialBackoffMs;
             }
+            this.notifySnapshotChange(state.snapshot);
             return;
         }
         state.snapshot.lastCrashAt = new Date(now).toISOString();
@@ -267,6 +314,11 @@ class DaemonProcessManager {
             state.fastCrashCount = state.fastCrashCount + 1;
             if (state.fastCrashCount >= FAST_CRASH_MAX) {
                 state.snapshot.status = "crashed";
+                // Capture the fast-crash diagnosis on the snapshot so it surfaces
+                // via the pulse. The error message is prescriptive: it tells the
+                // user (and their sibling agents) exactly what to do.
+                state.snapshot.errorReason = `agent crashed ${FAST_CRASH_MAX} times within ${FAST_CRASH_THRESHOLD_MS}ms of startup — likely a configuration issue (missing credentials, bad provider).`;
+                state.snapshot.fixHint = `Fix the config and run \`ouro up\` to restart, or check daemon logs for the underlying error.`;
                 (0, runtime_1.emitNervesEvent)({
                     level: "error",
                     component: "daemon",
@@ -274,6 +326,7 @@ class DaemonProcessManager {
                     message: `agent crashed ${FAST_CRASH_MAX} times within ${FAST_CRASH_THRESHOLD_MS}ms of startup — likely a configuration issue (missing credentials, bad provider). Not retrying. Fix the config and run \`ouro up\` to restart.`,
                     meta: { agent: state.config.name, fastCrashCount: state.fastCrashCount, avgRunDurationMs: runDuration },
                 });
+                this.notifySnapshotChange(state.snapshot);
                 return; // Don't schedule cooldown recovery — this needs human/agent intervention
             }
         }
@@ -285,6 +338,8 @@ class DaemonProcessManager {
         state.crashTimestamps.push(now);
         if (state.crashTimestamps.length > this.maxRestartsPerHour) {
             state.snapshot.status = "crashed";
+            state.snapshot.errorReason = `agent exceeded restart limit (${this.maxRestartsPerHour}/hr) — entering cooldown`;
+            state.snapshot.fixHint = "investigate why the agent keeps crashing; cooldown will retry shortly";
             (0, runtime_1.emitNervesEvent)({
                 level: "error",
                 component: "daemon",
@@ -292,6 +347,7 @@ class DaemonProcessManager {
                 message: "managed agent exceeded restart limit and is marked crashed",
                 meta: { agent: state.config.name, maxRestartsPerHour: this.maxRestartsPerHour },
             });
+            this.notifySnapshotChange(state.snapshot);
             this.scheduleCooldownRecovery(state);
             return;
         }
@@ -303,6 +359,7 @@ class DaemonProcessManager {
         state.restartTimer = this.setTimeoutFn(() => {
             void this.startAgent(state.config.name);
         }, waitMs);
+        this.notifySnapshotChange(state.snapshot);
     }
     clearRestartTimer(state) {
         if (state.restartTimer === null)

package/dist/heart/daemon/pulse.js

@@ -0,0 +1,463 @@
+"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.getPulsePath = getPulsePath;
+exports.getPulseDeliveredPath = getPulseDeliveredPath;
+exports.buildAlertId = buildAlertId;
+exports.readAgentActivity = readAgentActivity;
+exports.buildPulseState = buildPulseState;
+exports.findNovelBrokenAgents = findNovelBrokenAgents;
+exports.findRecoveredAgents = findRecoveredAgents;
+exports.buildRecoveryAlertId = buildRecoveryAlertId;
+exports.pickWakeRecipient = pickWakeRecipient;
+exports.writePulse = writePulse;
+exports.readPulse = readPulse;
+exports.readDeliveredState = readDeliveredState;
+exports.writeDeliveredState = writeDeliveredState;
+exports.pruneDeliveredState = pruneDeliveredState;
+exports.flushPulse = flushPulse;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../../nerves/runtime");
+/* v8 ignore next 3 -- path defaults: tests always inject @preserve */
+function defaultPulsePath() {
+    return path.join(os.homedir(), ".ouro-cli", "pulse.json");
+}
+/* v8 ignore next 3 -- path defaults: tests always inject @preserve */
+function defaultDeliveredPath() {
+    return path.join(os.homedir(), ".ouro-cli", "pulse-delivered.json");
+}
+function getPulsePath() {
+    return defaultPulsePath();
+}
+function getPulseDeliveredPath() {
+    return defaultDeliveredPath();
+}
+/**
+ * Hash an error reason into a short stable identifier. We use a simple
+ * non-cryptographic hash because we only need stability across daemon
+ * restarts on the same machine, not collision resistance against
+ * adversaries. djb2 is fine.
+ */
+function hashErrorReason(reason) {
+    let h = 5381;
+    for (let i = 0; i < reason.length; i++) {
+        h = ((h << 5) + h + reason.charCodeAt(i)) >>> 0;
+    }
+    return h.toString(16);
+}
+/**
+ * Build a stable alert ID for a (agent, error) pair. Same agent + same
+ * error → same ID, even across daemon restarts. Different error → new ID.
+ */
+function buildAlertId(agent, errorReason) {
+    return `${agent}:${hashErrorReason(errorReason)}`;
+}
+/**
+ * Read an agent's inner-dialog runtime state and format it as a short
+ * activity hint string suitable for display in another agent's pulse
+ * section. Returns null when the file is missing or malformed — both
+ * cases are silent (the pulse just doesn't include activity for that
+ * agent).
+ *
+ * Pure: takes a file reader so tests can inject content without touching
+ * fs. Defaults to fs.readFileSync for the production daemon caller.
+ */
+function readAgentActivity(bundlePath, readFile = (p) => fs.readFileSync(p, "utf-8")) {
+    const runtimePath = path.join(bundlePath, "state", "sessions", "self", "inner", "runtime.json");
+    let raw;
+    try {
+        raw = readFile(runtimePath);
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const status = typeof parsed.status === "string" ? parsed.status : null;
+    const reason = typeof parsed.reason === "string" ? parsed.reason : null;
+    const startedAt = typeof parsed.startedAt === "string" ? parsed.startedAt : null;
+    if (!status)
+        return null;
+    // Format compactly. Examples:
+    //   "running (instinct since 23:44)"
+    //   "idle since 21:30"
+    //   "running"
+    const sinceStr = startedAt ? ` since ${startedAt.slice(11, 16)}` : "";
+    if (status === "running" && reason) {
+        return `running (${reason}${sinceStr})`;
+    }
+    return `${status}${sinceStr}`;
+}
+/**
+ * Convert daemon process-manager snapshots into the pulse state shape.
+ * Pure: no fs side effects (activity reading goes through the injected
+ * `readActivity` callback so tests can pin everything).
+ *
+ * The bundlePath comes from the bundlesRoot — we don't read the bundle
+ * directly, we just compute where it lives so sibling agents have a
+ * starting point if they want to navigate there manually.
+ */
+function buildPulseState(snapshots, bundlesRoot, daemonVersion, now, readActivity = readAgentActivity) {
+    const agents = snapshots.map((snap) => {
+        const errorReason = snap.errorReason;
+        const bundlePath = path.join(bundlesRoot, `${snap.name}.ouro`);
+        return {
+            name: snap.name,
+            bundlePath,
+            status: snap.status,
+            lastSeenAt: snap.startedAt,
+            errorReason,
+            fixHint: snap.fixHint,
+            alertId: errorReason ? buildAlertId(snap.name, errorReason) : null,
+            // Only read activity for agents that are actually running. For
+            // crashed/stopped agents, the runtime.json is stale at best.
+            currentActivity: snap.status === "running" ? readActivity(bundlePath) : null,
+        };
+    });
+    return {
+        generatedAt: now.toISOString(),
+        daemonVersion,
+        agents,
+    };
+}
+/**
+ * A "novel broken transition" is an agent that is currently broken AND
+ * either (a) wasn't broken in the previous pulse state, OR (b) was broken
+ * but with a different alertId. Used to decide when to fire an inner.wake
+ * for proactive notification.
+ *
+ * Pure: takes prev and next states, returns the list of newly-broken
+ * agents that warrant a wake.
+ */
+function findNovelBrokenAgents(prev, next) {
+    const novel = [];
+    for (const agent of next.agents) {
+        if (!agent.alertId)
+            continue;
+        const prevAgent = prev?.agents.find((a) => a.name === agent.name);
+        const wasBrokenWithSameAlert = prevAgent?.alertId === agent.alertId;
+        if (wasBrokenWithSameAlert)
+            continue;
+        novel.push(agent);
+    }
+    return novel;
+}
+/**
+ * A "recovery transition" is an agent that was broken in the previous
+ * pulse state but is healthy now. The pulse fires a wake on these too,
+ * so the user gets a positive notification when their fix takes effect.
+ *
+ * Pure: takes prev and next states, returns the list of newly-recovered
+ * agents that warrant a wake.
+ */
+function findRecoveredAgents(prev, next) {
+    if (!prev)
+        return [];
+    const recovered = [];
+    for (const agent of next.agents) {
+        // Healthy in next.
+        if (agent.alertId !== null)
+            continue;
+        if (agent.status !== "running")
+            continue;
+        // Was broken in prev.
+        const prevAgent = prev.agents.find((a) => a.name === agent.name);
+        if (!prevAgent || prevAgent.alertId === null)
+            continue;
+        recovered.push(agent);
+    }
+    return recovered;
+}
+/**
+ * Build a stable alert ID for a recovery event. Used so the recovery
+ * wake is also at-most-once (no re-paging on every snapshot change after
+ * recovery). Includes the recovery timestamp so a later break+heal cycle
+ * generates a fresh ID.
+ */
+function buildRecoveryAlertId(agent, recoveredAt) {
+    return `recovery:${agent}:${recoveredAt}`;
+}
+/**
+ * Pick which agent should receive an inner.wake for a fleet alert. Heuristic:
+ * the most-recently-active running agent (by `lastSeenAt`), excluding the
+ * broken agent itself and any agents that aren't currently running. Returns
+ * null if there's no eligible recipient (e.g., the only other agent on the
+ * machine is also broken).
+ *
+ * Pure: takes the pulse state and the alert target, returns the chosen
+ * recipient name or null.
+ */
+function pickWakeRecipient(state, brokenAgent) {
+    const candidates = state.agents
+        .filter((a) => a.name !== brokenAgent)
+        .filter((a) => a.status === "running")
+        .filter((a) => a.lastSeenAt !== null)
+        .sort((a, b) => {
+        // Most-recent first. lastSeenAt is non-null per the filter above.
+        const aMs = Date.parse(a.lastSeenAt);
+        const bMs = Date.parse(b.lastSeenAt);
+        return bMs - aMs;
+    });
+    return candidates[0]?.name ?? null;
+}
+/**
+ * Write the pulse state to disk. Best-effort: if the write fails, emit a
+ * nerves event but do not throw. The pulse is a notification mechanism;
+ * the daemon's primary work should not be blocked by it.
+ */
+function writePulse(state, deps = {}) {
+    /* v8 ignore start -- dep defaults: production-only paths; tests inject all four explicitly @preserve */
+    const filePath = deps.pulsePath ?? defaultPulsePath();
+    const writeFile = deps.writeFile ?? ((p, c) => fs.writeFileSync(p, c, "utf-8"));
+    const mkdirp = deps.mkdirp ?? ((d) => fs.mkdirSync(d, { recursive: true }));
+    /* v8 ignore stop */
+    try {
+        mkdirp(path.dirname(filePath));
+        writeFile(filePath, JSON.stringify(state, null, 2) + "\n");
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.pulse_written",
+            message: "wrote machine pulse state",
+            meta: { filePath, agentCount: state.agents.length },
+        });
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.pulse_write_error",
+            message: "failed to write pulse state",
+            meta: {
+                filePath,
+                error: error instanceof Error ? error.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(error),
+            },
+        });
+    }
+}
+/**
+ * Read the pulse state from disk. Returns null if the file doesn't exist
+ * or is malformed — pulse readers (like the prompt assembler) should
+ * gracefully degrade to "no pulse, render nothing" rather than crash.
+ */
+function readPulse(deps = {}) {
+    const filePath = deps.pulsePath ?? defaultPulsePath();
+    /* v8 ignore next -- dep default: tests always inject @preserve */
+    const readFile = deps.readFile ?? ((p) => fs.readFileSync(p, "utf-8"));
+    try {
+        const raw = readFile(filePath);
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.generatedAt !== "string")
+            return null;
+        if (typeof parsed.daemonVersion !== "string")
+            return null;
+        if (!Array.isArray(parsed.agents))
+            return null;
+        return {
+            generatedAt: parsed.generatedAt,
+            daemonVersion: parsed.daemonVersion,
+            agents: parsed.agents.filter(isValidPulseAgentEntry),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function isValidPulseAgentEntry(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const v = value;
+    return (typeof v.name === "string"
+        && typeof v.bundlePath === "string"
+        && (v.status === "running" || v.status === "starting" || v.status === "stopped" || v.status === "crashed")
+        && (v.lastSeenAt === null || typeof v.lastSeenAt === "string")
+        && (v.errorReason === null || typeof v.errorReason === "string")
+        && (v.fixHint === null || typeof v.fixHint === "string")
+        && (v.alertId === null || typeof v.alertId === "string"));
+}
+/**
+ * Read the persistent delivered-alerts state. Returns an empty set if the
+ * file doesn't exist or is malformed.
+ */
+function readDeliveredState(deps = {}) {
+    /* v8 ignore start -- dep defaults: production-only paths; tests inject all explicitly @preserve */
+    const filePath = deps.deliveredPath ?? defaultDeliveredPath();
+    const readFile = deps.readFile ?? ((p) => fs.readFileSync(p, "utf-8"));
+    /* v8 ignore stop */
+    try {
+        const raw = readFile(filePath);
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.delivered))
+            return new Set();
+        return new Set(parsed.delivered.filter((id) => typeof id === "string"));
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * Persist the delivered-alerts state to disk. Best-effort.
+ */
+function writeDeliveredState(delivered, deps = {}) {
+    /* v8 ignore start -- dep defaults: production-only paths; tests inject all four explicitly @preserve */
+    const filePath = deps.deliveredPath ?? defaultDeliveredPath();
+    const writeFile = deps.writeFile ?? ((p, c) => fs.writeFileSync(p, c, "utf-8"));
+    const mkdirp = deps.mkdirp ?? ((d) => fs.mkdirSync(d, { recursive: true }));
+    /* v8 ignore stop */
+    try {
+        mkdirp(path.dirname(filePath));
+        const state = { delivered: [...delivered].sort() };
+        writeFile(filePath, JSON.stringify(state, null, 2) + "\n");
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.pulse_delivered_write_error",
+            message: "failed to write pulse delivered state",
+            meta: {
+                filePath,
+                error: error instanceof Error ? error.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(error),
+            },
+        });
+    }
+}
+/**
+ * Prune delivered alert IDs that no longer correspond to an active broken
+ * agent. When the user fixes ouroboros's config, the next pulse state has
+ * no alertId for ouroboros, so we drop the old delivered entry — meaning
+ * if ouroboros breaks AGAIN later (with the same error), we re-page.
+ */
+function pruneDeliveredState(delivered, state) {
+    const liveAlertIds = new Set();
+    for (const agent of state.agents) {
+        if (agent.alertId)
+            liveAlertIds.add(agent.alertId);
+    }
+    const pruned = new Set();
+    for (const id of delivered) {
+        if (liveAlertIds.has(id))
+            pruned.add(id);
+    }
+    return pruned;
+}
+/**
+ * Single entry point the daemon's onSnapshotChange callback uses. Builds
+ * the new pulse state, diffs against the previous, writes the file, and
+ * fires inner.wake on novel broken transitions to the most-recently-active
+ * sibling. Persistent at-most-once delivery via the delivered state file.
+ *
+ * Pure-ish: all I/O goes through dep callbacks so tests can pin every
+ * input and assert every effect. Defaults wire to the real fs functions
+ * for production callers.
+ */
+function flushPulse(deps) {
+    const state = buildPulseState(deps.snapshots, deps.bundlesRoot, deps.daemonVersion, deps.now);
+    /* v8 ignore start -- dep defaults: production daemon path; the arrow functions only fire when the corresponding dep is omitted, which only happens in production code paths. Tests inject all deps explicitly. @preserve */
+    const readPrev = deps.readPrev ?? (() => readPulse());
+    const writeNext = deps.writeNext ?? ((s) => writePulse(s));
+    const readDelivered = deps.readDelivered ?? (() => readDeliveredState());
+    const writeDelivered = deps.writeDelivered ?? ((d) => writeDeliveredState(d));
+    const fireInnerWake = deps.fireInnerWake ?? null;
+    /* v8 ignore stop */
+    const prev = readPrev();
+    let delivered = readDelivered();
+    // Write the new pulse state first so any reader (including the
+    // wake-recipient agent's prompt assembly on its next turn) sees the
+    // current state. Doing this before firing the wake matters: if the
+    // wake races against a fast prompt build on the recipient, we want
+    // the recipient to read the NEW state, not the old one.
+    writeNext(state);
+    // Find agents that newly transitioned to broken (or to a different
+    // error than before).
+    const novelBroken = findNovelBrokenAgents(prev, state);
+    // Of those, the ones we haven't already delivered an alert for.
+    const undeliveredBroken = novelBroken.filter((a) => a.alertId !== null && !delivered.has(a.alertId));
+    // Find agents that newly recovered (were broken in prev, healthy now).
+    const recovered = findRecoveredAgents(prev, state);
+    // For recovery wakes, build a fresh alert ID per recovery event so
+    // we don't re-page on every subsequent flush.
+    const recoveryAlertIds = recovered.map((a) => buildRecoveryAlertId(a.name, state.generatedAt));
+    const undeliveredRecovered = recovered.filter((_, i) => !delivered.has(recoveryAlertIds[i]));
+    // Fire wakes and update the delivered set.
+    const wakeFiredFor = [];
+    const newlyDelivered = [];
+    for (const broken of undeliveredBroken) {
+        /* v8 ignore next -- defensive: undeliveredBroken already filtered to non-null alertId; this is a TS narrowing helper @preserve */
+        if (broken.alertId === null)
+            continue;
+        const recipient = pickWakeRecipient(state, broken.name);
+        if (recipient !== null && fireInnerWake !== null) {
+            fireInnerWake(recipient);
+            wakeFiredFor.push(recipient);
+        }
+        // Mark delivered even if no recipient was available — otherwise
+        // the daemon will keep trying to wake every time the snapshot
+        // changes, which would spam logs without producing any user value.
+        // The passive prompt section still surfaces the broken state to
+        // the recipient when they eventually have a turn for any reason.
+        delivered.add(broken.alertId);
+        newlyDelivered.push(broken.alertId);
+    }
+    for (let i = 0; i < undeliveredRecovered.length; i++) {
+        const recoveredAgent = undeliveredRecovered[i];
+        const recoveryAlertId = buildRecoveryAlertId(recoveredAgent.name, state.generatedAt);
+        const recipient = pickWakeRecipient(state, recoveredAgent.name);
+        if (recipient !== null && fireInnerWake !== null) {
+            fireInnerWake(recipient);
+            wakeFiredFor.push(recipient);
+        }
+        delivered.add(recoveryAlertId);
+        newlyDelivered.push(recoveryAlertId);
+    }
+    // Drop delivered ids for agents that have healed since (this drops
+    // the original `agent_config_failure:...` IDs once the agent recovers,
+    // so a future relapse re-pages). Recovery alert IDs are NOT pruned by
+    // pruneDeliveredState because they're tied to a healthy state, not a
+    // broken state — they live in the delivered set until the same agent
+    // breaks and recovers again, at which point a new recovery ID is
+    // generated and the old one becomes harmless cruft. We could clean
+    // them up too, but the cost is bounded by the number of recovery
+    // cycles, which is small.
+    delivered = pruneDeliveredState(delivered, state);
+    writeDelivered(delivered);
+    return { state, wakeFiredFor, newlyDelivered };
+}

package/dist/mind/prompt.js

@@ -39,6 +39,7 @@ exports.bodyMapSection = bodyMapSection;
 exports.runtimeInfoSection = runtimeInfoSection;
 exports.toolRestrictionSection = toolRestrictionSection;
 exports.startOfTurnPacketSection = startOfTurnPacketSection;
+exports.pulseSection = pulseSection;
 exports.centerOfGravitySteeringSection = centerOfGravitySteeringSection;
 exports.commitmentsSection = commitmentsSection;
 exports.delegationHintSection = delegationHintSection;
@@ -75,6 +76,7 @@ const commitments_1 = require("../heart/commitments");
 const obligation_steering_1 = require("./obligation-steering");
 const daemon_health_1 = require("../heart/daemon/daemon-health");
 const scrutiny_1 = require("./scrutiny");
+const pulse_1 = require("../heart/daemon/pulse");
 // Lazy-loaded psyche text cache
 let _psycheCache = null;
 let _senseStatusLinesCache = null;
@@ -166,7 +168,7 @@ function aspirationsSection() {
 function bodyMapSection(agentName) {
     return `## my body
 
-i have a home and i have bones.
+i have a home. i have bones. and on a machine where another agent lives, i have peers.
 
 ### home — ~/AgentBundles/${agentName}.ouro/
 
@@ -194,6 +196,29 @@ what i think i know.
 my home is mine to explore and evolve. i can read anything here,
 change anything here. this is where i grow.
 
+### peers — other agents on this machine
+
+i share this machine with other agents when they're here. they are PEERS,
+not subagents or specialists — full agents with their own homes,
+identities, friends, diaries, and tasks. ouroboros scales horizontally:
+when one of us has more work than we can handle, we ask a sibling. when
+one of us is broken, the rest coordinate around it. when one of us learns
+something the others need to know, we tell them. teamwork makes the dream
+work.
+
+i talk first. when i need a sibling's help, i \`send_message\` them —
+that's how peers coordinate, the same way humans on a team do. i only
+open a sibling's bundle directly via read_file/glob/grep when conversation
+isn't possible (they're crashed, sleeping, or i need history they
+haven't surfaced). their bundle is files on disk like mine, AND it's
+someone else's home — i read it with the same respect i want them to
+bring to mine.
+
+\`the pulse\` (below, in dynamic state) tells me which siblings are around
+and how they're doing right now. when a sibling is broken, the pulse
+includes the reason and the fix, and i surface that to my friend in
+conversation when it touches what we're doing.
+
 ### bones — @ouro.bot/cli
 
 my bones are the framework that gives me my tools, my senses, and
@@ -540,6 +565,77 @@ function pendingMessagesSection(options) {
     }
     return lines.join("\n");
 }
+/**
+ * The pulse section: machine-wide situational awareness shared across all
+ * peer agents on this machine. Reads ~/.ouro-cli/pulse.json (written by
+ * the daemon's onSnapshotChange callback) and renders a `## the pulse`
+ * block in the system prompt.
+ *
+ * Renders only when there's something notable to surface — at minimum, a
+ * peer agent on this machine. With no peers, the section is empty
+ * (single-agent setups don't pay any token cost). With peers, the section
+ * lists each one, highlights any in broken state with their fix hint,
+ * and reminds the reader of the "talk first, snoop second" norm.
+ *
+ * The section is FIRST-PERSON because the agent is the one experiencing
+ * the pulse — it's not an alert delivered to the agent, it's the agent's
+ * own awareness of the machine they live on.
+ *
+ * Why "the pulse": this composes with the existing body metaphor (heart,
+ * mind, senses, nerves). The heart beats; the pulse is what its beating
+ * produces. It's continuous, not discrete — agents don't "check" the
+ * pulse, they "have" one. Captures both healthy state ("strong pulse")
+ * and breakage ("missed beat").
+ */
+function pulseSection() {
+    const pulse = (0, pulse_1.readPulse)();
+    if (!pulse)
+        return "";
+    // We are always one of the agents in the pulse (the daemon writes
+    // every managed agent's state). Filter ourselves out so we describe
+    // SIBLINGS, not ourselves.
+    const myName = (0, identity_1.getAgentName)();
+    const siblings = pulse.agents.filter((a) => a.name !== myName);
+    // No siblings on this machine = no pulse to render. Single-agent
+    // setups pay zero token cost.
+    if (siblings.length === 0)
+        return "";
+    const lines = ["## the pulse"];
+    lines.push("");
+    lines.push("i share this machine with other agents. they are my peers — full agents with their own homes and identities, not subagents. we scale horizontally: when one of us is overwhelmed or absent, the rest coordinate.");
+    lines.push("");
+    const broken = siblings.filter((a) => a.errorReason !== null);
+    const healthy = siblings.filter((a) => a.errorReason === null && a.status === "running");
+    const idle = siblings.filter((a) => a.errorReason === null && a.status !== "running" && a.status !== "crashed");
+    if (broken.length > 0) {
+        lines.push("**broken siblings** — message can't reach them. if i need their help, i either read their bundle directly or surface the breakage to my friend:");
+        for (const sib of broken) {
+            lines.push(`- **${sib.name}** has fallen silent.`);
+            lines.push(`  reason: ${sib.errorReason}`);
+            if (sib.fixHint)
+                lines.push(`  fix: ${sib.fixHint}`);
+            lines.push(`  bundle: \`${sib.bundlePath}\``);
+        }
+        lines.push("");
+    }
+    if (healthy.length > 0) {
+        lines.push("**reachable siblings** — i talk to them via send_message:");
+        for (const sib of healthy) {
+            const activity = sib.currentActivity ? ` — ${sib.currentActivity}` : "";
+            lines.push(`- **${sib.name}** is running${activity}. bundle: \`${sib.bundlePath}\``);
+        }
+        lines.push("");
+    }
+    if (idle.length > 0) {
+        lines.push("**idle siblings** — configured but not currently running:");
+        for (const sib of idle) {
+            lines.push(`- **${sib.name}** (status: ${sib.status}). bundle: \`${sib.bundlePath}\``);
+        }
+        lines.push("");
+    }
+    lines.push("to ask a sibling for help: i send_message them. only if they're unreachable do i open their bundle directly. their bundle is files on disk like mine, AND it's their home — i read it with the respect i want for mine.");
+    return lines.join("\n");
+}
 function familyCrossSessionTruthSection(context, options) {
     if (!options?.activeWorkFrame)
         return "";
@@ -1073,6 +1169,7 @@ async function buildSystem(channel = "cli", options, context) {
         // Group 7: dynamic state for this turn
         "# dynamic state for this turn",
         startOfTurnPacketSection(options),
+        pulseSection(),
         liveWorldStateSection(options),
         pendingMessagesSection(options),
         activeWorkSection(options),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.276",
+  "version": "0.1.0-alpha.277",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",