@ouro.bot/cli 0.1.0-alpha.134 → 0.1.0-alpha.136

package/README.md

@@ -8,7 +8,8 @@ Ouroboros is a TypeScript harness for daemon-managed agents that live in externa
 
 - `npx ouro.bot` is the bootstrap path.
 - `ouro` is the installed day-to-day command.
-- `ouro up` starts or repairs the daemon, syncs the launcher, installs workflow helpers, and reconciles stale runtime state.
+- `ouro up` starts the daemon from the installed production version, syncs the launcher, installs workflow helpers, and reconciles stale runtime state.
+- `ouro dev` starts the daemon from a local repo build (skips update checker, writes plist to repo path).
 - Agent bundles live outside the repo at `~/AgentBundles/<agent>.ouro/`.
 - Secrets live outside the repo at `~/.agentsecrets/<agent>/secrets.json`.
 - Machine-scoped test and runtime spillover lives under `~/.agentstate/...`.
@@ -141,7 +142,10 @@ If you are changing runtime code, keep all three green.
 ## Common Commands
 
 ```bash
-ouro up
+ouro up                          # start daemon from installed production version
+ouro dev                         # start daemon from local repo build
+ouro dev --repo-path /path       # start from a specific repo checkout
+ouro dev --clone                 # clone repo to ~/Projects/ouroboros, build, start
 ouro status
 ouro logs
 ouro stop

package/changelog.json

@@ -1,6 +1,22 @@
 {
   "_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.136",
+      "changes": [
+        "Dev mode DX: ouro dev starts daemon from local repo build, skips update checker, prints dev mode indicator.",
+        "ouro up from dev context delegates to installed production binary or errors with install guidance.",
+        "Daemon accepts mode option; update checker suppressed in dev mode with daemon.update_checker_skip event.",
+        "Daemon entry emits daemon.dev_mode_indicator nerves event when running from a dev repo."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.135",
+      "changes": [
+        "Metacognitive tool vocabulary complete: go_inward renamed to descend. RunAgentOutcome value is now 'descended', event is 'engine.descended'.",
+        "summarizeArgs rewritten: reads summaryKeys from ToolDefinition instead of per-tool switch branches. summarizeTeamsArgs and summarizeGithubArgs eliminated."
+      ]
+    },
     {
       "version": "0.1.0-alpha.134",
       "changes": [

package/dist/heart/core.js

@@ -176,7 +176,7 @@ Object.defineProperty(exports, "buildSystem", { enumerable: true, get: function
 const SOLE_CALL_REJECTION = {
     settle: "rejected: settle must be the only tool call. finish your work first, then call settle alone.",
     observe: "rejected: observe must be the only tool call. call observe alone when you want to stay silent.",
-    go_inward: "rejected: go_inward must be the only tool call. finish your other work first, then call go_inward alone.",
+    descend: "rejected: descend must be the only tool call. finish your other work first, then call descend alone.",
 };
 const DELEGATION_REASON_PROSE_HANDOFF = {
     explicit_reflection: "something in the conversation called for reflection",
@@ -186,7 +186,7 @@ const DELEGATION_REASON_PROSE_HANDOFF = {
     non_fast_path_tool: "this needs tools beyond a simple reply",
     unresolved_obligation: "there's an unresolved commitment from an earlier conversation",
 };
-function buildGoInwardHandoffPacket(params) {
+function buildDescendHandoffPacket(params) {
     const reasons = params.delegationDecision?.reasons ?? [];
     const reasonProse = reasons.length > 0
         ? reasons.map((r) => DELEGATION_REASON_PROSE_HANDOFF[r]).join("; ")
@@ -245,14 +245,14 @@ function isExternalStateQuery(toolName, args) {
     const cmd = String(args.command ?? "");
     return /\bgh\s+(pr|run|api|issue)\b/.test(cmd) || /\bnpm\s+(view|info|show)\b/.test(cmd);
 }
-function getSettleRetryError(mustResolveBeforeHandoff, intent, sawSteeringFollowUp, _delegationDecision, sawSendMessageSelf, sawGoInward, _sawQuerySession, currentObligation, innerJob, sawExternalStateQuery) {
+function getSettleRetryError(mustResolveBeforeHandoff, intent, sawSteeringFollowUp, _delegationDecision, sawSendMessageSelf, sawDescend, _sawQuerySession, currentObligation, innerJob, sawExternalStateQuery) {
     // Delegation adherence removed: the delegation decision is surfaced in the
     // system prompt as a suggestion. Hard-gating settle caused infinite
     // rejection loops where the agent couldn't respond to the user at all.
     // The agent is free to follow or ignore the delegation hint.
     // 2. Pending obligation not addressed
-    if (innerJob?.obligationStatus === "pending" && !sawSendMessageSelf && !sawGoInward) {
-        return "you're still holding something from an earlier conversation -- someone is waiting for your answer. finish the thought first, or go_inward to keep working on it privately.";
+    if (innerJob?.obligationStatus === "pending" && !sawSendMessageSelf && !sawDescend) {
+        return "you're still holding something from an earlier conversation -- someone is waiting for your answer. finish the thought first, or descend to keep working on it privately.";
     }
     // 3. mustResolveBeforeHandoff + missing intent
     if (mustResolveBeforeHandoff && !intent) {
@@ -496,7 +496,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
     let mustResolveBeforeHandoffActive = options?.mustResolveBeforeHandoff === true;
     let currentReasoningEffort = "medium";
     let sawSendMessageSelf = false;
-    let sawGoInward = false;
+    let sawDescend = false;
     let sawQuerySession = false;
     let sawBridgeManage = false;
     let sawExternalStateQuery = false;
@@ -522,11 +522,11 @@ async function runAgent(messages, callbacks, channel, signal, options) {
     providerRuntime.resetTurnState(messages);
     while (!done) {
         // Channel-based tool filtering:
-        // - Inner dialog: exclude go_inward (already inward), send_message (delivery via surface), observe (no one to observe)
+        // - Inner dialog: exclude descend (already inward), send_message (delivery via surface), observe (no one to observe)
         // - 1:1 sessions: exclude observe (can't ignore someone talking directly to you)
         // - Group chats: observe available
         //
-        // go_inward, settle, surface, and observe are always assembled based on channel context.
+        // descend, settle, surface, and observe are always assembled based on channel context.
         // toolChoiceRequired only controls whether tool_choice: "required" is set in the API call.
         const isInnerDialog = channel === "inner";
         const filteredBaseTools = isInnerDialog
@@ -534,7 +534,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             : baseTools;
         const activeTools = [
             ...filteredBaseTools,
-            ...(!isInnerDialog ? [tools_1.goInwardTool] : []),
+            ...(!isInnerDialog ? [tools_1.descendTool] : []),
             ...(isInnerDialog ? [surface_tool_1.surfaceToolDef] : []),
             ...(currentContext?.isGroupChat && !isInnerDialog ? [tools_1.observeTool] : []),
             tools_1.settleTool,
@@ -619,9 +619,18 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             else {
                 // Check for settle sole call: intercept before tool execution
                 if (isSoleSettle) {
+                    /* v8 ignore next -- defensive: JSON.parse catch for malformed settle args @preserve */
+                    const settleArgs = (() => { try {
+                        return JSON.parse(result.toolCalls[0].arguments);
+                    }
+                    catch {
+                        return {};
+                    } })();
+                    callbacks.onToolStart("settle", settleArgs);
                     // Inner dialog attention queue gate: reject settle if items remain
                     const attentionQueue = (augmentedToolContext ?? options?.toolContext)?.delegatedOrigins;
                     if (isInnerDialog && attentionQueue && attentionQueue.length > 0) {
+                        callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), false);
                         callbacks.onClearText?.();
                         messages.push(msg);
                         const gateMessage = "you're holding thoughts someone is waiting for — surface them before you settle.";
@@ -634,6 +643,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     const { answer, intent } = parseSettlePayload(result.toolCalls[0].arguments);
                     // Inner dialog settle: no CompletionMetadata, "(settled)" ack
                     if (isInnerDialog) {
+                        callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), true);
                         messages.push(msg);
                         const settled = "(settled)";
                         messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: settled });
@@ -642,7 +652,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         done = true;
                         continue;
                     }
-                    const retryError = getSettleRetryError(mustResolveBeforeHandoffActive, intent, sawSteeringFollowUp, options?.delegationDecision, sawSendMessageSelf, sawGoInward, sawQuerySession, options?.currentObligation ?? null, options?.activeWorkFrame?.inner?.job, sawExternalStateQuery);
+                    const retryError = getSettleRetryError(mustResolveBeforeHandoffActive, intent, sawSteeringFollowUp, options?.delegationDecision, sawSendMessageSelf, sawDescend, sawQuerySession, options?.currentObligation ?? null, options?.activeWorkFrame?.inner?.job, sawExternalStateQuery);
                     const deliveredAnswer = answer;
                     const validDirectReply = mustResolveBeforeHandoffActive && intent === "direct_reply" && sawSteeringFollowUp;
                     const validTerminalIntent = intent === "complete" || intent === "blocked";
@@ -650,6 +660,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         && !retryError
                         && (!mustResolveBeforeHandoffActive || validDirectReply || validTerminalIntent);
                     if (validClosure) {
+                        callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), true);
                         completion = {
                             answer: deliveredAnswer,
                             intent: validDirectReply ? "direct_reply" : intent === "blocked" ? "blocked" : "complete",
@@ -684,6 +695,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         // Answer is undefined -- the model's settle was incomplete or
                         // malformed. Clear any partial streamed text or noise, then push the
                         // assistant msg + error tool result and let the model try again.
+                        callbacks.onToolEnd("settle", (0, tools_1.summarizeArgs)("settle", settleArgs), false);
                         callbacks.onClearText?.();
                         messages.push(msg);
                         const toolRetryMessage = retryError
@@ -696,19 +708,24 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 // Check for observe sole call: intercept before tool execution
                 const isSoleObserve = result.toolCalls.length === 1 && result.toolCalls[0].name === "observe";
                 if (isSoleObserve) {
-                    let reason;
-                    try {
-                        const parsed = JSON.parse(result.toolCalls[0].arguments);
-                        if (typeof parsed?.reason === "string")
-                            reason = parsed.reason;
+                    /* v8 ignore next -- defensive: JSON.parse catch for malformed observe args @preserve */
+                    const observeArgs = (() => { try {
+                        return JSON.parse(result.toolCalls[0].arguments);
                     }
-                    catch { /* ignore */ }
+                    catch {
+                        return {};
+                    } })();
+                    let reason;
+                    if (typeof observeArgs?.reason === "string")
+                        reason = observeArgs.reason;
+                    callbacks.onToolStart("observe", observeArgs);
                     (0, runtime_1.emitNervesEvent)({
                         component: "engine",
                         event: "engine.observe",
                         message: "agent declined to respond in group chat",
                         meta: { ...(reason ? { reason } : {}) },
                     });
+                    callbacks.onToolEnd("observe", (0, tools_1.summarizeArgs)("observe", observeArgs), true);
                     messages.push(msg);
                     const silenced = "(silenced)";
                     messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: silenced });
@@ -717,14 +734,15 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     done = true;
                     continue;
                 }
-                // Check for go_inward sole call: intercept before tool execution
-                const isSoleGoInward = result.toolCalls.length === 1 && result.toolCalls[0].name === "go_inward";
-                if (isSoleGoInward) {
+                // Check for descend sole call: intercept before tool execution
+                const isSoleDescend = result.toolCalls.length === 1 && result.toolCalls[0].name === "descend";
+                if (isSoleDescend) {
                     let parsedArgs = {};
                     try {
                         parsedArgs = JSON.parse(result.toolCalls[0].arguments);
                     }
                     catch { /* ignore */ }
+                    callbacks.onToolStart("descend", parsedArgs);
                     /* v8 ignore next -- defensive: topic always string from model @preserve */
                     const topic = typeof parsedArgs.topic === "string" ? parsedArgs.topic : "";
                     const answer = typeof parsedArgs.answer === "string" ? parsedArgs.answer : undefined;
@@ -738,7 +756,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                         callbacks.onTextChunk(answer);
                     }
                     // Build handoff packet and enqueue
-                    const handoffContent = buildGoInwardHandoffPacket({
+                    const handoffContent = buildDescendHandoffPacket({
                         topic,
                         mode,
                         delegationDecision: options?.delegationDecision,
@@ -749,6 +767,24 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     const pendingDir = (0, pending_1.getInnerDialogPendingDir)((0, identity_2.getAgentName)());
                     const currentSession = options?.toolContext?.currentSession;
                     const isInnerChannel = currentSession?.friendId === "self" && currentSession?.channel === "inner";
+                    // Create obligation FIRST so we can attach its ID to the pending message
+                    let createdObligationId;
+                    if (currentSession && !isInnerChannel) {
+                        try {
+                            const obligation = (0, obligations_1.createObligation)((0, identity_2.getAgentRoot)(), {
+                                origin: {
+                                    friendId: currentSession.friendId,
+                                    channel: currentSession.channel,
+                                    key: currentSession.key,
+                                },
+                                content: topic,
+                            });
+                            createdObligationId = obligation.id;
+                        }
+                        catch {
+                            /* v8 ignore next -- defensive: obligation store write failure should not break descend @preserve */
+                        }
+                    }
                     const envelope = {
                         from: (0, identity_2.getAgentName)(),
                         friendId: "self",
@@ -764,40 +800,28 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                                 key: currentSession.key,
                             },
                             obligationStatus: "pending",
+                            /* v8 ignore next -- defensive: createdObligationId is undefined only when obligation store write fails @preserve */
+                            ...(createdObligationId ? { obligationId: createdObligationId } : {}),
                         } : {}),
                     };
                     (0, pending_1.queuePendingMessage)(pendingDir, envelope);
-                    if (currentSession && !isInnerChannel) {
-                        try {
-                            (0, obligations_1.createObligation)((0, identity_2.getAgentRoot)(), {
-                                origin: {
-                                    friendId: currentSession.friendId,
-                                    channel: currentSession.channel,
-                                    key: currentSession.key,
-                                },
-                                content: topic,
-                            });
-                        }
-                        catch {
-                            /* v8 ignore next -- defensive: obligation store write failure should not break go_inward @preserve */
-                        }
-                    }
                     try {
                         await (0, socket_client_1.requestInnerWake)((0, identity_2.getAgentName)());
                     }
                     catch { /* daemon may not be running */ }
-                    sawGoInward = true;
+                    callbacks.onToolEnd("descend", (0, tools_1.summarizeArgs)("descend", parsedArgs), true);
+                    sawDescend = true;
                     messages.push(msg);
                     const ack = "(going inward)";
                     messages.push({ role: "tool", tool_call_id: result.toolCalls[0].id, content: ack });
                     providerRuntime.appendToolOutput(result.toolCalls[0].id, ack);
                     (0, runtime_1.emitNervesEvent)({
                         component: "engine",
-                        event: "engine.go_inward",
+                        event: "engine.descended",
                         message: "taking thread inward",
                         meta: { mode, hasAnswer: answer !== undefined, contentSnippet: topic.slice(0, 80) },
                     });
-                    outcome = "go_inward";
+                    outcome = "descended";
                     done = true;
                     continue;
                 }
@@ -957,7 +981,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         trace_id: traceId,
         component: "engine",
         message: "runAgent turn completed",
-        meta: { done, sawGoInward, sawQuerySession, sawBridgeManage },
+        meta: { done, sawDescend, sawQuerySession, sawBridgeManage },
     });
     return {
         usage: lastUsage,

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

@@ -272,6 +272,7 @@ function usage() {
     return [
         "Usage:",
         "  ouro [up]",
+        "  ouro dev [--repo-path <path>] [--clone [--clone-path <path>]]",
         "  ouro stop|down|status|logs|hatch",
         "  ouro -v|--version",
         "  ouro config model --agent <name> <model-name>",
@@ -899,6 +900,27 @@ function parseOuroCommand(args) {
     }
     if (head === "up")
         return { kind: "daemon.up" };
+    if (head === "dev") {
+        const devArgs = args.slice(1);
+        let repoPath;
+        let clone = false;
+        let clonePath;
+        for (let i = 0; i < devArgs.length; i++) {
+            if (devArgs[i] === "--repo-path" && devArgs[i + 1]) {
+                repoPath = devArgs[++i];
+                continue;
+            }
+            if (devArgs[i] === "--clone") {
+                clone = true;
+                continue;
+            }
+            if (devArgs[i] === "--clone-path" && devArgs[i + 1]) {
+                clonePath = devArgs[++i];
+                continue;
+            }
+        }
+        return { kind: "daemon.dev", repoPath, clone, clonePath };
+    }
     if (head === "rollback")
         return { kind: "rollback", ...(second ? { version: second } : {}) };
     if (head === "versions")
@@ -1383,6 +1405,19 @@ function createDefaultOuroCliDeps(socketPath = socket_client_1.DEFAULT_DAEMON_SO
         syncGlobalOuroBotWrapper: ouro_bot_global_installer_1.syncGlobalOuroBotWrapper,
         ensureSkillManagement: skill_management_installer_1.ensureSkillManagement,
         ensureDaemonBootPersistence: defaultEnsureDaemonBootPersistence,
+        /* v8 ignore start -- dev-mode defaults: tests inject mocks for mode detection and binary resolution @preserve */
+        detectMode: () => (0, runtime_mode_1.detectRuntimeMode)((0, identity_1.getRepoRoot)()),
+        getInstalledBinaryPath: () => {
+            const cliHome = (0, ouro_version_manager_1.getOuroCliHome)();
+            const binaryPath = path.join(cliHome, "bin", "ouro");
+            return fs.existsSync(binaryPath) ? binaryPath : null;
+        },
+        execInstalledBinary: (binaryPath, binArgs) => {
+            const { execFileSync } = require("child_process");
+            execFileSync(binaryPath, binArgs, { stdio: "inherit" });
+            process.exit(0);
+        },
+        /* v8 ignore stop */
         /* v8 ignore next 3 -- integration: launches interactive CLI session @preserve */
         startChat: async (agentName) => {
             const { main } = await Promise.resolve().then(() => __importStar(require("../../senses/cli")));
@@ -1726,6 +1761,48 @@ function executeReminderCommand(command, taskMod) {
         return `error: ${error instanceof Error ? error.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(error)}`;
     }
 }
+/* v8 ignore start -- repo resolution for ouro dev: repoPath branch tested via daemon-cli-dev; clone requires real git/npm @preserve */
+function resolveDevRepoCwd(command, checkExists, deps) {
+    if (command.repoPath)
+        return path.resolve(command.repoPath);
+    if (command.clone)
+        return resolveClonePath(command, checkExists, deps);
+    return deps.getRepoCwd ? deps.getRepoCwd() : (0, identity_1.getRepoRoot)();
+}
+/* v8 ignore stop */
+/* v8 ignore start -- clone/build: requires real git clone + npm install on disk @preserve */
+function resolveClonePath(command, checkExists, deps) {
+    const cloneTarget = command.clonePath
+        ? path.resolve(command.clonePath)
+        : path.join(os.homedir(), "Projects", "ouroboros");
+    if (!checkExists(path.join(cloneTarget, ".git"))) {
+        deps.writeStdout(`cloning ouroboros to ${cloneTarget}...`);
+        try {
+            (0, child_process_1.execSync)(`git clone ${identity_1.HARNESS_CANONICAL_REPO_URL} "${cloneTarget}"`, { stdio: "inherit" });
+        }
+        catch {
+            throw new Error(`clone failed. check your network and try again, or clone manually and use --repo-path.`);
+        }
+    }
+    else {
+        deps.writeStdout(`repo already exists at ${cloneTarget}, pulling latest...`);
+        try {
+            (0, child_process_1.execSync)("git pull --ff-only", { cwd: cloneTarget, stdio: "inherit" });
+        }
+        catch {
+            deps.writeStdout("pull failed (may have local changes). continuing with existing code.");
+        }
+    }
+    deps.writeStdout("building...");
+    try {
+        (0, child_process_1.execSync)("npm install && npm run build", { cwd: cloneTarget, stdio: "inherit" });
+    }
+    catch {
+        throw new Error(`build failed in ${cloneTarget}. check the output above.`);
+    }
+    return cloneTarget;
+}
+/* v8 ignore stop */
 async function runOuroCli(args, deps = createDefaultOuroCliDeps()) {
     if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
         const text = usage();
@@ -1807,6 +1884,27 @@ async function runOuroCli(args, deps = createDefaultOuroCliDeps()) {
         meta: { kind: command.kind },
     });
     if (command.kind === "daemon.up") {
+        // ── dev mode delegation: ouro up from a dev repo delegates to installed binary ──
+        // Only runs when detectMode is explicitly injected (via createDefaultOuroCliDeps or tests)
+        if (deps.detectMode) {
+            const runtimeMode = deps.detectMode();
+            if (runtimeMode === "dev") {
+                /* v8 ignore next -- defensive: getInstalledBinaryPath always injected in tests @preserve */
+                const installedBinary = deps.getInstalledBinaryPath ? deps.getInstalledBinaryPath() : null;
+                if (installedBinary) {
+                    deps.writeStdout("delegating to installed ouro...");
+                    /* v8 ignore next 3 -- defensive: execInstalledBinary always injected; missing branch unreachable @preserve */
+                    if (deps.execInstalledBinary) {
+                        deps.execInstalledBinary(installedBinary, args);
+                    }
+                    /* v8 ignore next 2 -- unreachable after exec replaces process @preserve */
+                    return "";
+                }
+                const message = "no installed version found. run: npx @ouro.bot/cli@alpha";
+                deps.writeStdout(message);
+                return message;
+            }
+        }
         const linkedVersionBeforeUp = deps.getCurrentCliVersion?.() ?? null;
         // ── versioned CLI update check ──
         if (deps.checkForCliUpdate) {
@@ -1900,6 +1998,69 @@ async function runOuroCli(args, deps = createDefaultOuroCliDeps()) {
         deps.writeStdout(daemonResult.message);
         return daemonResult.message;
     }
+    if (command.kind === "daemon.dev") {
+        /* v8 ignore next -- defensive: existsSync always injected in tests @preserve */
+        const checkExists = deps.existsSync ?? fs.existsSync;
+        /* v8 ignore next -- repo resolution dispatched to v8-ignored helper @preserve */
+        const repoCwd = resolveDevRepoCwd(command, checkExists, deps);
+        const entryPath = path.join(repoCwd, "dist", "heart", "daemon", "daemon-entry.js");
+        if (!checkExists(entryPath) || !checkExists(path.join(repoCwd, ".git"))) {
+            const lines = [
+                "no harness repo found at " + repoCwd,
+                "",
+                "options:",
+                "  ouro dev --repo-path /path/to/ouroboros   use an existing checkout",
+                "  ouro dev --clone                          fresh clone to ~/Projects/ouroboros",
+                "  ouro dev --clone --clone-path /somewhere   fresh clone to a custom path",
+                "",
+                "if you have the repo, cd into it and run: npm run build && ouro dev",
+            ];
+            const message = lines.join("\n");
+            deps.writeStdout(message);
+            return message;
+        }
+        /* v8 ignore start -- defensive: ensureDaemonBootPersistence always injected in tests @preserve */
+        if (deps.ensureDaemonBootPersistence) {
+            try {
+                await Promise.resolve(deps.ensureDaemonBootPersistence(deps.socketPath));
+                /* v8 ignore next -- defensive: boot persistence error should not block dev mode @preserve */
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "daemon",
+                    event: "daemon.dev_boot_persistence_error",
+                    message: "failed to persist daemon boot startup in dev mode",
+                    meta: { error: error instanceof Error ? error.message : String(error), socketPath: deps.socketPath },
+                });
+            }
+            /* v8 ignore stop */
+        }
+        // Always force-restart in dev mode — you rebuilt, you want this code running
+        /* v8 ignore start -- dev force-restart: socket alive/stop/spawn tested via integration; tests inject mocks @preserve */
+        const alive = await deps.checkSocketAlive(deps.socketPath);
+        if (alive) {
+            try {
+                await deps.sendCommand(deps.socketPath, { kind: "daemon.stop" });
+            }
+            catch { /* already stopping */ }
+        }
+        deps.cleanupStaleSocket(deps.socketPath);
+        const devEntry = path.join(repoCwd, "dist", "heart", "daemon", "daemon-entry.js");
+        const startDevDaemon = deps.startDaemonProcess === defaultStartDaemonProcess
+            ? async (sp) => {
+                const child = (0, child_process_1.spawn)("node", [devEntry, "--socket", sp], { detached: true, stdio: "ignore" });
+                child.unref();
+                return { pid: child.pid ?? null };
+            }
+            : deps.startDaemonProcess;
+        /* v8 ignore stop */
+        const started = await startDevDaemon(deps.socketPath);
+        /* v8 ignore next -- defensive: pid is null only when spawn fails silently @preserve */
+        const message = `daemon running in dev mode from ${repoCwd} (pid ${started.pid ?? "unknown"})`;
+        deps.writeStdout(message);
+        return message;
+    }
     // ── rollback command (local, no daemon socket needed for symlinks) ──
     /* v8 ignore start -- rollback/versions: tested via daemon-cli-rollback/versions tests @preserve */
     if (command.kind === "rollback") {

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

@@ -66,6 +66,16 @@ const mode = (0, runtime_mode_1.detectRuntimeMode)((0, identity_1.getRepoRoot)()
     message: "starting daemon entrypoint",
     meta: { socketPath, entryPath, mode },
 });
+/* v8 ignore next -- dev-mode indicator: false branch (production) tested in daemon-boot-updates.test.ts @preserve */
+if (mode === "dev") {
+    const repoRoot = (0, identity_1.getRepoRoot)();
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.dev_mode_indicator",
+        message: `[dev] running from ${repoRoot}`,
+        meta: { repoRoot },
+    });
+}
 const managedAgents = (0, agent_discovery_1.listEnabledBundleAgents)();
 const processManager = new process_manager_1.DaemonProcessManager({
     agents: managedAgents.map((agent) => ({
@@ -103,6 +113,7 @@ const daemon = new daemon_1.OuroDaemon({
     scheduler,
     healthMonitor,
     router,
+    mode,
 });
 void daemon.start().catch(async () => {
     (0, runtime_1.emitNervesEvent)({

package/dist/heart/daemon/daemon.js

@@ -174,6 +174,7 @@ class OuroDaemon {
     router;
     senseManager;
     bundlesRoot;
+    mode;
     server = null;
     constructor(options) {
         this.socketPath = options.socketPath;
@@ -183,6 +184,7 @@ class OuroDaemon {
         this.router = options.router;
         this.senseManager = options.senseManager ?? null;
         this.bundlesRoot = options.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
+        this.mode = options.mode ?? "production";
     }
     async start() {
         if (this.server)
@@ -198,39 +200,50 @@ class OuroDaemon {
         const currentVersion = (0, bundle_manifest_1.getPackageVersion)();
         await (0, update_hooks_1.applyPendingUpdates)(this.bundlesRoot, currentVersion);
         // Start periodic update checker (polls npm registry every 30 minutes)
+        // Skip in dev mode — dev builds should not auto-update from npm
         const bundlesRoot = this.bundlesRoot;
-        const daemon = this;
-        (0, update_checker_1.startUpdateChecker)({
-            currentVersion,
-            deps: {
-                distTag: "alpha",
-                fetchRegistryJson: /* v8 ignore next -- integration: real HTTP fetch @preserve */ async () => {
-                    const res = await fetch("https://registry.npmjs.org/@ouro.bot/cli");
-                    return res.json();
-                },
-            },
-            onUpdate: /* v8 ignore start -- integration: real npm install + process spawn @preserve */ async (result) => {
-                if (!result.latestVersion)
-                    return;
-                await (0, staged_restart_1.performStagedRestart)(result.latestVersion, {
-                    execSync: (cmd) => (0, child_process_1.execSync)(cmd, { stdio: "inherit" }),
-                    spawnSync: child_process_1.spawnSync,
-                    resolveNewCodePath: (_version) => {
-                        try {
-                            const resolved = (0, child_process_1.execSync)(`node -e "console.log(require.resolve('@ouro.bot/cli/package.json'))"`, { encoding: "utf-8" }).trim();
-                            return resolved ? path.dirname(resolved) : null;
-                        }
-                        catch {
-                            return null;
-                        }
+        if (this.mode === "dev") {
+            (0, runtime_1.emitNervesEvent)({
+                component: "daemon",
+                event: "daemon.update_checker_skip",
+                message: "skipping update checker in dev mode",
+                meta: { reason: "dev mode" },
+            });
+        }
+        else {
+            const daemon = this;
+            (0, update_checker_1.startUpdateChecker)({
+                currentVersion,
+                deps: {
+                    distTag: "alpha",
+                    fetchRegistryJson: /* v8 ignore next -- integration: real HTTP fetch @preserve */ async () => {
+                        const res = await fetch("https://registry.npmjs.org/@ouro.bot/cli");
+                        return res.json();
                     },
-                    gracefulShutdown: () => daemon.stop(),
-                    nodePath: process.execPath,
-                    bundlesRoot,
-                });
-            },
-            /* v8 ignore stop */
-        });
+                },
+                onUpdate: /* v8 ignore start -- integration: real npm install + process spawn @preserve */ async (result) => {
+                    if (!result.latestVersion)
+                        return;
+                    await (0, staged_restart_1.performStagedRestart)(result.latestVersion, {
+                        execSync: (cmd) => (0, child_process_1.execSync)(cmd, { stdio: "inherit" }),
+                        spawnSync: child_process_1.spawnSync,
+                        resolveNewCodePath: (_version) => {
+                            try {
+                                const resolved = (0, child_process_1.execSync)(`node -e "console.log(require.resolve('@ouro.bot/cli/package.json'))"`, { encoding: "utf-8" }).trim();
+                                return resolved ? path.dirname(resolved) : null;
+                            }
+                            catch {
+                                return null;
+                            }
+                        },
+                        gracefulShutdown: () => daemon.stop(),
+                        nodePath: process.execPath,
+                        bundlesRoot,
+                    });
+                },
+                /* v8 ignore stop */
+            });
+        }
         // Pre-initialize MCP connections so they're ready for the first command (non-blocking)
         /* v8 ignore next -- catch callback: getSharedMcpManager logs errors internally @preserve */
         (0, mcp_manager_1.getSharedMcpManager)().catch(() => { });

package/dist/heart/tool-loop.js

@@ -178,8 +178,12 @@ function recordToolOutcome(state, toolName, args, result, success) {
         state.history.splice(0, state.history.length - exports.TOOL_LOOP_HISTORY_LIMIT);
     }
 }
+// Tools that must never be blocked by the circuit breaker.
+// settle = end the turn, surface = deliver results outward.
+// Blocking these traps the agent: it can think all it wants but can never speak.
+const CIRCUIT_BREAKER_EXEMPT = new Set(["settle", "surface"]);
 function detectToolLoop(state, toolName, args) {
-    if (state.history.length >= exports.GLOBAL_CIRCUIT_BREAKER_LIMIT) {
+    if (state.history.length >= exports.GLOBAL_CIRCUIT_BREAKER_LIMIT && !CIRCUIT_BREAKER_EXEMPT.has(toolName)) {
         return emitDetection("global_circuit_breaker", toolName, state.history.length, `this turn has already made ${state.history.length} tool calls. stop thrashing, use the current evidence, and either change approach or answer truthfully with the best grounded status.`);
     }
     const callHash = digest(normalizeArgs(toolName, args));