@ouro.bot/cli 0.1.0-alpha.514 → 0.1.0-alpha.516

package/changelog.json

@@ -1,6 +1,28 @@
 {
   "_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.516",
+      "changes": [
+        "Layer 1 of the harness-hardening sequence (1→4→2→3 from `docs/planning/2026-04-28-1900-planning-harness-hardening-and-repairguide.md`). Replaces the daemon-wide rollup at `daemon-entry.ts` (the binary `degraded.length > 0 ? \"degraded\" : \"ok\"` literal) with a five-state vocabulary: `healthy / partial / degraded / safe-mode / down`. A single sick agent no longer tips the whole daemon to `degraded`.",
+        "Type structure: `RollupStatus` (4-state, returned by the new pure `computeDaemonRollup` decision function in `daemon-rollup.ts`) and `DaemonStatus = RollupStatus | \"down\"` (full daemon-status; `down` is caller-owned because it represents pre-inventory failure, before the rollup is reachable). Both unions project from a single source-of-truth literal tuple so future widening touches one site.",
+        "`renderRollupStatusLine` in `cli-render.ts` uses a compiler-forced `never`-typed exhaustive switch — adding a future state compile-errors at every consumer using the pattern. The `degraded` literal carries three copy variants picked by inspecting cached agent statuses: empty map (fresh install, prompts `ouro hatch`), non-empty + any running agent (legacy stale cache from pre-Layer-1 daemons, prompts `ouro up` refresh), non-empty + zero running (all-failed live-check, prompts `ouro doctor`).",
+        "`runtime-readers.ts:readDaemonHealthDeep` parse tightened to use `isDaemonStatus`. `OutlookDaemonHealthDeep.status` widened to `DaemonStatus | \"unknown\"` so legacy serialized strings (`\"running\"`, `\"ok\"`) coerce defensively rather than failing the parse during rollout.",
+        "9759 tests pass (508 test files); coverage gate clean. The per-agent live-check loop in `cli-exec.ts` is intentionally untouched — it was already try/catch-isolated; the bug was in how its output rolled up. Subsequent PRs (layers 4, 2, 3) build on this PR's vocabulary."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.515",
+      "changes": [
+        "New `speak` tool — agent can deliver words to the current friend mid-turn without ending the turn. Pairs with `settle` (ends turn) and `ponder` (private inner thought). For acknowledgment of heavy work, phase-boundary updates, or progress narration on chat-style channels (cli, teams, bluebubbles).",
+        "Schema is intentionally minimal: `speak({ message: string })`. Not sole-call, doesn't terminate the turn, NOT exempt from the 24-call circuit breaker (the breaker is healthy backpressure against narration-spam — silence is a natural fallback for speak, unlike settle/rest). Added `flushNow?(): void | Promise<void>` to `ChannelCallbacks`; per-sense impls deliver the buffered message immediately (CLI noop, BlueBubbles `client.sendText` keeping typing on, Teams stream emit with `sendMessage` fallback).",
+        "Engine integration follows the `ponder` interception template at `core.ts:~1303`: `speak` runs inline (emit + flushNow + push `(spoken)` tool result + nerves event `engine.speak`), then the loop continues. Empty/missing message rejected with a tool-result error and `engine.speak_invalid`. New event keys: `engine.speak`, `engine.speak_invalid`, `engine.speak_delivery_failed`, `bluebubbles.speak_flush`, `teams.speak_flush`.",
+        "System prompt nudge in Group #4 (`how i work`), gated to chat-style channels: dependency boundary (settle if next step needs a reply, otherwise speak), phase boundaries (after acking heavy ask / hitting major constraint / switching strategy / before externally-visible step — not per-tool narration), one-way framing (speak is progress, not invitation).",
+        "Hardened `speak` delivery semantics (slugger PR review fix). `flushNow` contract is now explicit: throws if the message could not be delivered through any available path. Teams `flushNow` THROWS when both stream emit AND `sendMessage` fallback fail (was silently logging delivered=false and returning normally — engine then recorded `(spoken)` even though nothing reached the friend). BlueBubbles `flushNow` already let `client.sendText` rejections propagate; contract documented. Engine wraps `await flushNow()` in try/catch: on hard failure it calls `onToolEnd('speak', ..., false)`, pushes a `'speak delivery failed: ... did not reach your friend; do not assume they saw it'` tool result, emits `engine.speak_delivery_failed` (level=error), and the turn continues — preventing the agent from assuming silent success.",
+        "`speak` is now treated as flow-control across all senses (slugger PR review fix). Like settle/observe/ponder/rest, its only visible output is the message itself — no spinner, no phrase rotation, no `⏳` placeholder, no tool-activity status line. Added 'speak' to `FLOW_CONTROL_TOOLS` in `cli/tool-display.ts` and `cli/ouro-tui.tsx`; CLI/BlueBubbles/Teams `onToolStart` early-return for speak; `tool-description.ts` returns null for speak as defense-in-depth for any future sense using `createToolActivityCallbacks`. Teams `flushNow` also stops phrase rotation when it delivers, so the actual message replaces the cycling 'thinking...' phrase.",
+        "Teams `flushNow` no longer aborts the turn on a successful sendMessage fallback (slugger PR review fix). Prior code path: stream emit fails → `tryEmit` calls `markStopped()` which calls `controller.abort()` → falls through to `sendMessage` → succeeds → `flushNow` returns normally → core records `(spoken)` with success=true — but the turn controller is already aborted, so the next model/tool step aborts. Successful fallback delivery should not poison the rest of the turn. Fix adds a non-aborting `tryEmitNoAbort` variant adjacent to `tryEmit`; `flushNow` uses it so a primary-stream failure followed by a successful sendMessage no longer triggers `controller.abort()`. Only when ALL delivery paths fail does `flushNow` call `markStopped()` and throw, letting the engine's existing `engine.speak_delivery_failed` catch path end the turn cleanly. `tryEmit` and other non-flushNow callers (end-of-turn `flush()`, `safeEmit`) are unchanged — their abort-on-failure behavior remains correct because they have no fallback path forward."
+      ]
+    },
     {
       "version": "0.1.0-alpha.514",
       "changes": [

package/dist/heart/core.js

@@ -6,6 +6,7 @@ exports.getModel = getModel;
 exports.getProvider = getProvider;
 exports.createSummarize = createSummarize;
 exports.getProviderDisplayLabel = getProviderDisplayLabel;
+exports.isChatStyleChannel = isChatStyleChannel;
 exports.isExternalStateQuery = isExternalStateQuery;
 exports.getSettleRetryError = getSettleRetryError;
 exports.stripLastToolCalls = stripLastToolCalls;
@@ -211,6 +212,12 @@ function hasFreshPendingWork(options) {
     return pendingMessages.some((message) => typeof message?.content === "string"
         && message.content.trim().length > 0);
 }
+/** Chat-style channels expose the `speak` tool — outer human-conversation channels
+ *  where mid-turn delivery is meaningful. Inner dialog has `ponder`. MCP returns
+ *  synchronously. Mail is batch. Anything else (unknown channel) treats as non-chat. */
+function isChatStyleChannel(channel) {
+    return channel === "cli" || channel === "teams" || channel === "bluebubbles";
+}
 // Sole-call tools must be the only tool call in a turn. When they appear
 // alongside other tools, the sole-call tool is rejected with this message.
 const SOLE_CALL_REJECTION = {
@@ -672,6 +679,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             ...(isInnerDialog ? [tools_2.surfaceToolDef, tools_1.restTool] : []),
             ...(!isInnerDialog ? [tools_1.observeTool] : []),
             ...(!isInnerDialog ? [tools_1.settleTool] : []),
+            ...(isChatStyleChannel(channel ?? "") ? [tools_1.speakTool] : []),
         ];
         const steeringFollowUps = options?.drainSteeringFollowUps?.() ?? [];
         if (steeringFollowUps.length > 0) {
@@ -1074,6 +1082,63 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     if (tc.name === "send_message" && args.friendId === "self") {
                         sawSendMessageSelf = true;
                     }
+                    if (tc.name === "speak") {
+                        let speakArgs = {};
+                        try {
+                            speakArgs = JSON.parse(tc.arguments);
+                        }
+                        catch { /* malformed */ }
+                        const speakMessage = typeof speakArgs.message === "string" ? speakArgs.message : "";
+                        const argSummary = (0, tools_1.summarizeArgs)("speak", { message: speakMessage });
+                        callbacks.onToolStart("speak", { message: speakMessage });
+                        if (speakMessage.trim().length === 0) {
+                            const err = "speak requires a non-empty `message` string.";
+                            callbacks.onToolEnd("speak", argSummary, false);
+                            messages.push({ role: "tool", tool_call_id: tc.id, content: err });
+                            providerRuntime.appendToolOutput(tc.id, err);
+                            (0, runtime_1.emitNervesEvent)({
+                                level: "warn",
+                                component: "engine",
+                                event: "engine.speak_invalid",
+                                message: "speak rejected: missing or empty message",
+                                meta: {},
+                            });
+                            continue;
+                        }
+                        callbacks.onTextChunk(speakMessage);
+                        let speakDeliveryError = null;
+                        try {
+                            await callbacks.flushNow?.();
+                        }
+                        catch (err) {
+                            speakDeliveryError = err instanceof Error ? err : new Error(String(err));
+                        }
+                        if (speakDeliveryError) {
+                            callbacks.onToolEnd("speak", argSummary, false);
+                            const failMsg = `speak delivery failed: ${speakDeliveryError.message}. the message did not reach your friend; do not assume they saw it.`;
+                            messages.push({ role: "tool", tool_call_id: tc.id, content: failMsg });
+                            providerRuntime.appendToolOutput(tc.id, failMsg);
+                            (0, runtime_1.emitNervesEvent)({
+                                level: "error",
+                                component: "engine",
+                                event: "engine.speak_delivery_failed",
+                                message: "speak delivery failed",
+                                meta: { error: speakDeliveryError.message, messageLength: speakMessage.length },
+                            });
+                            continue;
+                        }
+                        callbacks.onToolEnd("speak", argSummary, true);
+                        const ack = "(spoken)";
+                        messages.push({ role: "tool", tool_call_id: tc.id, content: ack });
+                        providerRuntime.appendToolOutput(tc.id, ack);
+                        (0, runtime_1.emitNervesEvent)({
+                            component: "engine",
+                            event: "engine.speak",
+                            message: "agent spoke mid-turn",
+                            meta: { messageLength: speakMessage.length },
+                        });
+                        continue;
+                    }
                     if (tc.name === "ponder") {
                         const parsedArgs = normalizeLegacyPonderArgs(parsePonderPayload(tc.arguments));
                         const argSummary = (0, tools_1.summarizeArgs)(tc.name, parsedArgs);

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

@@ -45,6 +45,7 @@ exports.formatTable = formatTable;
 exports.formatDaemonStatusOutput = formatDaemonStatusOutput;
 exports.formatVersionOutput = formatVersionOutput;
 exports.buildStoppedStatusPayload = buildStoppedStatusPayload;
+exports.renderRollupStatusLine = renderRollupStatusLine;
 exports.daemonUnavailableStatusOutput = daemonUnavailableStatusOutput;
 exports.isDaemonUnavailableError = isDaemonUnavailableError;
 exports.formatMcpResponse = formatMcpResponse;
@@ -472,6 +473,69 @@ function buildStoppedStatusPayload(socketPath, syncRows = [], agentRows = []) {
         providers: [],
     };
 }
+/**
+ * Render the cached daemon-rollup status as a one-line string for the
+ * "daemon not running" view. Each `DaemonStatus` literal maps to a
+ * label + a brief explanatory copy fragment. The default branch is
+ * `never`-typed so future widening of `DaemonStatus` compile-errors
+ * here — Layer 1's compiler-forced exhaustiveness contract.
+ *
+ * The `degraded` literal splits into two copy variants based on the
+ * cached health file's `agents` map:
+ * - empty map → "no agents configured" (fresh-install copy).
+ * - non-empty map → "none ready" (all-agents-failed-live-check copy).
+ *
+ * The split lives at the render layer (not in the rollup status itself)
+ * so the same status can carry distinct UX copy without inflating the
+ * type union.
+ */
+function renderRollupStatusLine(health) {
+    const status = health.status;
+    const tail = `(pid ${health.pid}, uptime ${health.uptimeSeconds}s)`;
+    /* v8 ignore next -- v8 instruments the switch statement itself as a branch; the never-typed default below is unreachable by construction so v8 cannot observe its branch firing @preserve */
+    switch (status) {
+        case "healthy":
+            return `Last known status: healthy ${tail}`;
+        case "partial":
+            return `Last known status: partial — some agents unhealthy ${tail}`;
+        case "degraded": {
+            // Three-way copy split based on the cached agents map:
+            // - empty map → fresh install / no agents configured.
+            // - non-empty + any agent reports "running" → legacy stale cache:
+            //   pre-Layer-1, status="degraded" meant "any sick component," so a
+            //   running agent could coexist with a degraded daemon. Post-Layer-1,
+            //   degraded means "zero serving" — mutually exclusive with a running
+            //   agent. A live disagreement therefore implies the cache pre-dates
+            //   the rollup-semantics fix; prompt for `ouro up` to refresh rather
+            //   than falsely claim "none ready."
+            // - non-empty + zero agents reporting "running" → all-failed copy.
+            const agentEntries = Object.values(health.agents);
+            if (agentEntries.length === 0) {
+                return `Last known status: degraded — no agents configured (run \`ouro hatch\` to add one) ${tail}`;
+            }
+            const anyRunning = agentEntries.some((agent) => agent.status === "running");
+            if (anyRunning) {
+                return `Last known status: degraded — stale cache, run \`ouro up\` to refresh ${tail}`;
+            }
+            return `Last known status: degraded — agents configured but none ready (run \`ouro doctor\`) ${tail}`;
+        }
+        case "safe-mode":
+            return `Last known status: safe-mode — crash loop tripped ${tail}`;
+        case "down":
+            return `Last known status: down ${tail}`;
+        /* v8 ignore start -- compiler-forced exhaustiveness: the never-typed default branch is unreachable by construction; if DaemonStatus widens, tsc errors at the assignment before the throw can run @preserve */
+        default: {
+            // Compiler-forced exhaustiveness. If DaemonStatus grows a new
+            // literal, this `never` cast errors at tsc, forcing every
+            // consumer to handle it explicitly. NEVER replace this with a
+            // permissive `default:` returning a fallback string — that's
+            // exactly how the old "ok | degraded" semantics leaked through.
+            const _exhaustive = status;
+            throw new Error(`unhandled daemon status: ${_exhaustive}`);
+        }
+        /* v8 ignore stop */
+    }
+}
 function daemonUnavailableStatusOutput(socketPath, healthFilePath) {
     // Read per-agent sync config and bundle list from disk so the user still
     // sees them when the daemon is down. Best-effort: any fs error returns []
@@ -515,7 +579,7 @@ function daemonUnavailableStatusOutput(socketPath, healthFilePath) {
     const resolvedHealthPath = healthFilePath ?? (0, daemon_health_1.getDefaultHealthPath)();
     const health = (0, daemon_health_1.readHealth)(resolvedHealthPath);
     if (health) {
-        lines.push(`Last known status: ${health.status} (pid ${health.pid}, uptime ${health.uptimeSeconds}s)`);
+        lines.push(renderRollupStatusLine(health));
         if (health.safeMode?.active) {
             lines.push(`SAFE MODE: ${health.safeMode.reason}`);
         }

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

@@ -43,6 +43,7 @@ const index_1 = require("../../nerves/index");
 const message_router_1 = require("./message-router");
 const health_monitor_1 = require("./health-monitor");
 const daemon_health_1 = require("./daemon-health");
+const daemon_rollup_1 = require("./daemon-rollup");
 const task_scheduler_1 = require("./task-scheduler");
 const runtime_logging_1 = require("./runtime-logging");
 const sense_manager_1 = require("./sense-manager");
@@ -173,12 +174,40 @@ function buildDaemonHealthState() {
             since: snapshot.lastCrashAt ?? daemonStartedAt,
         };
     });
+    // Preserved for backwards-compatible inspection: callers (status
+    // command, outlook surface, etc.) may still read this combined list
+    // for per-component reasons. The rollup status field above is what
+    // changed meaning — the array is still the union of bootstrap +
+    // agent-derived degradation entries.
     const degraded = [
         ...degradedComponents.map((entry) => ({ ...entry })),
         ...agentDegradedComponents,
     ];
+    // Layer 1 rollup: project per-agent snapshots into the minimal
+    // AgentRollupInput shape and let computeDaemonRollup decide. The
+    // input is "every enabled agent" — managedAgents was filtered via
+    // listEnabledBundleAgents at module init, and snapshots only covers
+    // agents the process manager was told to manage, so by construction
+    // these entries are all enabled. The rollup function is a pure
+    // declarative function on the data we hand it.
+    //
+    // Note: safe-mode is wired as `false` here. Existing crash-loop
+    // detection (safe-mode.ts) already runs at the daemon-up boot path
+    // (cli-exec.ts), not from inside the daemon process itself. Once
+    // the daemon is up and reaching this rollup, safe mode no longer
+    // applies — the daemon is by definition past the crash-loop gate.
+    // If a future PR moves safe-mode signal into the running daemon,
+    // wire it through this third argument.
+    const rollupStatus = (0, daemon_rollup_1.computeDaemonRollup)({
+        enabledAgents: snapshots.map((snapshot) => ({
+            name: snapshot.name,
+            status: snapshot.status,
+        })),
+        bootstrapDegraded: degradedComponents,
+        safeMode: false,
+    });
     return {
-        status: degraded.length > 0 ? "degraded" : "ok",
+        status: rollupStatus,
         mode,
         pid: process.pid,
         startedAt: daemonStartedAt,

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

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HEALTH_TRACKED_EVENTS = exports.DaemonHealthWriter = void 0;
+exports.isRollupStatus = isRollupStatus;
+exports.isDaemonStatus = isDaemonStatus;
 exports.getDefaultHealthPath = getDefaultHealthPath;
 exports.createHealthNervesSink = createHealthNervesSink;
 exports.readHealth = readHealth;
@@ -41,6 +43,38 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const runtime_1 = require("../../nerves/runtime");
+/**
+ * Daemon-wide rollup vocabulary — locked layer-1 contract.
+ *
+ * - `RollupStatus` is what `computeDaemonRollup` returns (post-inventory,
+ *   four-state). The function never returns `"down"` because by the time
+ *   the rollup is reachable the daemon has already started, opened its
+ *   socket, and read its agent inventory — pre-inventory failure is the
+ *   caller's domain.
+ * - `DaemonStatus` is what `DaemonHealthState.status` accepts. The caller
+ *   widens the rollup result with `"down"` along the daemon-entry failure
+ *   path (e.g. when the daemon process can't read inventory at all).
+ *
+ * `isRollupStatus` and `isDaemonStatus` are runtime guards used both by
+ * `readHealth` (validating cached health files on disk) and by render-side
+ * consumers that want to narrow `unknown` JSON into the typed union before
+ * branching on it.
+ */
+// Single source of truth — the literal lists below are the runtime
+// projection of the type unions. A future literal added to RollupStatus
+// MUST also be added to ROLLUP_STATUS_LITERALS or `satisfies` blows up
+// at tsc. That tightens the Layer 1 contract: producer + consumer +
+// guard all stay in lockstep.
+const ROLLUP_STATUS_LITERALS = ["healthy", "partial", "degraded", "safe-mode"];
+const DAEMON_STATUS_LITERALS = [...ROLLUP_STATUS_LITERALS, "down"];
+const ROLLUP_STATUS_VALUES = new Set(ROLLUP_STATUS_LITERALS);
+const DAEMON_STATUS_VALUES = new Set(DAEMON_STATUS_LITERALS);
+function isRollupStatus(value) {
+    return typeof value === "string" && ROLLUP_STATUS_VALUES.has(value);
+}
+function isDaemonStatus(value) {
+    return typeof value === "string" && DAEMON_STATUS_VALUES.has(value);
+}
 class DaemonHealthWriter {
     healthPath;
     constructor(healthPath) {
@@ -111,7 +145,7 @@ function readHealth(healthPath) {
     try {
         const raw = fs.readFileSync(healthPath, "utf-8");
         const parsed = JSON.parse(raw);
-        if (typeof parsed.status !== "string" ||
+        if (!isDaemonStatus(parsed.status) ||
             typeof parsed.mode !== "string" ||
             typeof parsed.pid !== "number" ||
             typeof parsed.startedAt !== "string" ||

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

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeDaemonRollup = computeDaemonRollup;
+/**
+ * Pure rollup decision function — given the post-inventory daemon
+ * surface, returns the daemon-wide rollup state per the locked Layer 1
+ * vocabulary table:
+ *
+ *   | rollup     | when                                                      |
+ *   | ---------- | --------------------------------------------------------- |
+ *   | healthy    | every enabled agent serving + no bootstrap-degraded + no safe-mode |
+ *   | partial    | (≥1 serving + ≥1 not serving) OR (all serving + ≥1 bootstrap-degraded) |
+ *   | degraded   | zero enabled agents serving (fresh install OR all unhealthy)        |
+ *   | safe-mode  | `safeMode === true` overrides everything else                       |
+ *
+ * The function NEVER returns `"down"`. By the time `computeDaemonRollup`
+ * is reachable, the daemon process has started, opened its socket, and
+ * read its agent inventory — pre-inventory failure is the caller's
+ * domain. `daemon-entry.ts`'s startup-failure path assigns `"down"` to
+ * `DaemonHealthState.status` directly without consulting this function.
+ */
+function computeDaemonRollup(input) {
+    // Safe mode wins, period. Crash-loop detection trumps everything —
+    // we want the human to see SAFE MODE, not a noisy partial/degraded.
+    if (input.safeMode) {
+        return "safe-mode";
+    }
+    // Count serving agents. "Serving" = "running" worker status.
+    // Anything else (crashed/stopped/starting/etc) is not serving.
+    let serving = 0;
+    let notServing = 0;
+    for (const agent of input.enabledAgents) {
+        if (agent.status === "running") {
+            serving++;
+        }
+        else {
+            notServing++;
+        }
+    }
+    // Zero-serving wins over bootstrap-degraded — we have no working
+    // agents to surface a "partially working" story about. This covers
+    // both fresh-install (`enabledAgents.length === 0`) and
+    // all-failed-live-check (`serving === 0` with `notServing > 0`).
+    // Render layer (cli-render.ts) splits the UX copy by inspecting the
+    // agents map; the rollup itself doesn't carry the distinction.
+    if (serving === 0) {
+        return "degraded";
+    }
+    // From here we have ≥1 serving agent. The remaining choice is
+    // healthy vs partial.
+    const hasUnhealthyAgent = notServing > 0;
+    const hasBootstrapDegraded = input.bootstrapDegraded.length > 0;
+    if (hasUnhealthyAgent || hasBootstrapDegraded) {
+        return "partial";
+    }
+    return "healthy";
+}

package/dist/heart/outlook/readers/runtime-readers.js

@@ -49,6 +49,7 @@ const runtime_1 = require("../../../nerves/runtime");
 const habit_parser_1 = require("../../habits/habit-parser");
 const habit_runtime_state_1 = require("../../habits/habit-runtime-state");
 const identity_1 = require("../../identity");
+const daemon_health_1 = require("../../daemon/daemon-health");
 const shared_1 = require("./shared");
 const agent_machine_1 = require("./agent-machine");
 const sessions_1 = require("./sessions");
@@ -270,7 +271,12 @@ function readDaemonHealthDeep(healthPath) {
         const raw = fs.readFileSync(resolvedPath, "utf-8");
         const health = JSON.parse(raw);
         return {
-            status: typeof health.status === "string" ? health.status : "unknown",
+            // Layer 1: tighten the parse so only post-Layer-1 vocabulary
+            // carries through. Stale cached files that still hold legacy
+            // string values like "ok" or "running" — written by an older
+            // daemon binary — fall back to "unknown" so downstream Outlook
+            // consumers can detect the unparseable case explicitly.
+            status: (0, daemon_health_1.isDaemonStatus)(health.status) ? health.status : "unknown",
             mode: typeof health.mode === "string" ? health.mode : "unknown",
             pid: typeof health.pid === "number" ? health.pid : 0,
             startedAt: typeof health.startedAt === "string" ? health.startedAt : "",

package/dist/heart/tool-description.js

@@ -114,6 +114,10 @@ const TOOL_DESCRIPTIONS = {
     settle: () => null,
     rest: () => null,
     descend: () => null,
+    // speak's visible output is the message itself, delivered via onTextChunk +
+    // flushNow. The shared tool-activity callbacks must skip it so no per-sense
+    // tool-status text precedes the actual message.
+    speak: () => null,
 };
 function humanReadableToolDescription(name, args) {
     (0, runtime_1.emitNervesEvent)({

package/dist/mind/prompt.js

@@ -46,6 +46,7 @@ exports.commitmentsSection = commitmentsSection;
 exports.delegationHintSection = delegationHintSection;
 exports.workspaceDisciplineSection = workspaceDisciplineSection;
 exports.ponderPacketSopsSection = ponderPacketSopsSection;
+exports.speakSopsSection = speakSopsSection;
 exports.contextSection = contextSection;
 exports.metacognitiveFramingSection = metacognitiveFramingSection;
 exports.readJournalFiles = readJournalFiles;
@@ -991,6 +992,20 @@ function ponderPacketSopsSection() {
 - research: investigate the bounded question, gather evidence, and surface the answer or concrete artifact.
 - reflection: ordinary private thinking with no engineering workflow implied.`;
 }
+function speakSopsSection(channel) {
+    const isChatStyle = channel === "cli" || channel === "teams" || channel === "bluebubbles";
+    if (!isChatStyle)
+        return "";
+    return [
+        "## speaking mid-turn",
+        "",
+        "i have a `speak` tool that sends words to my friend without ending my turn. i use it to keep my friend in the loop while i'm doing real work.",
+        "",
+        "- if my next step depends on a reply, i settle. otherwise, i speak.",
+        "- i speak at phase boundaries during heavy work — after acking a heavy ask, after hitting a major constraint, before switching strategy, before a long externally-visible step. i don't narrate individual tool calls.",
+        "- speak is progress, not invitation. my friend won't steer me mid-turn after i speak — if i need steering, i settle.",
+    ].join("\n");
+}
 function contextSection(context, options) {
     if (!context)
         return "";
@@ -1311,6 +1326,7 @@ async function buildSystem(channel = "cli", options, context) {
         "# how i work",
         workspaceDisciplineSection(),
         ponderPacketSopsSection(),
+        speakSopsSection(channel),
         (0, scrutiny_1.preImplementationScrutinySection)(channelHasCodingTools(channel, options?.providerCapabilities)),
         toolRestrictionSection(context),
         loopOrientationSection(channel),

package/dist/nerves/coverage/file-completeness.js

@@ -87,6 +87,12 @@ const DISPATCH_EXEMPT_PATTERNS = [
     // HTTP health probe: pure HTTP utility factory. The HealthMonitor caller
     // owns observability via daemon.health_result events.
     "daemon/http-health-probe",
+    // Rollup decision function: pure decision tree mapping per-agent
+    // snapshots + bootstrap-degraded entries + safe-mode flag to a
+    // RollupStatus. No side effects. The caller (daemon-entry.ts
+    // buildDaemonHealthState → DaemonHealthWriter) owns observability via
+    // daemon.health_written when the rolled-up state is persisted.
+    "daemon/daemon-rollup",
     // Attachment helper modules: generic file-path/extension utilities and the
     // source registry are pure support seams. The orchestrator/adapters that
     // call them own the observability.

package/dist/repertoire/tools-base.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.tools = exports.baseToolDefinitions = exports.editFileReadTracker = exports.renderInnerProgressStatus = exports.restTool = exports.settleTool = exports.observeTool = exports.ponderTool = void 0;
+exports.tools = exports.baseToolDefinitions = exports.editFileReadTracker = exports.renderInnerProgressStatus = exports.speakTool = exports.restTool = exports.settleTool = exports.observeTool = exports.ponderTool = void 0;
 const tools_files_1 = require("./tools-files");
 const tools_shell_1 = require("./tools-shell");
 const tools_notes_1 = require("./tools-notes");
@@ -24,6 +24,7 @@ Object.defineProperty(exports, "ponderTool", { enumerable: true, get: function (
 Object.defineProperty(exports, "observeTool", { enumerable: true, get: function () { return tools_flow_1.observeTool; } });
 Object.defineProperty(exports, "settleTool", { enumerable: true, get: function () { return tools_flow_1.settleTool; } });
 Object.defineProperty(exports, "restTool", { enumerable: true, get: function () { return tools_flow_1.restTool; } });
+Object.defineProperty(exports, "speakTool", { enumerable: true, get: function () { return tools_flow_1.speakTool; } });
 // Re-export renderInnerProgressStatus for consumers
 var tools_session_2 = require("./tools-session");
 Object.defineProperty(exports, "renderInnerProgressStatus", { enumerable: true, get: function () { return tools_session_2.renderInnerProgressStatus; } });

package/dist/repertoire/tools-flow.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.restTool = exports.settleTool = exports.observeTool = exports.ponderTool = void 0;
+exports.restTool = exports.speakTool = exports.settleTool = exports.observeTool = exports.ponderTool = void 0;
 exports.ponderTool = {
     type: "function",
     function: {
@@ -83,6 +83,20 @@ exports.settleTool = {
         },
     },
 };
+exports.speakTool = {
+    type: "function",
+    function: {
+        name: "speak",
+        description: "i speak to send words to my friend mid-turn without ending it. for progress, acknowledgment, or phase-boundary updates during heavy work. i settle when my work is done or i need a reply. speak is one-way: my friend cannot steer me mid-turn after i speak.",
+        parameters: {
+            type: "object",
+            properties: {
+                message: { type: "string", description: "the words i'm sending to my friend right now" },
+            },
+            required: ["message"],
+        },
+    },
+};
 exports.restTool = {
     type: "function",
     function: {

package/dist/repertoire/tools.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.surfaceToolDef = exports.restTool = exports.ponderTool = exports.observeTool = exports.settleTool = exports.tools = void 0;
+exports.surfaceToolDef = exports.speakTool = exports.restTool = exports.ponderTool = exports.observeTool = exports.settleTool = exports.tools = void 0;
 exports.resetMcpDefinitions = resetMcpDefinitions;
 exports.getToolsForChannel = getToolsForChannel;
 exports.execTool = execTool;
@@ -32,6 +32,7 @@ Object.defineProperty(exports, "settleTool", { enumerable: true, get: function (
 Object.defineProperty(exports, "observeTool", { enumerable: true, get: function () { return tools_base_2.observeTool; } });
 Object.defineProperty(exports, "ponderTool", { enumerable: true, get: function () { return tools_base_2.ponderTool; } });
 Object.defineProperty(exports, "restTool", { enumerable: true, get: function () { return tools_base_2.restTool; } });
+Object.defineProperty(exports, "speakTool", { enumerable: true, get: function () { return tools_base_2.speakTool; } });
 // Re-export surface tool schema for consumers (e.g. heart/core.ts)
 var tools_surface_2 = require("./tools-surface");
 Object.defineProperty(exports, "surfaceToolDef", { enumerable: true, get: function () { return tools_surface_2.surfaceToolDef; } });

package/dist/senses/bluebubbles/index.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.enrichReactionText = enrichReactionText;
 exports.createStatusBatcher = createStatusBatcher;
+exports.createBlueBubblesCallbacks = createBlueBubblesCallbacks;
 exports.isAgentSelfHandle = isAgentSelfHandle;
 exports.getDiscoveredOwnHandles = getDiscoveredOwnHandles;
 exports.clearDiscoveredOwnHandles = clearDiscoveredOwnHandles;
@@ -514,7 +515,12 @@ function createBlueBubblesCallbacks(client, chat, replyTarget, isGroupChat) {
         },
         onReasoningChunk(_text) { },
         onToolStart(name, _args) {
-            if (name === "observe") {
+            // observe + speak are flow-control: their visible output (or lack of it) is
+            // handled outside the tool-activity callbacks. speak in particular delivers
+            // its message via onTextChunk/flushNow — we MUST NOT enqueue a "speaking..."
+            // status sendText here, which would arrive as a separate iMessage right
+            // before the actual speak content.
+            if (name === "observe" || name === "speak") {
                 (0, runtime_1.emitNervesEvent)({
                     component: "senses",
                     event: "senses.bluebubbles_tool_start",
@@ -535,7 +541,8 @@ function createBlueBubblesCallbacks(client, chat, replyTarget, isGroupChat) {
             });
         },
         onToolEnd(name, summary, success) {
-            if (name !== "observe") {
+            // observe + speak skip the tool-activity end callback (no ✓/✗ status sent).
+            if (name !== "observe" && name !== "speak") {
                 toolCallbacks.onToolEnd(name, summary, success);
             }
             (0, runtime_1.emitNervesEvent)({
@@ -558,6 +565,29 @@ function createBlueBubblesCallbacks(client, chat, replyTarget, isGroupChat) {
         onClearText() {
             textBuffer = "";
         },
+        async flushNow() {
+            // Contract: throws if delivery fails. We deliberately let `client.sendText`
+            // rejections propagate so the engine's speak interception can mark the
+            // tool call as failed and tell the agent the message did not reach the
+            // friend (rather than silently logging and pretending success).
+            const trimmed = textBuffer.trim();
+            if (!trimmed)
+                return;
+            textBuffer = "";
+            await client.sendText({
+                chat,
+                text: trimmed,
+                replyToMessageGuid: replyTarget.getReplyToMessageGuid(),
+            });
+            // Note: do NOT call client.setTyping(chat, false) here — the agent is
+            // still mid-turn, so the typing indicator stays ACTIVE.
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "bluebubbles.speak_flush",
+                message: "bluebubbles flushed mid-turn speak",
+                meta: { messageLength: trimmed.length },
+            });
+        },
         async flush() {
             statusBatcher.flush();
             await queue;

package/dist/senses/cli/ouro-tui.js

@@ -73,8 +73,10 @@ function Header({ agentName, model, contextPercent, cwd, resumeInfo }) {
     return ((0, jsx_runtime_1.jsxs)(ink_1.Box, { flexDirection: "column", children: [(0, jsx_runtime_1.jsx)(ink_1.Text, { color: OURO.scale, children: line1 }), (0, jsx_runtime_1.jsx)(ink_1.Text, { color: OURO.scale, children: line2 }), (0, jsx_runtime_1.jsxs)(ink_1.Text, { color: OURO.scale, children: [TAIL3, (0, jsx_runtime_1.jsx)(ink_1.Text, { color: OURO.glow, children: line3text }), (0, jsx_runtime_1.jsx)(ink_1.Text, { color: OURO.scale, children: HEAD3 })] }), resumeInfo ? ((0, jsx_runtime_1.jsxs)(ink_1.Text, { color: OURO.teal, children: ["  resuming \u00b7 ", resumeInfo.messageCount, " messages \u00b7 last active ", resumeInfo.timeAgo] })) : null] }));
 }
 // ─── Message Rendering ──────────────────────────────────────────────
-// Flow control tools are invisible to the user — they are internal agent mechanics
-const FLOW_CONTROL_TOOLS = new Set(["settle", "ponder", "observe", "rest"]);
+// Flow control tools are invisible to the user — they are internal agent mechanics.
+// `speak` is included because its visible output is the message itself (rendered as
+// regular assistant text), not a tool-result line or in-progress activity indicator.
+const FLOW_CONTROL_TOOLS = new Set(["settle", "ponder", "observe", "rest", "speak"]);
 function ToolResultLine({ tc }) {
     const icon = tc.success !== false ? "✓" : "✗";
     const iconColor = tc.success !== false ? OURO.scale : OURO.fang;

package/dist/senses/cli/tool-display.js

@@ -13,8 +13,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeToolStart = writeToolStart;
 exports.writeToolEnd = writeToolEnd;
 const runtime_1 = require("../../nerves/runtime");
-// Flow control tools are invisible to the user — internal agent mechanics
-const FLOW_CONTROL_TOOLS = new Set(["settle", "ponder", "observe", "rest"]);
+// Flow control tools are invisible to the user — internal agent mechanics.
+// `speak` is included because its visible output is the message itself (delivered
+// via onTextChunk/flushNow), not a "running speak..." spinner or tool-end status line.
+const FLOW_CONTROL_TOOLS = new Set(["settle", "ponder", "observe", "rest", "speak"]);
 // Ouroboros teal: #4ec9b0 -> RGB escape
 const OURO_TEAL = "\x1b[38;2;78;201;176m";
 const GREEN = "\x1b[32m";

package/dist/senses/cli.js

@@ -353,11 +353,20 @@ function createCliCallbacks() {
             /* v8 ignore stop */
             textDirty = text.length > 0 && !text.endsWith("\n");
         },
+        flushNow: () => {
+            // CLI flushes immediately on each onTextChunk; nothing buffered to push.
+        },
         onReasoningChunk: (_text) => {
             // Keep reasoning private in the CLI surface. The spinner continues to
             // represent active thinking until actual tool or answer output arrives.
         },
         onToolStart: (_name, _args) => {
+            // speak is flow-control: its visible output is the message itself (delivered
+            // via onTextChunk/flushNow). Do NOT start a tool spinner — that would write
+            // a "running speak..." phrase to stderr right before the actual message
+            // arrives, which is the visual churn the user explicitly does not want.
+            if (_name === "speak")
+                return;
             // Stop the model-start spinner: when the model returns only tool calls
             // (no content/reasoning), onModelStreamStart never fires, so the old
             // spinner's intervals would leak.

package/dist/senses/teams.js

@@ -290,6 +290,26 @@ function createTeamsCallbacks(stream, controller, sendMessage, options) {
             return false;
         }
     }
+    // Non-aborting awaitable emit — returns true on success, false on failure WITHOUT
+    // calling markStopped() / aborting the controller. Used by flushNow (speak) so a
+    // primary-stream failure followed by a successful sendMessage fallback does NOT
+    // poison the rest of the turn. tryEmit's abort-on-failure behavior is correct for
+    // end-of-turn flush() (no fallback path forward) but wrong for mid-turn speak,
+    // which has a sendMessage fallback that may still succeed. Caller (flushNow) is
+    // responsible for the `!stopped` precondition; no defensive guard here.
+    async function tryEmitNoAbort(text) {
+        try {
+            const result = stream.emit({ text, entities: aiLabelEntities(), channelData: { feedbackLoopEnabled: true } });
+            streamHasContent = true;
+            if (result && typeof result.then === "function") {
+                await result;
+            }
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     // Safely send a status update to the stream.
     // On error (e.g. 403 from Teams stop button), abort the controller.
     function safeUpdate(text) {
@@ -427,6 +447,56 @@ function createTeamsCallbacks(stream, controller, sendMessage, options) {
         onClearText: () => {
             textBuffer = "";
         },
+        flushNow: async () => {
+            const trimmed = textBuffer.trim();
+            if (!trimmed)
+                return;
+            // Cancel pending periodic flush — we're delivering now.
+            stopFlushTimer();
+            // The actual speak message replaces any "thinking..." phrase cycling.
+            stopPhraseRotation();
+            // Bypass MIN_INITIAL_CHARS threshold — speak delivers immediately.
+            firstContentEmitted = true;
+            textBuffer = "";
+            // Try the stream first via the NON-ABORTING variant; on failure, fall back
+            // to sendMessage. Critical: do NOT call markStopped() / abort the controller
+            // when only the primary stream fails — the sendMessage fallback may still
+            // deliver the speak, and a successful fallback must not poison the rest of
+            // the turn. Only abort when ALL delivery paths fail (handled below).
+            // Contract: throws if the message could not be delivered through any available path.
+            let delivered = false;
+            let lastError = null;
+            if (!stopped) {
+                const ok = await tryEmitNoAbort(trimmed);
+                if (ok)
+                    delivered = true;
+                else
+                    lastError = new Error("stream emit failed");
+            }
+            if (!delivered && sendMessage) {
+                try {
+                    await sendMessage(trimmed);
+                    delivered = true;
+                    lastError = null;
+                }
+                catch (err) {
+                    lastError = err instanceof Error ? err : new Error(String(err));
+                }
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "teams.speak_flush",
+                message: "teams flushed mid-turn speak",
+                meta: { messageLength: trimmed.length, delivered },
+            });
+            if (!delivered) {
+                // All delivery paths exhausted — now it is correct to abort the turn.
+                // markStopped() halts further stream activity and aborts the controller
+                // so the engine catches up and ends the turn cleanly.
+                markStopped();
+                throw new Error(`teams speak delivery failed: ${lastError?.message ?? "no fallback available"}`);
+            }
+        },
         ...(() => {
             const toolCbs = (0, tool_activity_callbacks_1.createToolActivityCallbacks)({
                 onDescription: (text) => safeUpdate(text),
@@ -438,6 +508,13 @@ function createTeamsCallbacks(stream, controller, sendMessage, options) {
             });
             return {
                 onToolStart: (name, args) => {
+                    // speak is flow-control: its visible output is the message itself
+                    // (delivered via onTextChunk + flushNow). Do NOT stop phrase rotation
+                    // here, do NOT emit the \u23f3 placeholder, do NOT post a tool-activity
+                    // status update \u2014 all of those would create UI churn right before the
+                    // actual speak content arrives.
+                    if (name === "speak")
+                        return;
                     stopPhraseRotation();
                     // Force-flush any accumulated text, bypassing MIN_INITIAL_CHARS threshold
                     firstContentEmitted = true;
@@ -453,6 +530,12 @@ function createTeamsCallbacks(stream, controller, sendMessage, options) {
                     hadToolRun = true;
                 },
                 onToolEnd: (name, summary, success) => {
+                    // speak is flow-control: skip phrase-rotation stop and tool-activity end
+                    // callback (no safeUpdate for \u2713/\u2717). The flushNow call inside the engine
+                    // already emitted the actual message and stopped any rotation as part of
+                    // tryEmit's first-content-emitted flag.
+                    if (name === "speak")
+                        return;
                     stopPhraseRotation();
                     toolCbs.onToolEnd(name, summary, success);
                 },

package/package.json

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