@ouro.bot/cli 0.1.0-alpha.727 → 0.1.0-alpha.728

package/README.md

@@ -179,6 +179,9 @@ If you are changing runtime code, keep all three green.
 ```bash
 ouro                             # open the interactive home deck in a human TTY
 ouro up                          # start daemon from installed production version
+ouro up --latest                 # preflight latest, then replace any exact rollback pin
+ouro rollback <version>          # pin normal starts to an exact installed version
+ouro versions                    # show installed versions and current intent
 ouro dev                         # start daemon from local repo build (auto-detects CWD)
 ouro dev --repo-path /path       # start from a specific repo checkout
 ouro dev --clone                 # clone repo to ~/Projects/ouroboros, build, start
@@ -198,6 +201,7 @@ ouro connect perplexity --agent <name>
 ouro connect embeddings --agent <name>
 ouro connect teams --agent <name>
 ouro connect bluebubbles --agent <name>
+ouro bluebubbles host status --json
 ouro connect voice --agent <name>
 ouro auth --agent <name>
 ouro auth --agent <name> --provider <provider>
@@ -218,11 +222,18 @@ ouro attention --agent <agent>       # attention queue
 ouro link <agent> --friend <id> --provider <provider> --external-id <external-id>
 ouro setup --tool <tool> --agent <name>   # register MCP server + hooks with a dev tool
 ouro mcp-serve --agent <name>             # start MCP server on stdin/stdout (used by dev tools)
+ouro mcp doctor --agent <name> --json     # bounded direct bridge evidence
 ouro hook <event> --agent <name>          # fire a lifecycle hook (SessionStart, Stop, PostToolUse)
 ```
 
 The generic secret primitive is a vault item / credential in the owning agent vault: stable item name/path, hidden secret material, optional public fields, notes, timestamps/provenance, and no assumed use. `ouro connect` is for harness-managed workflows; workflow bindings reference ordinary vault items when they need secret material.
 
+### Standard BlueBubbles setup
+
+`ouro connect bluebubbles --agent <name>` is the standard local-Mac setup path. Besides saving the machine-scoped attachment, it installs or verifies the native-compatible BlueBubbles LaunchAgent for a same-user bridge and reconciles one Ouro-owned `[*]` webhook after the listener is bound. The daemon repairs that owned callback every 180 seconds, preserves unrelated callbacks, and creates the desired callback before removing a stale owned one. If the listener or BlueBubbles API is unavailable, connect says the attachment was saved but setup is incomplete; `ouro doctor` and `ouro bluebubbles host status --json` separate app, service, process, HTTP, and webhook failures.
+
+When BlueBubbles runs in another logged-in macOS account, standard setup installs a generic helper and returns one nonce-bound `human-required` Terminal command for that account plus `ouro bluebubbles host collect --request-id <id>`. Ouro never asks for or stores the other account's login password. The receipt proves that one handoff and reports launchd only as point-in-time evidence; current process and HTTP health are checked separately.
+
 ## Setting Up On Another Machine
 
 To clone an existing agent onto a new machine (macOS, Linux, or Windows via WSL2), see **[docs/cross-machine-setup.md](docs/cross-machine-setup.md)**. The short version is bundle plus vault: `npx ouro.bot@latest`, open the home deck, choose clone, enter the bundle's git remote URL, unlock the agent vault, refresh/verify credentials, and start with `ouro up`.
