@ouro.bot/cli 0.1.0-alpha.43 → 0.1.0-alpha.45

package/changelog.json

@@ -1,6 +1,20 @@
 {
   "_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.45",
+      "changes": [
+        "`ouro up` now persists a boot-time launch agent with `RunAtLoad`, so the daemon comes back reliably after reboot instead of only starting for the current session.",
+        "BlueBubbles sense status is now truthful about upstream health: it probes the real BlueBubbles API, records runtime state, and surfaces `error` when the webhook listener is alive but the upstream server is unreachable.",
+        "BlueBubbles intake now replays recoverable read/delivery mutation backlogs through the normal inbound agent path, with a small dedupe ledger so missed messages can be recovered without silent drops or duplicate delivery."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.44",
+      "changes": [
+        "Workflow skills now install into `~/.agents/skills` for Codex/OpenAI instead of duplicating installs under both `.agents` and `.codex`, which prevents duplicate advertised skills while keeping re-installs safe."
+      ]
+    },
     {
       "version": "0.1.0-alpha.43",
       "changes": [

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

@@ -63,6 +63,7 @@ const bundle_meta_1 = require("./hooks/bundle-meta");
 const bundle_manifest_1 = require("../../mind/bundle-manifest");
 const tasks_1 = require("../../repertoire/tasks");
 const ouro_bot_global_installer_1 = require("./ouro-bot-global-installer");
+const launchd_1 = require("./launchd");
 function stringField(value) {
     return typeof value === "string" ? value : null;
 }
@@ -761,6 +762,25 @@ function defaultFallbackPendingMessage(command) {
     });
     return pendingPath;
 }
+function defaultEnsureDaemonBootPersistence(socketPath) {
+    if (process.platform !== "darwin") {
+        return;
+    }
+    const homeDir = os.homedir();
+    const launchdDeps = {
+        writeFile: (filePath, content) => fs.writeFileSync(filePath, content, "utf-8"),
+        mkdirp: (dir) => fs.mkdirSync(dir, { recursive: true }),
+        homeDir,
+    };
+    const entryPath = path.join((0, identity_1.getRepoRoot)(), "dist", "heart", "daemon", "daemon-entry.js");
+    const logDir = path.join(homeDir, ".agentstate", "daemon", "logs");
+    (0, launchd_1.writeLaunchAgentPlist)(launchdDeps, {
+        nodePath: process.execPath,
+        entryPath,
+        socketPath,
+        logDir,
+    });
+}
 async function defaultInstallSubagents() {
     return (0, subagent_installer_1.installSubagentsForAvailableCli)({
         repoRoot: (0, identity_1.getRepoRoot)(),
@@ -1045,6 +1065,7 @@ function createDefaultOuroCliDeps(socketPath = "/tmp/ouroboros-daemon.sock") {
         registerOuroBundleType: ouro_uti_1.registerOuroBundleUti,
         installOuroCommand: ouro_path_installer_1.installOuroCommand,
         syncGlobalOuroBotWrapper: ouro_bot_global_installer_1.syncGlobalOuroBotWrapper,
+        ensureDaemonBootPersistence: defaultEnsureDaemonBootPersistence,
         /* v8 ignore next 3 -- integration: launches interactive CLI session @preserve */
         startChat: async (agentName) => {
             const { main } = await Promise.resolve().then(() => __importStar(require("../../senses/cli")));
@@ -1406,6 +1427,20 @@ async function runOuroCli(args, deps = createDefaultOuroCliDeps()) {
     });
     if (command.kind === "daemon.up") {
         await performSystemSetup(deps);
+        if (deps.ensureDaemonBootPersistence) {
+            try {
+                await Promise.resolve(deps.ensureDaemonBootPersistence(deps.socketPath));
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "daemon",
+                    event: "daemon.system_setup_launchd_error",
+                    message: "failed to persist daemon boot startup",
+                    meta: { error: error instanceof Error ? error.message : String(error), socketPath: deps.socketPath },
+                });
+            }
+        }
         // Run update hooks before starting daemon so user sees the output
         (0, update_hooks_1.registerUpdateHook)(bundle_meta_1.bundleMetaHook);
         const bundlesRoot = (0, identity_1.getAgentBundlesRoot)();

package/dist/heart/daemon/launchd.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DAEMON_PLIST_LABEL = void 0;
 exports.generateDaemonPlist = generateDaemonPlist;
+exports.writeLaunchAgentPlist = writeLaunchAgentPlist;
 exports.installLaunchAgent = installLaunchAgent;
 exports.uninstallLaunchAgent = uninstallLaunchAgent;
 exports.isDaemonInstalled = isDaemonInstalled;
@@ -65,6 +66,8 @@ function generateDaemonPlist(options) {
         `    <string>--socket</string>`,
         `    <string>${options.socketPath}</string>`,
         `  </array>`,
+        `  <key>RunAtLoad</key>`,
+        `  <true/>`,
         `  <key>KeepAlive</key>`,
         `  <true/>`,
     ];
@@ -74,6 +77,23 @@ function generateDaemonPlist(options) {
     lines.push(`</dict>`, `</plist>`, ``);
     return lines.join("\n");
 }
+function writeLaunchAgentPlist(deps, options) {
+    const launchAgentsDir = path.join(deps.homeDir, "Library", "LaunchAgents");
+    deps.mkdirp(launchAgentsDir);
+    if (options.logDir) {
+        deps.mkdirp(options.logDir);
+    }
+    const fullPath = plistFilePath(deps.homeDir);
+    const xml = generateDaemonPlist(options);
+    deps.writeFile(fullPath, xml);
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.launchd_plist_written",
+        message: "daemon launch agent plist written",
+        meta: { plistPath: fullPath, entryPath: options.entryPath, socketPath: options.socketPath },
+    });
+    return fullPath;
+}
 function installLaunchAgent(deps, options) {
     (0, runtime_1.emitNervesEvent)({
         component: "daemon",
@@ -81,8 +101,6 @@ function installLaunchAgent(deps, options) {
         message: "installing launch agent",
         meta: { entryPath: options.entryPath, socketPath: options.socketPath },
     });
-    const launchAgentsDir = path.join(deps.homeDir, "Library", "LaunchAgents");
-    deps.mkdirp(launchAgentsDir);
     const fullPath = plistFilePath(deps.homeDir);
     // Unload existing (best effort) for idempotent re-install
     if (deps.existsFile(fullPath)) {
@@ -91,8 +109,7 @@ function installLaunchAgent(deps, options) {
         }
         catch { /* best effort */ }
     }
-    const xml = generateDaemonPlist(options);
-    deps.writeFile(fullPath, xml);
+    writeLaunchAgentPlist(deps, options);
     deps.exec(`launchctl load "${fullPath}"`);
     (0, runtime_1.emitNervesEvent)({
         component: "daemon",

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

@@ -38,6 +38,7 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const runtime_1 = require("../../nerves/runtime");
+const bluebubbles_runtime_state_1 = require("../../senses/bluebubbles-runtime-state");
 const identity_1 = require("../identity");
 const sense_truth_1 = require("../sense-truth");
 const process_manager_1 = require("./process-manager");
@@ -175,12 +176,29 @@ function runtimeInfoFor(status) {
         return { runtime: "running" };
     return { runtime: "error" };
 }
+function readBlueBubblesRuntimeFacts(agent, bundlesRoot, snapshot) {
+    const agentRoot = path.join(bundlesRoot, `${agent}.ouro`);
+    const runtimePath = path.join(agentRoot, "state", "senses", "bluebubbles", "runtime.json");
+    if (snapshot?.runtime !== "running" || !fs.existsSync(runtimePath)) {
+        return { runtime: snapshot?.runtime };
+    }
+    const state = (0, bluebubbles_runtime_state_1.readBlueBubblesRuntimeState)(agent, agentRoot);
+    if (state.upstreamStatus === "error") {
+        return {
+            runtime: "error",
+            detail: state.detail,
+        };
+    }
+    return { runtime: snapshot.runtime };
+}
 class DaemonSenseManager {
     processManager;
     contexts;
+    bundlesRoot;
     constructor(options) {
         const bundlesRoot = options.bundlesRoot ?? path.join(os.homedir(), "AgentBundles");
         const secretsRoot = options.secretsRoot ?? path.join(os.homedir(), ".agentsecrets");
+        this.bundlesRoot = bundlesRoot;
         this.contexts = new Map(options.agents.map((agent) => {
             const senses = readAgentSenses(path.join(bundlesRoot, `${agent}.ouro`, "agent.json"));
             const facts = senseFactsFromSecrets(agent, senses, path.join(secretsRoot, agent, "secrets.json"));
@@ -227,6 +245,7 @@ class DaemonSenseManager {
             runtime.set(parsed.agent, current);
         }
         const rows = [...this.contexts.entries()].flatMap(([agent, context]) => {
+            const blueBubblesRuntimeFacts = readBlueBubblesRuntimeFacts(agent, this.bundlesRoot, runtime.get(agent)?.bluebubbles);
             const runtimeInfo = {
                 cli: { configured: true },
                 teams: {
@@ -235,7 +254,7 @@ class DaemonSenseManager {
                 },
                 bluebubbles: {
                     configured: context.facts.bluebubbles.configured,
-                    ...(runtime.get(agent)?.bluebubbles ?? {}),
+                    ...blueBubblesRuntimeFacts,
                 },
             };
             const inventory = (0, sense_truth_1.getSenseInventory)({ senses: context.senses }, runtimeInfo);
@@ -245,7 +264,12 @@ class DaemonSenseManager {
                 label: entry.label,
                 enabled: entry.enabled,
                 status: entry.status,
-                detail: entry.enabled ? context.facts[entry.sense].detail : "not enabled in agent.json",
+                detail: entry.enabled
+                    ? entry.sense === "bluebubbles"
+                        ? blueBubblesRuntimeFacts.detail
+                            ?? context.facts[entry.sense].detail
+                        : context.facts[entry.sense].detail
+                    : "not enabled in agent.json",
             }));
         });
         (0, runtime_1.emitNervesEvent)({

package/dist/heart/daemon/subagent-installer.js

@@ -64,6 +64,16 @@ function pathExists(target) {
         return false;
     }
 }
+function isSameFile(source, target) {
+    try {
+        const sourceStats = fs.statSync(source);
+        const targetStats = fs.statSync(target);
+        return sourceStats.dev === targetStats.dev && sourceStats.ino === targetStats.ino;
+    }
+    catch {
+        return false;
+    }
+}
 function ensureSymlink(source, target) {
     fs.mkdirSync(path.dirname(target), { recursive: true });
     if (pathExists(target)) {
@@ -78,6 +88,25 @@ function ensureSymlink(source, target) {
     fs.symlinkSync(source, target);
     return true;
 }
+function ensureHardLink(source, target) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (pathExists(target)) {
+        const stats = fs.lstatSync(target);
+        if (!stats.isSymbolicLink() && isSameFile(source, target)) {
+            return false;
+        }
+        fs.unlinkSync(target);
+    }
+    fs.linkSync(source, target);
+    return true;
+}
+function hasOpenAiSkillHome(homeDir) {
+    return pathExists(path.join(homeDir, ".codex")) || pathExists(path.join(homeDir, ".agents"));
+}
+function openAiSkillTargets(homeDir, source) {
+    const skillName = path.basename(source, ".md");
+    return [path.join(homeDir, ".agents", "skills", skillName, "SKILL.md")];
+}
 async function installSubagentsForAvailableCli(options = {}) {
     const repoRoot = options.repoRoot ?? path.resolve(__dirname, "..", "..", "..");
     const homeDir = options.homeDir ?? os.homedir();
@@ -111,15 +140,18 @@ async function installSubagentsForAvailableCli(options = {}) {
         }
     }
     const codexPath = which("codex");
-    if (!codexPath) {
-        notes.push("codex CLI not found; skipping subagent install");
+    if (!codexPath && !hasOpenAiSkillHome(homeDir)) {
+        notes.push("codex CLI/config not found; skipping subagent install");
     }
     else {
-        const codexSkillsDir = path.join(homeDir, ".codex", "skills");
         for (const source of sources) {
-            const skillName = path.basename(source, ".md");
-            const target = path.join(codexSkillsDir, skillName, "SKILL.md");
-            if (ensureSymlink(source, target)) {
+            let installedForSkill = false;
+            for (const target of openAiSkillTargets(homeDir, source)) {
+                if (ensureHardLink(source, target)) {
+                    installedForSkill = true;
+                }
+            }
+            if (installedForSkill) {
                 codexInstalled += 1;
             }
         }

package/dist/senses/bluebubbles-client.js

@@ -170,6 +170,12 @@ function applyRepairNotice(event, notice) {
         repairNotice: notice,
     };
 }
+function hasRecoverableMessageContent(event) {
+    return event.kind === "message"
+        && (event.textForAgent.trim().length > 0
+            || event.attachments.length > 0
+            || event.hasPayloadData);
+}
 function hydrateTextForAgent(event, rawData) {
     if (event.kind !== "message") {
         return { ...event, requiresRepair: false };
@@ -323,6 +329,40 @@ function createBlueBubblesClient(config = (0, config_1.getBlueBubblesConfig)(),
                 throw new Error(`BlueBubbles read failed (${response.status}): ${errorText || "unknown"}`);
             }
         },
+        async checkHealth() {
+            const url = buildBlueBubblesApiUrl(config.serverUrl, "/api/v1/message/count", config.password);
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.bluebubbles_healthcheck_start",
+                message: "probing bluebubbles upstream health",
+                meta: { serverUrl: config.serverUrl },
+            });
+            const response = await fetch(url, {
+                method: "GET",
+                signal: AbortSignal.timeout(channelConfig.requestTimeoutMs),
+            });
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => "");
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "senses",
+                    event: "senses.bluebubbles_healthcheck_error",
+                    message: "bluebubbles upstream health probe failed",
+                    meta: {
+                        serverUrl: config.serverUrl,
+                        status: response.status,
+                        reason: errorText || "unknown",
+                    },
+                });
+                throw new Error(`BlueBubbles upstream health check failed (${response.status}): ${errorText || "unknown"}`);
+            }
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.bluebubbles_healthcheck_end",
+                message: "bluebubbles upstream health probe succeeded",
+                meta: { serverUrl: config.serverUrl },
+            });
+        },
         async repairEvent(event) {
             if (!event.requiresRepair) {
                 (0, runtime_1.emitNervesEvent)({
@@ -387,7 +427,16 @@ function createBlueBubblesClient(config = (0, config_1.getBlueBubblesConfig)(),
                     type: event.eventType,
                     data,
                 });
-                let hydrated = hydrateTextForAgent(normalized, data);
+                const recoveredMessage = event.kind === "mutation"
+                    && !event.shouldNotifyAgent
+                    ? (0, bluebubbles_model_1.normalizeBlueBubblesEvent)({
+                        type: "new-message",
+                        data,
+                    })
+                    : null;
+                let hydrated = recoveredMessage && hasRecoverableMessageContent(recoveredMessage)
+                    ? hydrateTextForAgent(recoveredMessage, data)
+                    : hydrateTextForAgent(normalized, data);
                 if (hydrated.kind === "message" &&
                     hydrated.balloonBundleId !== "com.apple.messages.URLBalloonProvider" &&
                     hydrated.attachments.length > 0) {
@@ -411,6 +460,7 @@ function createBlueBubblesClient(config = (0, config_1.getBlueBubblesConfig)(),
                         kind: hydrated.kind,
                         messageGuid: hydrated.messageGuid,
                         repairedFrom: event.kind,
+                        promotedFromMutation: event.kind === "mutation" && hydrated.kind === "message",
                     },
                 });
                 return hydrated;

package/dist/senses/bluebubbles-entry.js

@@ -8,4 +8,6 @@ if (!process.argv.includes("--agent")) {
     process.exit(1);
 }
 const bluebubbles_1 = require("./bluebubbles");
+const runtime_logging_1 = require("../heart/daemon/runtime-logging");
+(0, runtime_logging_1.configureDaemonRuntimeLogger)("bluebubbles");
 (0, bluebubbles_1.startBlueBubblesApp)();

package/dist/senses/bluebubbles-inbound-log.js

@@ -0,0 +1,109 @@
+"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.getBlueBubblesInboundLogPath = getBlueBubblesInboundLogPath;
+exports.hasRecordedBlueBubblesInbound = hasRecordedBlueBubblesInbound;
+exports.recordBlueBubblesInbound = recordBlueBubblesInbound;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const config_1 = require("../heart/config");
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+function getBlueBubblesInboundLogPath(agentName, sessionKey) {
+    return path.join((0, identity_1.getAgentRoot)(agentName), "state", "senses", "bluebubbles", "inbound", `${(0, config_1.sanitizeKey)(sessionKey)}.ndjson`);
+}
+function readEntries(filePath) {
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        return raw
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => JSON.parse(line))
+            .filter((entry) => typeof entry.messageGuid === "string" && typeof entry.sessionKey === "string");
+    }
+    catch {
+        return [];
+    }
+}
+function hasRecordedBlueBubblesInbound(agentName, sessionKey, messageGuid) {
+    if (!messageGuid.trim())
+        return false;
+    const filePath = getBlueBubblesInboundLogPath(agentName, sessionKey);
+    return readEntries(filePath).some((entry) => entry.messageGuid === messageGuid);
+}
+function recordBlueBubblesInbound(agentName, event, source) {
+    const filePath = getBlueBubblesInboundLogPath(agentName, event.chat.sessionKey);
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.appendFileSync(filePath, JSON.stringify({
+            recordedAt: new Date(event.timestamp).toISOString(),
+            messageGuid: event.messageGuid,
+            chatGuid: event.chat.chatGuid ?? null,
+            chatIdentifier: event.chat.chatIdentifier ?? null,
+            sessionKey: event.chat.sessionKey,
+            textForAgent: event.textForAgent,
+            source,
+        }) + "\n", "utf-8");
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_inbound_log_error",
+            message: "failed to record bluebubbles inbound sidecar log",
+            meta: {
+                agentName,
+                messageGuid: event.messageGuid,
+                sessionKey: event.chat.sessionKey,
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+        return filePath;
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.bluebubbles_inbound_logged",
+        message: "recorded bluebubbles inbound message to sidecar log",
+        meta: {
+            agentName,
+            messageGuid: event.messageGuid,
+            sessionKey: event.chat.sessionKey,
+            source,
+            path: filePath,
+        },
+    });
+    return filePath;
+}

package/dist/senses/bluebubbles-mutation-log.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getBlueBubblesMutationLogPath = getBlueBubblesMutationLogPath;
 exports.recordBlueBubblesMutation = recordBlueBubblesMutation;
+exports.listBlueBubblesRecoveryCandidates = listBlueBubblesRecoveryCandidates;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const runtime_1 = require("../nerves/runtime");
@@ -72,3 +73,44 @@ function recordBlueBubblesMutation(agentName, event) {
     });
     return filePath;
 }
+function listBlueBubblesRecoveryCandidates(agentName) {
+    const rootDir = path.join((0, identity_1.getAgentRoot)(agentName), "state", "senses", "bluebubbles", "mutations");
+    let files;
+    try {
+        files = fs.readdirSync(rootDir);
+    }
+    catch {
+        return [];
+    }
+    const deduped = new Map();
+    for (const file of files.filter((entry) => entry.endsWith(".ndjson")).sort()) {
+        const filePath = path.join(rootDir, file);
+        let raw = "";
+        try {
+            raw = fs.readFileSync(filePath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of raw.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const entry = JSON.parse(trimmed);
+                if (typeof entry.messageGuid !== "string"
+                    || !entry.messageGuid.trim()
+                    || entry.fromMe
+                    || entry.shouldNotifyAgent
+                    || (entry.mutationType !== "read" && entry.mutationType !== "delivery")) {
+                    continue;
+                }
+                deduped.set(entry.messageGuid, entry);
+            }
+            catch {
+                // ignore malformed recovery candidates
+            }
+        }
+    }
+    return [...deduped.values()].sort((left, right) => left.recordedAt.localeCompare(right.recordedAt));
+}

package/dist/senses/bluebubbles-runtime-state.js

@@ -0,0 +1,109 @@
+"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.getBlueBubblesRuntimeStatePath = getBlueBubblesRuntimeStatePath;
+exports.readBlueBubblesRuntimeState = readBlueBubblesRuntimeState;
+exports.writeBlueBubblesRuntimeState = writeBlueBubblesRuntimeState;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const DEFAULT_RUNTIME_STATE = {
+    upstreamStatus: "unknown",
+    detail: "startup health probe pending",
+    pendingRecoveryCount: 0,
+};
+function getBlueBubblesRuntimeStatePath(agentName, agentRoot = (0, identity_1.getAgentRoot)(agentName)) {
+    return path.join(agentRoot, "state", "senses", "bluebubbles", "runtime.json");
+}
+function readBlueBubblesRuntimeState(agentName, agentRoot) {
+    const filePath = getBlueBubblesRuntimeStatePath(agentName, agentRoot);
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return {
+            upstreamStatus: parsed.upstreamStatus === "ok" || parsed.upstreamStatus === "error"
+                ? parsed.upstreamStatus
+                : "unknown",
+            detail: typeof parsed.detail === "string" && parsed.detail.trim()
+                ? parsed.detail
+                : DEFAULT_RUNTIME_STATE.detail,
+            lastCheckedAt: typeof parsed.lastCheckedAt === "string" ? parsed.lastCheckedAt : undefined,
+            pendingRecoveryCount: typeof parsed.pendingRecoveryCount === "number" && Number.isFinite(parsed.pendingRecoveryCount)
+                ? parsed.pendingRecoveryCount
+                : 0,
+            lastRecoveredAt: typeof parsed.lastRecoveredAt === "string" ? parsed.lastRecoveredAt : undefined,
+            lastRecoveredMessageGuid: typeof parsed.lastRecoveredMessageGuid === "string"
+                ? parsed.lastRecoveredMessageGuid
+                : undefined,
+        };
+    }
+    catch {
+        return { ...DEFAULT_RUNTIME_STATE };
+    }
+}
+function writeBlueBubblesRuntimeState(agentName, state, agentRoot) {
+    const filePath = getBlueBubblesRuntimeStatePath(agentName, agentRoot);
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(state, null, 2) + "\n", "utf-8");
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.bluebubbles_runtime_state_error",
+            message: "failed to write bluebubbles runtime state",
+            meta: {
+                agentName,
+                upstreamStatus: state.upstreamStatus,
+                reason: error instanceof Error ? error.message : String(error),
+            },
+        });
+        return filePath;
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.bluebubbles_runtime_state_written",
+        message: "wrote bluebubbles runtime state",
+        meta: {
+            agentName,
+            upstreamStatus: state.upstreamStatus,
+            pendingRecoveryCount: state.pendingRecoveryCount,
+            path: filePath,
+        },
+    });
+    return filePath;
+}