@@ -252,7 +263,9 @@ ouro setup --tool claude-code --agent <name>
 ouro setup --tool codex --agent <name>
 ```
 
-This registers the MCP server, installs lifecycle hooks (SessionStart, Stop, PostToolUse), and detects dev vs installed mode automatically.
+This registers the MCP server, installs lifecycle hooks (SessionStart, Stop, PostToolUse), detects dev vs installed mode automatically, and runs a bounded direct canary. Registration success and canary health are reported separately.
+
+If the dev-tool host appears frozen, run `ouro mcp doctor --agent <name> --json`. Its classification is deliberately narrow: `ouro-bridge-failed`, `ouro-bridge-healthy-at-capture`, or `host-stall-unexplained`. Add `--host-stall-observed` only when the host stall was independently observed. A healthy bridge canary does not prove that Codex or another host caused the stall; it only bounds what Ouro observed at capture time.
 
 **How it works:** When a developer starts a Claude Code session, the MCP server launches as a subprocess. The dev tool sees your MCP tools (`send_message`, `ask`, `check_response`, `status`, `search_facts`, `delegate`, etc.) and can invoke them mid-session. Conversation-shaped tools such as `send_message`, `ask`, `delegate`, `check_guidance`, and `report_progress` run full agent turns — you get your system prompt, your Desk record, your tools, everything. Read-only inspection tools such as `status` and `search_facts` do local lookup only. Missing `search_facts` hits are not evidence that the agent has no belief or preference.
 

package/assets/bluebubbles-host

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+"use strict"
+
+const fs = require("fs")
+const os = require("os")
+const path = require("path")
+const { execFileSync } = require("child_process")
+
+const SCHEMA_VERSION = 1
+const HELPER_VERSION = 1
+const FRESHNESS_MS = 300000
+const SHARED_ROOT = "/Users/Shared/Ouro"
+const REQUESTS_ROOT = path.join(SHARED_ROOT, "bluebubbles-host-requests")
+const RECEIPTS_ROOT = path.join(SHARED_ROOT, "bluebubbles-host-receipts")
+const APP_PATH = "/Applications/BlueBubbles.app"
+const EXECUTABLE_PATH = `${APP_PATH}/Contents/MacOS/BlueBubbles`
+const LABEL = "com.bluebubbles.server"
+
+function createRuntime(overrides = {}) {
+  return {
+    fs,
+    homedir: os.homedir,
+    now: Date.now,
+    getuid: () => process.getuid(),
+    execFileSync,
+    argv: process.argv,
+    writeStdout: (value) => process.stdout.write(value),
+    writeStderr: (value) => process.stderr.write(value),
+    setExitCode: (code) => { process.exitCode = code },
+    ...overrides,
+  }
+}
+
+function fail(message, runtime) {
+  runtime.writeStderr(`bluebubbles-host: ${message}\n`)
+  runtime.setExitCode(1)
+}
+
+function runLaunchctl(args, runtime) {
+  try {
+    const output = runtime.execFileSync("launchctl", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] })
+    return { ok: true, detail: output.trim() || "ok" }
+  } catch (error) {
+    return { ok: false, detail: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+function requireLaunchctl(args, operation, runtime) {
+  const result = runLaunchctl(args, runtime)
+  if (result.ok) {
+    return result.detail
+  } else {
+    throw new Error(`launchctl ${operation} failed: ${result.detail}`)
+  }
+}
+
+function nativePlist() {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+    <dict>
+        <key>AssociatedBundleIdentifiers</key>
+        <array>
+            <string>com.BlueBubbles.BlueBubbles-Server</string>
+        </array>
+        <key>Label</key>
+        <string>com.bluebubbles.server</string>
+        <key>Program</key>
+        <string>${EXECUTABLE_PATH}</string>
+        <key>RunAtLoad</key>
+        <true/>
+        <key>KeepAlive</key>
+        <dict>
+	        <key>SuccessfulExit</key>
+	        <false/>
+            <key>Crashed</key>
+            <true/>
+	    </dict>
+    </dict>
+</plist>`
+}
+
+function validateRequest(request, requestPath, runtime) {
+  if (path.dirname(path.resolve(requestPath)) !== REQUESTS_ROOT) throw new Error("request path is outside the shared request directory")
+  if (request.schemaVersion !== SCHEMA_VERSION) throw new Error("unsupported request schema")
+  if (request.helperVersion !== HELPER_VERSION) throw new Error("unsupported helper version")
+  if (!/^[A-Za-z_][A-Za-z0-9._-]*$/.test(request.username)) throw new Error("invalid target username")
+  if (!Number.isInteger(request.uid) || request.uid < 500) throw new Error("invalid target uid")
+  if (!/^[0-9a-f]{64}$/.test(request.nonce)) throw new Error("invalid request nonce")
+  if (request.requestId !== `${request.uid}-${request.nonce}`) throw new Error("request id mismatch")
+  if (!new Set(["install", "status", "repair", "remove"]).has(request.action)) throw new Error("unsupported host action")
+  const requestedAt = Date.parse(request.requestedAt)
+  const expiresAt = Date.parse(request.expiresAt)
+  const now = runtime.now()
+  if (!Number.isFinite(requestedAt) || !Number.isFinite(expiresAt)) throw new Error("invalid request time")
+  if (expiresAt - requestedAt > FRESHNESS_MS) throw new Error("request freshness window is too large")
+  if (requestedAt > now || now > expiresAt) throw new Error("request is not fresh")
+
+  const currentUid = runtime.getuid()
+  const currentUsername = runtime.execFileSync("id", ["-un"], { encoding: "utf8" }).trim()
+  if (currentUid !== request.uid || currentUsername !== request.username) throw new Error("run this request as its exact target user")
+  requireLaunchctl(["print", `gui/${currentUid}`], `print gui/${currentUid}`, runtime)
+  return request
+}
+
+function inspect(request, runtime) {
+  const plistPath = path.join(runtime.homedir(), "Library", "LaunchAgents", `${LABEL}.plist`)
+  const serviceTarget = `gui/${request.uid}/${LABEL}`
+  const service = runLaunchctl(["print", serviceTarget], runtime)
+  const plist = runtime.fs.existsSync(plistPath)
+    ? runtime.fs.readFileSync(plistPath, "utf8") === nativePlist() ? "current" : "drifted"
+    : "missing"
+  return { plistPath, serviceTarget, service, plist }
+}
+
+function receiptState(request, runtime) {
+  return {
+    plistPath: path.join(runtime.homedir(), "Library", "LaunchAgents", `${LABEL}.plist`),
+    serviceTarget: `gui/${request.uid}/${LABEL}`,
+  }
+}
+
+function requireApp(runtime) {
+  if (runtime.fs.existsSync(APP_PATH)) {
+    return APP_PATH
+  } else {
+    throw new Error(`BlueBubbles app is missing at ${APP_PATH}`)
+  }
+}
+
+function unloadService(state, disableFirst, runtime) {
+  if (!state.service.ok) {
+    return false
+  } else {
+    disableFirst && requireLaunchctl(["disable", state.serviceTarget], "disable", runtime)
+    requireLaunchctl(["bootout", state.serviceTarget], "bootout", runtime)
+    return true
+  }
+}
+
+function installPlistIfNeeded(state, runtime) {
+  if (state.plist === "current") {
+    return false
+  } else {
+    runtime.fs.mkdirSync(path.dirname(state.plistPath), { recursive: true })
+    runtime.fs.writeFileSync(state.plistPath, nativePlist(), { mode: 0o644 })
+    return true
+  }
+}
+
+function execute(request, runtime) {
+  const before = inspect(request, runtime)
+  if (request.action === "status") {
+    if (before.plist === "current" && before.service.ok) {
+      return before
+    } else {
+      throw new Error(`native service is not current and loaded (${before.plist}; ${before.service.detail})`)
+    }
+  }
+  if (request.action === "remove") {
+    unloadService(before, true, runtime)
+    before.plist !== "missing" && runtime.fs.unlinkSync(before.plistPath)
+    const after = inspect(request, runtime)
+    if (after.plist !== "missing" || after.service.ok) throw new Error("native service removal did not verify")
+    return after
+  } else {
+    requireApp(runtime)
+    if (before.plist === "current" && before.service.ok) {
+      return before
+    } else {
+      installPlistIfNeeded(before, runtime)
+      unloadService(before, false, runtime)
+      requireLaunchctl(["disable", before.serviceTarget], "disable", runtime)
+      requireLaunchctl(["enable", before.serviceTarget], "enable", runtime)
+      requireLaunchctl(["bootstrap", `gui/${request.uid}`, before.plistPath], "bootstrap", runtime)
+      const after = inspect(request, runtime)
+      if (after.plist === "current" && after.service.ok) {
+        return after
+      } else {
+        throw new Error("native service installation did not verify")
+      }
+    }
+  }
+}
+
+function publishReceipt(request, result, detail, state, runtime) {
+  const receipt = {
+    ...request,
+    appPath: APP_PATH,
+    plistPath: state.plistPath,
+    launchAgentLabel: LABEL,
+    launchdDomain: `gui/${request.uid}`,
+    result,
+    detail,
+    verifiedAt: new Date(runtime.now()).toISOString(),
+  }
+  const finalPath = path.join(RECEIPTS_ROOT, `${request.requestId}.json`)
+  const temporaryPath = `${finalPath}.${request.nonce}.tmp`
+  runtime.fs.writeFileSync(temporaryPath, `${JSON.stringify(receipt, null, 2)}\n`, { encoding: "utf8", mode: 0o444, flag: "wx" })
+  try {
+    runtime.fs.chmodSync(temporaryPath, 0o444)
+    runtime.fs.linkSync(temporaryPath, finalPath)
+    runtime.fs.chmodSync(finalPath, 0o444)
+  } finally {
+    if (runtime.fs.existsSync(temporaryPath)) runtime.fs.unlinkSync(temporaryPath)
+  }
+  runtime.writeStdout(`${JSON.stringify({ ok: result === "verified", requestId: request.requestId, receiptPath: finalPath })}\n`)
+}
+
+function main(runtime) {
+  const requestFlag = runtime.argv.indexOf("--request")
+  if (requestFlag >= 0 && runtime.argv[requestFlag + 1]) {
+    const requestPath = path.resolve(runtime.argv[requestFlag + 1])
+    const request = validateRequest(JSON.parse(runtime.fs.readFileSync(requestPath, "utf8")), requestPath, runtime)
+    let state = receiptState(request, runtime)
+    try {
+      state = execute(request, runtime)
+      publishReceipt(request, "verified", `native ${request.action} verified`, state, runtime)
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error)
+      publishReceipt(request, "failed", detail, state, runtime)
+      throw error
+    }
+  } else {
+    throw new Error("usage: bluebubbles-host --request <request.json>")
+  }
+}
+
+function runCli(runtime = createRuntime()) {
+  try {
+    main(runtime)
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error), runtime)
+  }
+}
+
+function runCliIfMain(isMain, runtime) {
+  if (isMain) {
+    runCli(runtime)
+  } else {
+    return false
+  }
+  return true
+}
+
+runCliIfMain(require.main === module)
+
+module.exports = {
+  constants: {
+    schemaVersion: SCHEMA_VERSION,
+    helperVersion: HELPER_VERSION,
+    freshnessMs: FRESHNESS_MS,
+    sharedRoot: SHARED_ROOT,
+  },
+  createRuntime,
+  nativePlist,
+  validateRequest,
+  inspect,
+  execute,
+  publishReceipt,
+  main,
+  runCli,
+  runCliIfMain,
+}