package/dist/senses/bluebubbles.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleBlueBubblesEvent = handleBlueBubblesEvent;
+exports.recoverMissedBlueBubblesMessages = recoverMissedBlueBubblesMessages;
 exports.createBlueBubblesWebhookHandler = createBlueBubblesWebhookHandler;
 exports.drainAndSendPendingBlueBubbles = drainAndSendPendingBlueBubbles;
 exports.startBlueBubblesApp = startBlueBubblesApp;
@@ -55,7 +56,9 @@ const phrases_1 = require("../mind/phrases");
 const runtime_1 = require("../nerves/runtime");
 const bluebubbles_model_1 = require("./bluebubbles-model");
 const bluebubbles_client_1 = require("./bluebubbles-client");
+const bluebubbles_inbound_log_1 = require("./bluebubbles-inbound-log");
 const bluebubbles_mutation_log_1 = require("./bluebubbles-mutation-log");
+const bluebubbles_runtime_state_1 = require("./bluebubbles-runtime-state");
 const bluebubbles_session_cleanup_1 = require("./bluebubbles-session-cleanup");
 const debug_activity_1 = require("./debug-activity");
 const trust_gate_1 = require("./trust-gate");
@@ -74,6 +77,7 @@ const defaultDeps = {
     createFriendResolver: (store, params) => new resolver_1.FriendResolver(store, params),
     createServer: http.createServer,
 };
+const BLUEBUBBLES_RUNTIME_SYNC_INTERVAL_MS = 30_000;
 function resolveFriendParams(event) {
     if (event.chat.isGroup) {
         const groupKey = event.chat.chatGuid ?? event.chat.chatIdentifier ?? event.sender.externalId;
@@ -234,6 +238,47 @@ function buildInboundContent(event, existingMessages) {
         ...event.inputPartsForAgent,
     ];
 }
+function sessionLikelyContainsMessage(event, existingMessages) {
+    const fragment = event.textForAgent.trim();
+    if (!fragment)
+        return false;
+    return existingMessages.some((message) => {
+        if (message.role !== "user")
+            return false;
+        return extractMessageText(message.content).includes(fragment);
+    });
+}
+function mutationEntryToEvent(entry) {
+    return {
+        kind: "mutation",
+        eventType: entry.eventType,
+        mutationType: entry.mutationType,
+        messageGuid: entry.messageGuid,
+        targetMessageGuid: entry.targetMessageGuid ?? undefined,
+        timestamp: Date.parse(entry.recordedAt) || Date.now(),
+        fromMe: entry.fromMe,
+        sender: {
+            provider: "imessage-handle",
+            externalId: entry.chatIdentifier ?? entry.chatGuid ?? "unknown",
+            rawId: entry.chatIdentifier ?? entry.chatGuid ?? "unknown",
+            displayName: entry.chatIdentifier ?? entry.chatGuid ?? "Unknown",
+        },
+        chat: {
+            chatGuid: entry.chatGuid ?? undefined,
+            chatIdentifier: entry.chatIdentifier ?? undefined,
+            displayName: undefined,
+            isGroup: Boolean(entry.chatGuid?.includes(";+;")),
+            sessionKey: entry.sessionKey,
+            sendTarget: entry.chatGuid
+                ? { kind: "chat_guid", value: entry.chatGuid }
+                : { kind: "chat_identifier", value: entry.chatIdentifier ?? "unknown" },
+            participantHandles: [],
+        },
+        shouldNotifyAgent: entry.shouldNotifyAgent,
+        textForAgent: entry.textForAgent,
+        requiresRepair: true,
+    };
+}
 function getBlueBubblesContinuityIngressTexts(event) {
     if (event.kind !== "message")
         return [];
@@ -435,10 +480,8 @@ function isWebhookPasswordValid(url, expectedPassword) {
     const provided = url.searchParams.get("password");
     return !provided || provided === expectedPassword;
 }
-async function handleBlueBubblesEvent(payload, deps = {}) {
-    const resolvedDeps = { ...defaultDeps, ...deps };
+async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source) {
     const client = resolvedDeps.createClient();
-    const event = await client.repairEvent((0, bluebubbles_model_1.normalizeBlueBubblesEvent)(payload));
     if (event.fromMe) {
         (0, runtime_1.emitNervesEvent)({
             component: "senses",
@@ -509,6 +552,36 @@ async function handleBlueBubblesEvent(payload, deps = {}) {
     const sessionMessages = existing?.messages && existing.messages.length > 0
         ? existing.messages
         : [{ role: "system", content: await resolvedDeps.buildSystem("bluebubbles", undefined, context) }];
+    if (event.kind === "message") {
+        const agentName = resolvedDeps.getAgentName();
+        if ((0, bluebubbles_inbound_log_1.hasRecordedBlueBubblesInbound)(agentName, event.chat.sessionKey, event.messageGuid)) {
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.bluebubbles_recovery_skip",
+                message: "skipped bluebubbles message already recorded as handled",
+                meta: {
+                    messageGuid: event.messageGuid,
+                    sessionKey: event.chat.sessionKey,
+                    source,
+                },
+            });
+            return { handled: true, notifiedAgent: false, kind: event.kind, reason: "already_processed" };
+        }
+        if (source !== "webhook" && sessionLikelyContainsMessage(event, existing?.messages ?? sessionMessages)) {
+            (0, bluebubbles_inbound_log_1.recordBlueBubblesInbound)(agentName, event, "recovery-bootstrap");
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.bluebubbles_recovery_skip",
+                message: "skipped bluebubbles recovery because the session already contains the message text",
+                meta: {
+                    messageGuid: event.messageGuid,
+                    sessionKey: event.chat.sessionKey,
+                    source,
+                },
+            });
+            return { handled: true, notifiedAgent: false, kind: event.kind, reason: "already_processed" };
+        }
+    }
     // Build inbound user message (adapter concern: BB-specific content formatting)
     const userMessage = {
         role: "user",
@@ -578,6 +651,9 @@ async function handleBlueBubblesEvent(payload, deps = {}) {
                     text: result.gateResult.autoReply,
                 });
             }
+            if (event.kind === "message") {
+                (0, bluebubbles_inbound_log_1.recordBlueBubblesInbound)(resolvedDeps.getAgentName(), event, source);
+            }
             return {
                 handled: true,
                 notifiedAgent: false,
@@ -586,6 +662,9 @@ async function handleBlueBubblesEvent(payload, deps = {}) {
         }
         // Gate allowed — flush the agent's reply
         await callbacks.flush();
+        if (event.kind === "message") {
+            (0, bluebubbles_inbound_log_1.recordBlueBubblesInbound)(resolvedDeps.getAgentName(), event, source);
+        }
         (0, runtime_1.emitNervesEvent)({
             component: "senses",
             event: "senses.bluebubbles_turn_end",
@@ -606,6 +685,94 @@ async function handleBlueBubblesEvent(payload, deps = {}) {
         await callbacks.finish();
     }
 }
+async function handleBlueBubblesEvent(payload, deps = {}) {
+    const resolvedDeps = { ...defaultDeps, ...deps };
+    const client = resolvedDeps.createClient();
+    const event = await client.repairEvent((0, bluebubbles_model_1.normalizeBlueBubblesEvent)(payload));
+    return handleBlueBubblesNormalizedEvent(event, resolvedDeps, "webhook");
+}
+function countPendingRecoveryCandidates(agentName) {
+    return (0, bluebubbles_mutation_log_1.listBlueBubblesRecoveryCandidates)(agentName)
+        .filter((entry) => !(0, bluebubbles_inbound_log_1.hasRecordedBlueBubblesInbound)(agentName, entry.sessionKey, entry.messageGuid))
+        .length;
+}
+async function syncBlueBubblesRuntime(deps = {}) {
+    const resolvedDeps = { ...defaultDeps, ...deps };
+    const agentName = resolvedDeps.getAgentName();
+    const client = resolvedDeps.createClient();
+    const checkedAt = new Date().toISOString();
+    try {
+        await client.checkHealth();
+        const recovery = await recoverMissedBlueBubblesMessages(resolvedDeps);
+        (0, bluebubbles_runtime_state_1.writeBlueBubblesRuntimeState)(agentName, {
+            upstreamStatus: recovery.pending > 0 || recovery.failed > 0 ? "error" : "ok",
+            detail: recovery.failed > 0
+                ? `recovery failures: ${recovery.failed}`
+                : recovery.pending > 0
+                    ? `pending recovery: ${recovery.pending}`
+                    : "upstream reachable",
+            lastCheckedAt: checkedAt,
+            pendingRecoveryCount: recovery.pending,
+            lastRecoveredAt: recovery.recovered > 0 ? checkedAt : undefined,
+        });
+    }
+    catch (error) {
+        (0, bluebubbles_runtime_state_1.writeBlueBubblesRuntimeState)(agentName, {
+            upstreamStatus: "error",
+            detail: error instanceof Error ? error.message : String(error),
+            lastCheckedAt: checkedAt,
+            pendingRecoveryCount: countPendingRecoveryCandidates(agentName),
+        });
+    }
+}
+async function recoverMissedBlueBubblesMessages(deps = {}) {
+    const resolvedDeps = { ...defaultDeps, ...deps };
+    const agentName = resolvedDeps.getAgentName();
+    const client = resolvedDeps.createClient();
+    const result = { recovered: 0, skipped: 0, pending: 0, failed: 0 };
+    for (const candidate of (0, bluebubbles_mutation_log_1.listBlueBubblesRecoveryCandidates)(agentName)) {
+        if ((0, bluebubbles_inbound_log_1.hasRecordedBlueBubblesInbound)(agentName, candidate.sessionKey, candidate.messageGuid)) {
+            result.skipped++;
+            continue;
+        }
+        try {
+            const repaired = await client.repairEvent(mutationEntryToEvent(candidate));
+            if (repaired.kind !== "message") {
+                result.pending++;
+                continue;
+            }
+            const handled = await handleBlueBubblesNormalizedEvent(repaired, resolvedDeps, "mutation-recovery");
+            if (handled.reason === "already_processed") {
+                result.skipped++;
+            }
+            else {
+                result.recovered++;
+            }
+        }
+        catch (error) {
+            result.failed++;
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.bluebubbles_recovery_error",
+                message: "bluebubbles backlog recovery failed",
+                meta: {
+                    messageGuid: candidate.messageGuid,
+                    reason: error instanceof Error ? error.message : String(error),
+                },
+            });
+        }
+    }
+    if (result.recovered > 0 || result.skipped > 0 || result.pending > 0 || result.failed > 0) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.bluebubbles_recovery_complete",
+            message: "bluebubbles backlog recovery pass completed",
+            meta: { ...result },
+        });
+    }
+    return result;
+}
 function createBlueBubblesWebhookHandler(deps = {}) {
     return async (req, res) => {
         const url = new URL(req.url ?? "/", "http://127.0.0.1");
@@ -842,6 +1009,12 @@ function startBlueBubblesApp(deps = {}) {
     resolvedDeps.createClient();
     const channelConfig = (0, config_1.getBlueBubblesChannelConfig)();
     const server = resolvedDeps.createServer(createBlueBubblesWebhookHandler(deps));
+    const runtimeTimer = setInterval(() => {
+        void syncBlueBubblesRuntime(resolvedDeps);
+    }, BLUEBUBBLES_RUNTIME_SYNC_INTERVAL_MS);
+    server.on?.("close", () => {
+        clearInterval(runtimeTimer);
+    });
     server.listen(channelConfig.port, () => {
         (0, runtime_1.emitNervesEvent)({
             component: "channels",
@@ -850,5 +1023,6 @@ function startBlueBubblesApp(deps = {}) {
             meta: { port: channelConfig.port, webhookPath: channelConfig.webhookPath },
         });
     });
+    void syncBlueBubblesRuntime(resolvedDeps);
     return server;
 }

package/package.json

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

package/subagents/README.md

@@ -36,13 +36,39 @@ cp subagents/*.md ~/.claude/agents/
 ## Installing For Codex-Style Skills
 
 ```bash
-mkdir -p ~/.codex/skills/work-planner ~/.codex/skills/work-doer ~/.codex/skills/work-merger
-cp subagents/work-planner.md ~/.codex/skills/work-planner/SKILL.md
-cp subagents/work-doer.md ~/.codex/skills/work-doer/SKILL.md
-cp subagents/work-merger.md ~/.codex/skills/work-merger/SKILL.md
+mkdir -p ~/.agents/skills/work-planner ~/.agents/skills/work-doer ~/.agents/skills/work-merger
+
+# Hard-link to keep one source of truth
+ln -f "$(pwd)/subagents/work-planner.md" ~/.agents/skills/work-planner/SKILL.md
+ln -f "$(pwd)/subagents/work-doer.md" ~/.agents/skills/work-doer/SKILL.md
+ln -f "$(pwd)/subagents/work-merger.md" ~/.agents/skills/work-merger/SKILL.md
 ```
 
-If you prefer symlinks or hard-links, that is fine too, but plain copies are easier to reason about and easier to repair when editors replace files.
+**Important:** For Codex/OpenAI skill installs, use the generic `~/.agents/skills` root and use hard links (`ln`, not `ln -s`). Installing the same skill into both `~/.agents/skills` and `~/.codex/skills` can produce duplicate entries in Codex. Symlinked `SKILL.md` files may load but are not advertised reliably by Codex surfaces. Hard-links break when editors save by replacing the file (new inode). After editing any `subagents/*.md` file, re-run the `ln -f` command for that file to restore the link. You can verify with `stat -f '%i'` — both files should share the same inode.
+
+Optional UI metadata:
+
+```bash
+mkdir -p ~/.agents/skills/work-planner/agents ~/.agents/skills/work-doer/agents ~/.agents/skills/work-merger/agents
+cat > ~/.agents/skills/work-planner/agents/openai.yaml << 'EOF'
+interface:
+  display_name: "Work Planner"
+  short_description: "Create and gate planning/doing task docs"
+  default_prompt: "Use $work-planner to create or update a planning doc, then stop at NEEDS_REVIEW."
+EOF
+cat > ~/.agents/skills/work-doer/agents/openai.yaml << 'EOF'
+interface:
+  display_name: "Work Doer"
+  short_description: "Execute approved doing docs with strict TDD"
+  default_prompt: "Use $work-doer to execute an approved doing doc unit by unit."
+EOF
+cat > ~/.agents/skills/work-merger/agents/openai.yaml << 'EOF'
+interface:
+  display_name: "Work Merger"
+  short_description: "Merge feature branch into main via PR after work-doer completes"
+  default_prompt: "Use $work-merger to merge the current feature branch into main."
+EOF
+```
 
 ## Keeping Local Skill Copies Fresh
 
@@ -51,8 +77,8 @@ After editing any `subagents/*.md` file, resync your local installed copies.
 The repo workflow usually checks this with diffs like:
 
 ```bash
-diff -q ~/.codex/skills/work-planner/SKILL.md subagents/work-planner.md
-diff -q ~/.codex/skills/work-doer/SKILL.md subagents/work-doer.md
+diff -q ~/.agents/skills/work-planner/SKILL.md subagents/work-planner.md
+diff -q ~/.agents/skills/work-doer/SKILL.md subagents/work-doer.md
 ```
 
 ## Restart Behavior

package/subagents/work-doer.md

@@ -9,13 +9,14 @@ You are a task executor. Read a doing.md file and execute all units sequentially
 ## On Startup
 
 1. **Find task-doc directory**: Read project instructions (for example `AGENTS.md`) to determine where planning/doing docs live for this repo
-2. **Find doing doc**: Look for `YYYY-MM-DD-HHMM-doing-*.md` in that project-defined task-doc directory
-3. If multiple found, ask which one
-4. If none found, ask user for location
-5. **Check execution_mode**: Read the doing doc's `Execution Mode` field
-6. **Verify artifacts directory exists**: `{task-name}/` next to `{task-name}.md`
+2. **Confirm worktree**: Run from the dedicated task worktree required by the project. If the current checkout is shared, ambiguous, or not on the task branch, STOP and switch/create the correct worktree first.
+3. **Find doing doc**: Look for `YYYY-MM-DD-HHMM-doing-*.md` in that project-defined task-doc directory
+4. If multiple found, ask which one
+5. If none found, ask user for location
+6. **Check execution_mode**: Read the doing doc's `Execution Mode` field
+7. **Verify artifacts directory exists**: `{task-name}/` next to `{task-name}.md`
    - If missing, create it: `mkdir {task-name}`
-7. **Detect resume vs fresh start:**
+8. **Detect resume vs fresh start:**
    - Count completed units (✅) vs total units
    - Check git status for uncommitted changes
 
@@ -218,18 +219,19 @@ When all units are `✅`:
 2. **Location**: Read and update doing docs in the project-defined task-doc directory, which may live outside the repo
 3. **Artifacts directory**: Use `{task-name}/` for all outputs, logs, data
 4. **Execution mode**: Honor `pending | spawn | direct` from doing doc
-5. **TDD strictly enforced** — tests before implementation, always
-6. **100% coverage** — no exceptions, no exclude attributes
-7. **Atomic commits** — one logical unit per commit, push after each
-8. **Timestamps from git** — `git log -1 --format="%Y-%m-%d %H:%M"`
-9. **Push after each unit phase complete**
-10. **Update doing.md after each unit** — status and progress log
-11. **Spawn sub-agents for fixes** — don't ask, just do it
-12. **Update docs immediately** — when decisions made, commit right away
-13. **Stop on actual blocker** — unclear requirements or need user input
-14. **/compact proactively** — preserve context between units
-15. **No warnings** — treat warnings as errors
-16. **Run full test suite** — before marking unit complete, not just new tests
-17. **Always compile** — run the project's build command after every implementation/refactor unit. Tests passing is necessary but not sufficient.
-18. **Checklist hygiene is mandatory** — keep doing/planning `Completion Criteria` checklists synchronized with verified completion evidence.
+5. **Respect the approved structure**: A `READY_FOR_EXECUTION` doing doc should already be ambiguity-clean. Do not rewrite unit structure unless the user changes scope or the doing doc is actually blocked/inaccurate.
+6. **TDD strictly enforced** — tests before implementation, always
+7. **100% coverage** — no exceptions, no exclude attributes
+8. **Atomic commits** — one logical unit per commit, push after each
+9. **Timestamps from git** — `git log -1 --format="%Y-%m-%d %H:%M"`
+10. **Push after each unit phase complete**
+11. **Update doing.md after each unit** — status and progress log
+12. **Spawn sub-agents for fixes** — don't ask, just do it
+13. **Update docs immediately** — when decisions made, commit right away
+14. **Stop on actual blocker** — unclear requirements or need user input
+15. **/compact proactively** — preserve context between units
+16. **No warnings** — treat warnings as errors
+17. **Run full test suite** — before marking unit complete, not just new tests
+18. **Always compile** — run the project's build command after every implementation/refactor unit. Tests passing is necessary but not sufficient.
+19. **Checklist hygiene is mandatory** — keep doing/planning `Completion Criteria` checklists synchronized with verified completion evidence.
 19. **Verify APIs before importing** — before writing `import { Foo } from './bar'`, use `grep` or `read_file` to confirm `Foo` is actually exported from that module. Never assume an export exists — always check the source first. This prevents wasted cycles on "module has no exported member" errors.

package/subagents/work-planner.md

@@ -11,10 +11,11 @@ You are a task planner for coding work. Help the user define scope, then convert
 **Determine task doc directory:**
 1. Read project instructions (for example `AGENTS.md`) to find the canonical task-doc location for the current repo
 2. Derive `AGENT` from the current git branch when the project uses agent-scoped task docs
-3. Set `TASK_DIR` to the project-defined planning/doing directory
-4. If the project-defined parent location exists but `TASK_DIR` does not, create it
-5. If the project does not define a task-doc location, STOP and ask the user or caller where planning/doing docs should live
-6. Do not assume task docs live in the repo root; many projects keep them externally
+3. Confirm the task is running from a dedicated task worktree when the project requires parallel agent work; if the checkout is shared or ambiguous, STOP and tell the caller to create/switch to a dedicated worktree first
+4. Set `TASK_DIR` to the project-defined planning/doing directory
+5. If the project-defined parent location exists but `TASK_DIR` does not, create it
+6. If the project does not define a task-doc location, STOP and ask the user or caller where planning/doing docs should live
+7. Do not assume task docs live in the repo root; many projects keep them externally
 
 **Check for existing planning docs:**
 1. Look for `YYYY-MM-DD-HHMM-planning-*.md` files in `TASK_DIR`
@@ -160,7 +161,7 @@ User answers questions → agent updates doc → agent sets status to `NEEDS_REV
 
 **CRITICAL: Planning doc is KEPT. Conversion creates a NEW doing doc alongside it in `TASK_DIR`.**
 
-Run these passes — announce each. **ALL 4 PASSES ARE MANDATORY. You must run every pass, even if you think nothing changed. Each pass MUST have its own commit (use "no changes needed" in the commit message if the pass found nothing to fix). Do NOT skip or combine passes.**
+Run these passes — announce each. **ALL 5 PASSES ARE MANDATORY. You must run every pass, even if you think nothing changed. Each pass MUST have its own commit (use "no changes needed" in the commit message if the pass found nothing to fix). Do NOT skip or combine passes.**
 
 **Pass 1 — First Draft:**
 - Create `YYYY-MM-DD-HHMM-doing-{short-desc}.md` (same timestamp and short-desc as planning)
@@ -181,7 +182,14 @@ Run these passes — announce each. **ALL 4 PASSES ARE MANDATORY. You must run e
 - Update units if reality differs from what was assumed during planning
 - Commit: `git commit -m "docs(doing): validation pass"` (or `"docs(doing): validation pass - no changes needed"` if nothing to fix)
 
-**Pass 4 — Quality:**
+**Pass 4 — Ambiguity:**
+- Remove doer-facing ambiguity before execution starts
+- Tighten units so a `READY_FOR_EXECUTION` doing doc does not require structural rewrites by `work-doer`
+- Resolve fuzzy phrases like "appropriate files", "as needed", or "wherever the bug is" into concrete targets unless the project instructions explicitly require that flexibility
+- If uncertainty remains, keep it in the planning doc's `Open Questions`, set status to `NEEDS_REVIEW`, and STOP instead of shipping an ambiguous doing doc
+- Commit: `git commit -m "docs(doing): ambiguity pass"` (or `"docs(doing): ambiguity pass - no changes needed"` if nothing to fix)
+
+**Pass 5 — Quality:**
 - All units have acceptance criteria?
 - No TBD items?
 - Completion criteria testable?