package/changelog.json

@@ -1,6 +1,15 @@
 {
   "_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.728",
+      "changes": [
+        "Make exact rollback intent durable, bound status and MCP diagnostics, and make BlueBubbles host continuity plus owner-safe webhook reconciliation part of standard setup.",
+        "Verify the packed BlueBubbles host helper and exact wrapper intent across fresh, older, equal, and newer installations, and replace the vulnerable mail parsing dependency chain.",
+        "Enforce status as an absolute wall-clock deadline even under trickled socket data, and keep sanitized MCP failure evidence compliant with the runtime logging schema.",
+        "Stage published latest targets in either direction, verify the recovery launcher before version-intent commits, and require BlueBubbles host repair to finish with a current loaded LaunchAgent."
+      ]
+    },
     {
       "version": "0.1.0-alpha.727",
       "changes": [

package/dist/heart/config.js

@@ -315,8 +315,7 @@ function getBlueBubblesConfig() {
 }
 function getBlueBubblesChannelConfig() {
     const config = loadConfig();
-    const { port, webhookPath, requestTimeoutMs } = config.bluebubblesChannel;
-    return { port, webhookPath, requestTimeoutMs };
+    return { ...config.bluebubblesChannel };
 }
 function getIntegrationsConfig() {
     const config = loadConfig();

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

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blueBubblesListenerReadyAfterApply = blueBubblesListenerReadyAfterApply;
+exports.formatBlueBubblesWebhookConnectLine = formatBlueBubblesWebhookConnectLine;
+exports.formatBlueBubblesHostActionText = formatBlueBubblesHostActionText;
+exports.reconcileBlueBubblesWebhookAfterConnect = reconcileBlueBubblesWebhookAfterConnect;
+const runtime_1 = require("../../nerves/runtime");
+const webhook_registration_1 = require("../../senses/bluebubbles/webhook-registration");
+function blueBubblesListenerReadyAfterApply(daemonApply) {
+    return daemonApply.startsWith("restarted Ouro;");
+}
+function formatBlueBubblesWebhookConnectLine(result) {
+    return result.ok
+        ? `webhook: ${result.detail}`
+        : `webhook saved-but-incomplete: ${result.detail}`;
+}
+function formatBlueBubblesHostActionText(outcome) {
+    const httpStatus = outcome.state.http.ok === true
+        ? "healthy"
+        : outcome.state.http.ok === false
+            ? "unhealthy"
+            : "not checked";
+    return [
+        `BlueBubbles host ${outcome.action}`,
+        "actor: agent-runnable",
+        `app: ${outcome.state.app}`,
+        `plist: ${outcome.state.plist} (${outcome.state.plistPath})`,
+        `service: ${outcome.state.service}${outcome.state.serviceDetail ? ` (${outcome.state.serviceDetail})` : ""}`,
+        `process: ${outcome.state.process}`,
+        `HTTP: ${httpStatus} (${outcome.state.http.detail})`,
+        "repair: ouro bluebubbles host repair",
+    ].join("\n");
+}
+async function reconcileBlueBubblesWebhookAfterConnect(input, deps = {}) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.bluebubbles_connect_webhook_start",
+        message: "verifying BlueBubbles webhook after connect",
+        meta: { agent: input.agentName, listenerReady: input.listenerReady },
+    });
+    try {
+        const result = deps.reconcile
+            ? await deps.reconcile(input)
+            : await (0, webhook_registration_1.reconcileBlueBubblesWebhookRegistration)(input, { fetchImpl: deps.fetchImpl ?? fetch });
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.bluebubbles_connect_webhook_end",
+            level: result.ok ? "info" : "warn",
+            message: "verified BlueBubbles webhook after connect",
+            meta: { agent: input.agentName, state: result.state, ok: result.ok },
+        });
+        return result;
+    }
+    catch {
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.bluebubbles_connect_webhook_error",
+            level: "error",
+            message: "BlueBubbles webhook verification failed before returning diagnostics",
+            meta: { agent: input.agentName, listenerReady: input.listenerReady },
+        });
+        return {
+            ok: false,
+            state: "api-unreachable",
+            changed: false,
+            ownedCount: 0,
+            exactCount: 0,
+            detail: "webhook verification failed before BlueBubbles returned a diagnostic result",
+        };
+    }
+}