@ouro.bot/cli 0.1.0-alpha.423 → 0.1.0-alpha.426

package/changelog.json

@@ -1,6 +1,36 @@
 {
   "_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.426",
+      "changes": [
+        "`ouro up` no longer marks `starting daemon` complete when a replacement daemon still is not answering; it now narrates replacement progress in plain language and reports replacement timeout as an incomplete replacement instead of a fake success.",
+        "Root `ouro connect --agent <agent>` now prints a short `checking current connections` preflight while it reads portable and machine-local runtime settings before showing the connect bay menu.",
+        "Auth/provider/setup docs now codify the human CLI rule that waits longer than about three seconds should show current work, and they describe the new daemon replacement wording and connect-bay preflight.",
+        "`@ouro.bot/cli` and the `ouro.bot` wrapper are version-synced for the daemon replacement and connect-bay progress release."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.425",
+      "changes": [
+        "Human-facing single-agent CLI commands now resolve an omitted `--agent` through one shared path: use the explicit flag when present, otherwise use runtime identity when it can name the current agent, otherwise use the only discovered local agent, otherwise ask which agent to use, and otherwise explain how to hatch or clone one.",
+        "`ouro auth`, `ouro auth verify`, `ouro auth switch`, `ouro use`, `ouro provider` commands, `ouro vault` commands, `ouro connect`, `ouro config model`, `ouro config models`, `ouro setup`, `ouro bluebubbles replay`, `ouro thoughts`, `ouro attention`, `ouro inner`, `ouro task`, `ouro reminder create`, `ouro friend` management commands, `ouro habit`, and `ouro session list` now share that missing-agent contract instead of quietly depending on argv or ambient context.",
+        "Task/reminder execution now builds agent-scoped task modules directly from the selected bundle, session scanning now accepts an explicit agent name, and local friend/habit flows now read the selected agent bundle instead of falling back to hidden global defaults.",
+        "`ouro whoami` keeps its richer runtime identity output but now shares the same no-agent fallback behavior when runtime identity is unavailable, and the runtime seam no longer grabs unrelated ambient repo identity behind the human's back.",
+        "CLI help and execution coverage now protect single-agent auto-selection, multi-agent prompting, no-agent guidance, noninteractive ambiguity handling, and the newly covered local task/reminder/friend/habit/session flows.",
+        "`@ouro.bot/cli` and the `ouro.bot` wrapper are version-synced for the complete missing-agent resolution release."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.424",
+      "changes": [
+        "Human-facing single-agent CLI commands now resolve an omitted `--agent` through one shared path: use the explicit flag when present, otherwise use the only installed agent, otherwise ask which agent to use, and otherwise explain how to hatch or clone one.",
+        "`ouro auth`, `ouro auth verify`, `ouro auth switch`, `ouro use`, `ouro provider refresh`, `ouro provider check`, `ouro provider status`, `ouro vault` commands, `ouro connect`, `ouro config model`, `ouro config models`, `ouro setup`, and `ouro bluebubbles replay` now accept `[--agent <name>]` instead of failing during parse before Ouro has a chance to help.",
+        "`ouro whoami` keeps its richer runtime identity output but now shares the same no-agent fallback behavior when runtime identity is unavailable, and the runtime seam no longer grabs unrelated ambient repo identity behind the human's back.",
+        "CLI help text now tells the truth about optional-agent behavior, and focused parser/execution/help coverage protects single-agent auto-selection, multi-agent prompting, no-agent guidance, and noninteractive ambiguity handling.",
+        "`@ouro.bot/cli` and the `ouro.bot` wrapper are version-synced for the missing-agent resolution release."
+      ]
+    },
     {
       "version": "0.1.0-alpha.423",
       "changes": [

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

@@ -587,8 +587,7 @@ function createDefaultOuroCliDeps(socketPath = socket_client_1.DEFAULT_DAEMON_SO
             const { main } = await Promise.resolve().then(() => __importStar(require("../../senses/cli")));
             await main(agentName);
         },
-        scanSessions: async () => {
-            const agentName = (0, identity_1.getAgentName)();
+        scanSessions: async (agentName) => {
             const agentRoot = (0, identity_1.getAgentRoot)(agentName);
             return (0, session_activity_1.listSessionActivity)({
                 sessionsDir: path.join(agentRoot, "state", "sessions"),

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

@@ -158,6 +158,132 @@ async function listCliAgents(deps) {
     }
     return [];
 }
+function runtimeContextAgentName(deps) {
+    try {
+        return deps.whoamiInfo?.().agentName.trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizeCliAgentNames(agentNames) {
+    return [...new Set(agentNames.map((agent) => agent.trim()).filter((agent) => agent.length > 0))];
+}
+function resolveSelectedCliAgent(answer, agentNames) {
+    const trimmed = answer.trim();
+    if (!trimmed)
+        return undefined;
+    const byName = agentNames.find((agent) => agent.toLowerCase() === trimmed.toLowerCase());
+    if (byName)
+        return byName;
+    const parsedIndex = Number.parseInt(trimmed, 10);
+    if (Number.isNaN(parsedIndex))
+        return undefined;
+    return agentNames[parsedIndex - 1];
+}
+function noAgentsFoundMessage() {
+    return "no agents found. Run `ouro` to hatch one or `ouro clone <remote>` to add an existing agent.";
+}
+function multipleAgentsFoundMessage(agentNames) {
+    return [
+        `multiple agents found: ${agentNames.join(", ")}`,
+        "Re-run with --agent <name>.",
+    ].join("\n");
+}
+function invalidAgentSelectionMessage(agentNames) {
+    return [
+        `invalid agent selection. Available agents: ${agentNames.join(", ")}`,
+        "Re-run with --agent <name>.",
+    ].join("\n");
+}
+function agentResolutionFailureMode(command) {
+    switch (command.kind) {
+        case "task.board":
+        case "task.create":
+        case "task.update":
+        case "task.show":
+        case "task.actionable":
+        case "task.deps":
+        case "task.sessions":
+        case "task.fix":
+        case "reminder.create":
+        case "friend.list":
+        case "friend.show":
+        case "friend.create":
+        case "friend.update":
+        case "habit.list":
+        case "habit.create":
+        case "thoughts":
+        case "attention.list":
+        case "attention.show":
+        case "attention.history":
+        case "inner.status":
+        case "session.list":
+            return "return-message";
+        case "provider.use":
+        case "provider.check":
+        case "provider.status":
+        case "provider.refresh":
+        case "vault.create":
+        case "vault.replace":
+        case "vault.recover":
+        case "vault.unlock":
+        case "vault.status":
+        case "vault.config.set":
+        case "vault.config.status":
+        case "connect":
+        case "auth.run":
+        case "auth.verify":
+        case "auth.switch":
+        case "config.model":
+        case "config.models":
+        case "setup":
+        case "bluebubbles.replay":
+            return "throw";
+        default:
+            return undefined;
+    }
+}
+async function resolveMissingAgentName(deps, failureMode) {
+    const runtimeAgent = runtimeContextAgentName(deps);
+    if (runtimeAgent) {
+        return { ok: true, agent: runtimeAgent };
+    }
+    const discoveredAgents = normalizeCliAgentNames(await listCliAgents(deps));
+    if (discoveredAgents.length === 0) {
+        return { ok: false, message: noAgentsFoundMessage(), failureMode };
+    }
+    if (discoveredAgents.length === 1) {
+        return { ok: true, agent: discoveredAgents[0] };
+    }
+    if (!deps.promptInput) {
+        return { ok: false, message: multipleAgentsFoundMessage(discoveredAgents), failureMode };
+    }
+    const answer = await deps.promptInput([
+        "Which agent should this use?",
+        ...discoveredAgents.map((agent, index) => `${index + 1}. ${agent}`),
+        `Choose [1-${discoveredAgents.length}] or type a name: `,
+    ].join("\n"));
+    const selectedAgent = resolveSelectedCliAgent(answer, discoveredAgents);
+    if (!selectedAgent) {
+        return { ok: false, message: invalidAgentSelectionMessage(discoveredAgents), failureMode };
+    }
+    return { ok: true, agent: selectedAgent };
+}
+async function resolveCommandAgent(command, deps) {
+    const failureMode = agentResolutionFailureMode(command);
+    if (!failureMode) {
+        return { ok: true, command: command };
+    }
+    const explicitAgent = "agent" in command && typeof command.agent === "string" ? command.agent.trim() : "";
+    if (explicitAgent) {
+        return { ok: true, command: { ...command, agent: explicitAgent } };
+    }
+    const resolvedAgent = await resolveMissingAgentName(deps, failureMode);
+    if (!resolvedAgent.ok)
+        return resolvedAgent;
+    return { ok: true, command: { ...command, agent: resolvedAgent.agent } };
+}
 function managedAgentsSignature(agentNames) {
     const unique = [...new Set(agentNames.map((agent) => agent.trim()).filter((agent) => agent.length > 0))].sort();
     return unique.length > 0 ? unique.join(",") : "(none)";
@@ -203,12 +329,10 @@ async function runCommandProgressPhase(progress, label, run, detail) {
     }
 }
 function daemonProgressSummary(result) {
-    if (result.verifyStartupStatus === false)
-        return "not answering yet";
     if (result.alreadyRunning)
         return "already running";
-    if (result.message.includes("restarted"))
-        return "restarted and ready";
+    if (result.message.includes("replaced"))
+        return "replacement ready";
     return "ready";
 }
 async function reportPostRepairProviderHealth(deps, repairedAgents, onProgress) {
@@ -338,6 +462,7 @@ async function ensureDaemonRunning(deps, options = {}) {
             cleanupStaleSocket: deps.cleanupStaleSocket,
             startDaemonProcess: deps.startDaemonProcess,
             checkSocketAlive: deps.checkSocketAlive,
+            onProgress: deps.reportDaemonStartupPhase,
         });
         if (!runtimeResult.verifyStartupStatus) {
             return runtimeResult;
@@ -1500,7 +1625,7 @@ function enableAgentSense(agent, sense, deps) {
     };
     fs.writeFileSync(configPath, `${JSON.stringify(raw, null, 2)}\n`, "utf-8");
 }
-async function buildConnectMenu(agent, deps) {
+async function buildConnectMenu(agent, deps, onProgress) {
     const providerVisibility = (0, provider_visibility_1.buildAgentProviderVisibility)({
         agentName: agent,
         agentRoot: providerCliAgentRoot({ agent }, deps),
@@ -1516,7 +1641,9 @@ async function buildConnectMenu(agent, deps) {
     const providerDetail = providerVisibility.lanes.map((lane) => lane.status === "configured"
         ? `${lane.lane}: ${lane.provider} / ${lane.model}`
         : `${lane.lane}: choose provider/model`).join(" | ");
+    onProgress?.("loading portable settings");
     const runtimeConfig = await (0, runtime_credentials_1.refreshRuntimeCredentialConfig)(agent, { preserveCachedOnFailure: true });
+    onProgress?.("loading this machine's settings");
     const machineRuntime = await (0, runtime_credentials_1.refreshMachineRuntimeCredentialConfig)(agent, currentMachineId(deps), { preserveCachedOnFailure: true });
     const agentConfig = (0, auth_flow_1.readAgentConfigForAgent)(agent, deps.bundlesRoot).config;
     const teamsEnabled = agentConfig.senses?.teams?.enabled === true;
@@ -1825,7 +1952,14 @@ async function executeConnect(command, deps) {
         return executeConnectTeams(command.agent, deps);
     if (command.target === "bluebubbles")
         return executeConnectBlueBubbles(command.agent, deps);
-    const menu = await buildConnectMenu(command.agent, deps);
+    const progress = createHumanCommandProgress(deps, "connect");
+    let menu;
+    try {
+        menu = await runCommandProgressPhase(progress, "checking current connections", () => buildConnectMenu(command.agent, deps, (message) => progress.updateDetail(message)), () => "ready");
+    }
+    finally {
+        progress.end();
+    }
     const promptInput = deps.promptInput;
     if (!promptInput) {
         const message = [
@@ -2887,9 +3021,9 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         deps.writeStdout(text);
         return text;
     }
-    let command;
+    let parsedCommand;
     try {
-        command = (0, cli_parse_1.parseOuroCommand)(args);
+        parsedCommand = (0, cli_parse_1.parseOuroCommand)(args);
     }
     catch (parseError) {
         if (deps.startChat && deps.listDiscoveredAgents && args.length === 1) {
@@ -2902,6 +3036,15 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         }
         throw parseError;
     }
+    const resolvedCommand = await resolveCommandAgent(parsedCommand, deps);
+    if (!resolvedCommand.ok) {
+        if (resolvedCommand.failureMode === "return-message") {
+            deps.writeStdout(resolvedCommand.message);
+            return resolvedCommand.message;
+        }
+        throw new Error(resolvedCommand.message);
+    }
+    let command = resolvedCommand.command;
     if (args.length === 0) {
         const discovered = await Promise.resolve(deps.listDiscoveredAgents ? deps.listDiscoveredAgents() : (0, cli_defaults_1.defaultListDiscoveredAgents)());
         if (discovered.length === 0 && deps.runSerpentGuide) {
@@ -3213,12 +3356,14 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
                 progress.announceStep?.(label);
             },
         }, { initialAlive: daemonAliveBeforeStart });
-        progress.completePhase("starting daemon", daemonProgressSummary(daemonResult));
         if (daemonResult.verifyStartupStatus === false) {
+            ;
+            progress.announceStep?.("replacement daemon did not answer in time");
             progress.end();
             deps.writeStdout(daemonResult.message);
             return daemonResult.message;
         }
+        progress.completePhase("starting daemon", daemonProgressSummary(daemonResult));
         if (!providerChecksAlreadyRun || daemonResult.alreadyRunning) {
             progress.startPhase("provider checks");
             const providerDegraded = await checkAlreadyRunningAgentProviders(deps, (msg) => progress.updateDetail(msg));
@@ -3781,7 +3926,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         command.kind === "task.show" || command.kind === "task.actionable" || command.kind === "task.deps" ||
         command.kind === "task.sessions" || command.kind === "task.fix") {
         /* v8 ignore start -- production default: requires full identity setup @preserve */
-        const taskMod = deps.taskModule ?? (0, tasks_1.getTaskModule)();
+        const taskMod = deps.taskModule ?? (0, tasks_1.createTaskModule)(path.join(deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(), `${command.agent}.ouro`, "tasks"));
         /* v8 ignore stop */
         const message = executeTaskCommand(command, taskMod);
         deps.writeStdout(message);
@@ -3790,7 +3935,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     // ── reminder subcommands (local, no daemon socket needed) ──
     if (command.kind === "reminder.create") {
         /* v8 ignore start -- production default: requires full identity setup @preserve */
-        const taskMod = deps.taskModule ?? (0, tasks_1.getTaskModule)();
+        const taskMod = deps.taskModule ?? (0, tasks_1.createTaskModule)(path.join(deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(), `${command.agent}.ouro`, "tasks"));
         /* v8 ignore stop */
         const message = executeReminderCommand(command, taskMod);
         deps.writeStdout(message);
@@ -3800,8 +3945,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     if (command.kind === "habit.list" || command.kind === "habit.create") {
         const { parseHabitFile, renderHabitFile } = await Promise.resolve().then(() => __importStar(require("../habits/habit-parser")));
         /* v8 ignore start -- production default: uses real bundle root @preserve */
-        const agentName = command.agent ?? (0, identity_1.getAgentName)();
-        const bundleRoot = deps.agentBundleRoot ?? path.join((0, identity_1.getAgentBundlesRoot)(), `${agentName}.ouro`);
+        const bundleRoot = deps.agentBundleRoot ?? path.join(deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(), `${command.agent}.ouro`);
         /* v8 ignore stop */
         const habitsDir = path.join(bundleRoot, "habits");
         if (command.kind === "habit.list") {
@@ -3860,8 +4004,8 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             // Derive agent-scoped friends dir from --agent flag or link/unlink's agent field
             const agentName = ("agent" in command && command.agent) ? command.agent : undefined;
             const friendsDir = agentName
-                ? path.join((0, identity_1.getAgentBundlesRoot)(), `${agentName}.ouro`, "friends")
-                : path.join((0, identity_1.getAgentBundlesRoot)(), "friends");
+                ? path.join(deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(), `${agentName}.ouro`, "friends")
+                : path.join(deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(), "friends");
             store = new store_file_1.FileFriendStore(friendsDir);
         }
         /* v8 ignore stop */
@@ -4044,29 +4188,41 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             deps.writeStdout(message);
             return message;
         }
-        /* v8 ignore start -- production default: requires full identity setup @preserve */
         try {
-            const info = deps.whoamiInfo
-                ? deps.whoamiInfo()
-                : {
-                    agentName: (0, identity_1.getAgentName)(),
-                    homePath: path.join((0, identity_1.getAgentBundlesRoot)(), `${(0, identity_1.getAgentName)()}.ouro`),
-                    bonesVersion: (0, runtime_metadata_1.getRuntimeMetadata)().version,
-                };
+            if (deps.whoamiInfo) {
+                try {
+                    const info = deps.whoamiInfo();
+                    const message = [
+                        `agent: ${info.agentName}`,
+                        `home: ${info.homePath}`,
+                        `bones: ${info.bonesVersion}`,
+                    ].join("\n");
+                    deps.writeStdout(message);
+                    return message;
+                }
+                catch {
+                    // Fall through to shared agent selection when no runtime identity is available.
+                }
+            }
+            const resolvedAgent = await resolveMissingAgentName(deps, "return-message");
+            if (!resolvedAgent.ok) {
+                deps.writeStdout(resolvedAgent.message);
+                return resolvedAgent.message;
+            }
+            const agentRoot = path.join((0, identity_1.getAgentBundlesRoot)(), `${resolvedAgent.agent}.ouro`);
             const message = [
-                `agent: ${info.agentName}`,
-                `home: ${info.homePath}`,
-                `bones: ${info.bonesVersion}`,
+                `agent: ${resolvedAgent.agent}`,
+                `home: ${agentRoot}`,
+                `bones: ${(0, runtime_metadata_1.getRuntimeMetadata)().version}`,
             ].join("\n");
             deps.writeStdout(message);
             return message;
         }
         catch {
-            const message = "error: no agent context — use --agent <name> to specify";
+            const message = noAgentsFoundMessage();
             deps.writeStdout(message);
             return message;
         }
-        /* v8 ignore stop */
     }
     // ── changelog (local, no daemon socket needed) ──
     if (command.kind === "changelog") {
@@ -4110,10 +4266,9 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     // ── thoughts (local, no daemon socket needed) ──
     if (command.kind === "thoughts") {
         try {
-            const agentName = command.agent ?? (0, identity_1.getAgentName)();
             /* v8 ignore next -- production fallback: tests always inject bundlesRoot via createTmpBundle @preserve */
             const bundlesRoot = deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
-            const agentRoot = path.join(bundlesRoot, `${agentName}.ouro`);
+            const agentRoot = path.join(bundlesRoot, `${command.agent}.ouro`);
             const sessionFilePath = (0, thoughts_1.getInnerDialogSessionPath)(agentRoot);
             if (command.json) {
                 try {
@@ -4156,10 +4311,9 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     /* v8 ignore start -- CLI attention handler: requires real obligation store on disk @preserve */
     if (command.kind === "attention.list" || command.kind === "attention.show" || command.kind === "attention.history") {
         try {
-            const agentName = command.agent ?? (0, identity_1.getAgentName)();
             const { listActiveReturnObligations, readReturnObligation } = await Promise.resolve().then(() => __importStar(require("../../arc/obligations")));
             if (command.kind === "attention.list") {
-                const obligations = listActiveReturnObligations(agentName);
+                const obligations = listActiveReturnObligations(command.agent);
                 if (obligations.length === 0) {
                     const message = "nothing held — attention queue is empty";
                     deps.writeStdout(message);
@@ -4171,7 +4325,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
                 return message;
             }
             if (command.kind === "attention.show") {
-                const obligation = readReturnObligation(agentName, command.id);
+                const obligation = readReturnObligation(command.agent, command.id);
                 if (!obligation) {
                     const message = `no obligation found with id ${command.id}`;
                     deps.writeStdout(message);
@@ -4183,7 +4337,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             }
             // attention.history: show returned obligations
             const { getReturnObligationsDir } = await Promise.resolve().then(() => __importStar(require("../../arc/obligations")));
-            const obligationsDir = getReturnObligationsDir(agentName);
+            const obligationsDir = getReturnObligationsDir(command.agent);
             let attEntries = [];
             try {
                 attEntries = fs.readdirSync(obligationsDir);
@@ -4224,8 +4378,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     /* v8 ignore start -- inner status handler: requires real agent state on disk @preserve */
     if (command.kind === "inner.status") {
         try {
-            const agentName = command.agent ?? (0, identity_1.getAgentName)();
-            const agentRoot = (0, identity_1.getAgentRoot)(agentName);
+            const agentRoot = (0, identity_1.getAgentRoot)(command.agent);
             const { buildInnerStatusOutput } = await Promise.resolve().then(() => __importStar(require("./inner-status")));
             const { sessionPath: getSessionPath } = await Promise.resolve().then(() => __importStar(require("../config")));
             const { parseCadenceToMs: parseCadenceMs, DEFAULT_CADENCE_MS } = await Promise.resolve().then(() => __importStar(require("./cadence")));
@@ -4283,9 +4436,9 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             }
             catch { /* no habits — heartbeat unknown */ }
             // Attention count
-            const activeObligations = listActiveReturnObligations(agentName);
+            const activeObligations = listActiveReturnObligations(command.agent);
             const message = buildInnerStatusOutput({
-                agentName,
+                agentName: command.agent,
                 runtimeState,
                 journalFiles,
                 heartbeat,
@@ -4307,7 +4460,7 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         /* v8 ignore start -- production default: requires full identity setup @preserve */
         const scanner = deps.scanSessions ?? (async () => []);
         /* v8 ignore stop */
-        const sessions = await scanner();
+        const sessions = await scanner(command.agent);
         if (sessions.length === 0) {
             const message = "no active sessions";
             deps.writeStdout(message);

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

@@ -94,8 +94,8 @@ exports.COMMAND_REGISTRY = {
     config: {
         category: "Agents",
         description: "View or change agent configuration",
-        usage: "ouro config <subcommand> --agent <name>",
-        example: "ouro config models --agent ouroboros",
+        usage: "ouro config <subcommand> [--agent <name>]",
+        example: "ouro config models",
         subcommands: ["model", "models"],
     },
     changelog: {
@@ -159,27 +159,27 @@ exports.COMMAND_REGISTRY = {
     auth: {
         category: "Auth",
         description: "Set up, verify, or switch agent credentials",
-        usage: "ouro auth [verify|switch] --agent <name> [--provider <provider>]",
-        example: "ouro auth --agent ouroboros",
+        usage: "ouro auth [verify|switch] [--agent <name>] [--provider <provider>]",
+        example: "ouro auth",
         subcommands: ["verify", "switch"],
     },
     connect: {
         category: "Auth",
         description: "Connect providers, portable integrations, and local senses from one guided bay",
-        usage: "ouro connect [providers|perplexity|embeddings|teams|bluebubbles] --agent <name>",
-        example: "ouro connect --agent ouroboros",
+        usage: "ouro connect [providers|perplexity|embeddings|teams|bluebubbles] [--agent <name>]",
+        example: "ouro connect",
         subcommands: ["providers", "perplexity", "embeddings", "teams", "bluebubbles"],
     },
     use: {
         category: "Auth",
         description: "Choose this machine's provider/model lane for an agent",
-        usage: "ouro use --agent <name> --lane outward|inner --provider <provider> --model <model> [--force]",
+        usage: "ouro use [--agent <name>] --lane outward|inner --provider <provider> --model <model> [--force]",
         example: "ouro use --agent ouroboros --lane outward --provider minimax --model MiniMax-M2.5",
     },
     check: {
         category: "Auth",
         description: "Run a live check for this machine's selected provider/model lane",
-        usage: "ouro check --agent <name> --lane outward|inner",
+        usage: "ouro check [--agent <name>] --lane outward|inner",
         example: "ouro check --agent ouroboros --lane outward",
     },
     repair: {
@@ -191,15 +191,15 @@ exports.COMMAND_REGISTRY = {
     provider: {
         category: "Auth",
         description: "Refresh daemon provider credentials from an agent vault",
-        usage: "ouro provider refresh --agent <name>",
+        usage: "ouro provider refresh [--agent <name>]",
         example: "ouro provider refresh --agent ouroboros",
         subcommands: ["refresh"],
     },
     vault: {
         category: "Auth",
         description: "Create, replace, recover, unlock, inspect, and populate the agent credential vault",
-        usage: "ouro vault <create|replace|recover|unlock|status|config> --agent <name>",
-        example: "ouro vault status --agent ouroboros",
+        usage: "ouro vault <create|replace|recover|unlock|status|config> [--agent <name>]",
+        example: "ouro vault status",
         subcommands: ["create", "replace", "recover", "unlock", "status", "config set", "config status"],
     },
     thoughts: {
@@ -244,8 +244,8 @@ exports.COMMAND_REGISTRY = {
     setup: {
         category: "System",
         description: "Register MCP server and hooks for a dev tool",
-        usage: "ouro setup --tool <claude-code|codex> --agent <name>",
-        example: "ouro setup --tool claude-code --agent ouroboros",
+        usage: "ouro setup --tool <claude-code|codex> [--agent <name>]",
+        example: "ouro setup --tool claude-code",
     },
     hook: {
         category: "System",
@@ -256,86 +256,86 @@ exports.COMMAND_REGISTRY = {
     bluebubbles: {
         category: "System",
         description: "BlueBubbles integration commands",
-        usage: "ouro bluebubbles replay --agent <name> --message-guid <guid> [--event-type <type>] [--json]",
-        example: "ouro bluebubbles replay --agent ouroboros --message-guid abc123",
+        usage: "ouro bluebubbles replay [--agent <name>] --message-guid <guid> [--event-type <type>] [--json]",
+        example: "ouro bluebubbles replay --message-guid abc123",
         subcommands: ["replay"],
     },
 };
 const SUBCOMMAND_HELP = {
     "auth verify": {
         description: "Verify agent provider credentials without changing provider/model lanes",
-        usage: "ouro auth verify --agent <name> [--provider <provider>]",
-        example: "ouro auth verify --agent ouroboros --provider openai-codex",
+        usage: "ouro auth verify [--agent <name>] [--provider <provider>]",
+        example: "ouro auth verify --provider openai-codex",
     },
     "auth switch": {
         description: "Switch local provider/model lanes after credentials are available",
-        usage: "ouro auth switch --agent <name> --provider <provider> [--facing human|agent]",
-        example: "ouro auth switch --agent ouroboros --provider minimax",
+        usage: "ouro auth switch [--agent <name>] --provider <provider> [--facing human|agent]",
+        example: "ouro auth switch --provider minimax",
     },
     "connect perplexity": {
         description: "Connect Perplexity search for this agent",
-        usage: "ouro connect perplexity --agent <name>",
-        example: "ouro connect perplexity --agent ouroboros",
+        usage: "ouro connect perplexity [--agent <name>]",
+        example: "ouro connect perplexity",
     },
     "connect providers": {
         description: "Open provider auth from the connect bay without remembering the auth command",
-        usage: "ouro connect providers --agent <name>",
-        example: "ouro connect providers --agent ouroboros",
+        usage: "ouro connect providers [--agent <name>]",
+        example: "ouro connect providers",
     },
     "connect embeddings": {
         description: "Connect memory embeddings for this agent",
-        usage: "ouro connect embeddings --agent <name>",
-        example: "ouro connect embeddings --agent ouroboros",
+        usage: "ouro connect embeddings [--agent <name>]",
+        example: "ouro connect embeddings",
     },
     "connect teams": {
         description: "Connect Microsoft Teams credentials and enable the Teams sense",
-        usage: "ouro connect teams --agent <name>",
-        example: "ouro connect teams --agent ouroboros",
+        usage: "ouro connect teams [--agent <name>]",
+        example: "ouro connect teams",
     },
     "connect bluebubbles": {
         description: "Attach BlueBubbles iMessage to this machine only",
-        usage: "ouro connect bluebubbles --agent <name>",
-        example: "ouro connect bluebubbles --agent ouroboros",
+        usage: "ouro connect bluebubbles [--agent <name>]",
+        example: "ouro connect bluebubbles",
     },
     "provider refresh": {
         description: "Reload this agent's provider credentials from its vault into daemon memory",
-        usage: "ouro provider refresh --agent <name>",
-        example: "ouro provider refresh --agent ouroboros",
+        usage: "ouro provider refresh [--agent <name>]",
+        example: "ouro provider refresh",
     },
     "vault create": {
         description: "Create an agent credential vault and store local unlock material",
-        usage: "ouro vault create --agent <name> --email <email> [--server <url>] [--store <store>]",
-        example: "ouro vault create --agent ouroboros --email ouroboros@ouro.bot",
+        usage: "ouro vault create [--agent <name>] --email <email> [--server <url>] [--store <store>]",
+        example: "ouro vault create --email ouroboros@ouro.bot",
     },
     "vault replace": {
         description: "Create an empty agent vault at the stable agent email when no unlock secret or JSON export exists",
-        usage: "ouro vault replace --agent <name> [--email <email>] [--server <url>] [--store <store>]",
-        example: "ouro vault replace --agent ouroboros",
+        usage: "ouro vault replace [--agent <name>] [--email <email>] [--server <url>] [--store <store>]",
+        example: "ouro vault replace",
     },
     "vault recover": {
         description: "Create an agent vault at the stable agent email and import local JSON credential exports",
-        usage: "ouro vault recover --agent <name> --from <json> [--from <json> ...] [--email <email>] [--server <url>] [--store <store>]",
-        example: "ouro vault recover --agent ouroboros --from ./credentials.json",
+        usage: "ouro vault recover [--agent <name>] --from <json> [--from <json> ...] [--email <email>] [--server <url>] [--store <store>]",
+        example: "ouro vault recover --from ./credentials.json",
     },
     "vault unlock": {
         description: "Unlock an existing agent credential vault on this machine",
-        usage: "ouro vault unlock --agent <name> [--store <store>]",
-        example: "ouro vault unlock --agent ouroboros",
+        usage: "ouro vault unlock [--agent <name>] [--store <store>]",
+        example: "ouro vault unlock",
     },
     "vault status": {
         description: "Show whether this machine can unlock an agent credential vault",
-        usage: "ouro vault status --agent <name> [--store <store>]",
-        example: "ouro vault status --agent ouroboros",
+        usage: "ouro vault status [--agent <name>] [--store <store>]",
+        example: "ouro vault status",
     },
     "vault config set": {
         description: "Write runtime configuration into the agent credential vault without printing values",
-        usage: "ouro vault config set --agent <name> --key <path> [--value <value>] [--scope agent|machine]",
-        example: "ouro vault config set --agent ouroboros --key teams.clientSecret",
+        usage: "ouro vault config set [--agent <name>] --key <path> [--value <value>] [--scope agent|machine]",
+        example: "ouro vault config set --key teams.clientSecret",
     },
     "vault config status": {
         description: "List runtime configuration keys stored in the agent credential vault",
-        usage: "ouro vault config status --agent <name> [--scope agent|machine|all]",
-        example: "ouro vault config status --agent ouroboros --scope all",
+        usage: "ouro vault config status [--agent <name>] [--scope agent|machine|all]",
+        example: "ouro vault config status --scope all",
     },
 };
 // ── Levenshtein distance ──

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

@@ -74,25 +74,25 @@ function usage() {
         "  ouro dev [--repo-path <path>] [--clone [--clone-path <path>]]",
         "  ouro stop|down|status|logs|hatch",
         "  ouro status --agent <name>",
-        "  ouro use --agent <name> --lane outward|inner --provider <provider> --model <model> [--force]",
-        "  ouro check --agent <name> --lane outward|inner",
+        "  ouro use [--agent <name>] --lane outward|inner --provider <provider> --model <model> [--force]",
+        "  ouro check [--agent <name>] --lane outward|inner",
         "  ouro repair [--agent <name>]",
-        "  ouro provider refresh --agent <name>",
+        "  ouro provider refresh [--agent <name>]",
         "  ouro outlook [--json]",
         "  ouro -v|--version",
-        "  ouro config model --agent <name> <model-name>",
-        "  ouro config models --agent <name>",
-        "  ouro auth --agent <name> [--provider <provider>]",
-        "  ouro connect [providers|perplexity|embeddings|teams|bluebubbles] --agent <name>",
-        "  ouro auth verify --agent <name> [--provider <provider>]",
-        "  ouro auth switch --agent <name> --provider <provider>",
-        "  ouro vault create --agent <name> --email <email> [--server <url>] [--store <store>]",
-        "  ouro vault replace --agent <name> [--email <email>] [--server <url>] [--store <store>]",
-        "  ouro vault recover --agent <name> --from <json> [--from <json>] [--email <email>] [--server <url>] [--store <store>]",
-        "  ouro vault unlock --agent <name> [--store auto|macos-keychain|windows-dpapi|linux-secret-service|plaintext-file]",
-        "  ouro vault status --agent <name> [--store auto|macos-keychain|windows-dpapi|linux-secret-service|plaintext-file]",
-        "  ouro vault config set --agent <name> --key <path> [--value <value>] [--scope agent|machine]",
-        "  ouro vault config status --agent <name> [--scope agent|machine|all]",
+        "  ouro config model [--agent <name>] <model-name>",
+        "  ouro config models [--agent <name>]",
+        "  ouro auth [--agent <name>] [--provider <provider>]",
+        "  ouro connect [providers|perplexity|embeddings|teams|bluebubbles] [--agent <name>]",
+        "  ouro auth verify [--agent <name>] [--provider <provider>]",
+        "  ouro auth switch [--agent <name>] --provider <provider>",
+        "  ouro vault create [--agent <name>] --email <email> [--server <url>] [--store <store>]",
+        "  ouro vault replace [--agent <name>] [--email <email>] [--server <url>] [--store <store>]",
+        "  ouro vault recover [--agent <name>] --from <json> [--from <json>] [--email <email>] [--server <url>] [--store <store>]",
+        "  ouro vault unlock [--agent <name>] [--store auto|macos-keychain|windows-dpapi|linux-secret-service|plaintext-file]",
+        "  ouro vault status [--agent <name>] [--store auto|macos-keychain|windows-dpapi|linux-secret-service|plaintext-file]",
+        "  ouro vault config set [--agent <name>] --key <path> [--value <value>] [--scope agent|machine]",
+        "  ouro vault config status [--agent <name>] [--scope agent|machine|all]",
         "  ouro chat <agent>",
         "  ouro msg --to <agent> [--session <id>] [--task <ref>] <message>",
         "  ouro poke <agent> --task <task-id>",
@@ -100,7 +100,7 @@ function usage() {
         "  ouro habit list [--agent <name>]",
         "  ouro habit create [--agent <name>] <name> [--cadence <interval>]",
         "  ouro link <agent> --friend <id> --provider <provider> --external-id <external-id>",
-        "  ouro bluebubbles replay --agent <name> --message-guid <guid> [--event-type new-message|updated-message] [--json]",
+        "  ouro bluebubbles replay [--agent <name>] --message-guid <guid> [--event-type new-message|updated-message] [--json]",
         "  ouro task board [<status>] [--agent <name>]",
         "  ouro task create <title> [--type <type>] [--agent <name>]",
         "  ouro task update <id> <status> [--agent <name>]",
@@ -415,15 +415,21 @@ function parseAuthCommand(args) {
             }
         }
         /* v8 ignore stop */
-        /* v8 ignore next -- defensive: agent always provided in tests @preserve */
-        if (!agent)
-            throw new Error(`Usage\n${usage()}`);
         if (subcommand === "switch") {
             if (!provider)
                 throw new Error(`auth switch requires --provider.\n${usage()}`);
-            return facing ? { kind: "auth.switch", agent, provider, facing } : { kind: "auth.switch", agent, provider };
+            return {
+                kind: "auth.switch",
+                ...(agent ? { agent } : {}),
+                provider,
+                ...(facing ? { facing } : {}),
+            };
         }
-        return provider ? { kind: "auth.verify", agent, provider } : { kind: "auth.verify", agent };
+        return {
+            kind: "auth.verify",
+            ...(agent ? { agent } : {}),
+            ...(provider ? { provider } : {}),
+        };
     }
     const { agent, rest } = extractAgentFlag(args);
     let provider;
@@ -437,15 +443,11 @@ function parseAuthCommand(args) {
             continue;
         }
     }
-    if (!agent) {
-        throw new Error([
-            "Usage:",
-            "  ouro auth --agent <name> [--provider <provider>]     Set up credentials",
-            "  ouro auth verify --agent <name> [--provider <p>]     Verify credentials work",
-            "  ouro auth switch --agent <name> --provider <p>       Switch active provider",
-        ].join("\n"));
-    }
-    return provider ? { kind: "auth.run", agent, provider } : { kind: "auth.run", agent };
+    return {
+        kind: "auth.run",
+        ...(agent ? { agent } : {}),
+        ...(provider ? { provider } : {}),
+    };
 }
 function isVaultUnlockStoreKind(value) {
     return value === "auto" || value === "macos-keychain" || value === "windows-dpapi" || value === "linux-secret-service" || value === "plaintext-file";
@@ -487,7 +489,7 @@ function parseVaultCommand(args) {
             }
             const value = rest[i + 1];
             if (!value)
-                throw new Error("Usage: ouro vault recover --agent <name> --from <json> [--from <json> ...]");
+                throw new Error("Usage: ouro vault recover [--agent <name>] --from <json> [--from <json> ...]");
             sources.push(value);
             i += 1;
             continue;
@@ -496,15 +498,15 @@ function parseVaultCommand(args) {
             generateUnlockSecret = true;
             continue;
         }
-        throw new Error("Usage: ouro vault create|replace|recover|unlock|status --agent <name>");
+        throw new Error("Usage: ouro vault create|replace|recover|unlock|status [--agent <name>]");
     }
-    if (!agent || (sub !== "create" && sub !== "replace" && sub !== "recover" && sub !== "unlock" && sub !== "status")) {
-        throw new Error("Usage: ouro vault create|replace|recover|unlock|status --agent <name>");
+    if (sub !== "create" && sub !== "replace" && sub !== "recover" && sub !== "unlock" && sub !== "status") {
+        throw new Error("Usage: ouro vault create|replace|recover|unlock|status [--agent <name>]");
     }
     if (sub === "create") {
         return {
             kind: "vault.create",
-            agent,
+            ...(agent ? { agent } : {}),
             ...(email ? { email } : {}),
             ...(serverUrl ? { serverUrl } : {}),
             ...(store ? { store } : {}),
@@ -514,7 +516,7 @@ function parseVaultCommand(args) {
     if (sub === "replace") {
         return {
             kind: "vault.replace",
-            agent,
+            ...(agent ? { agent } : {}),
             ...(email ? { email } : {}),
             ...(serverUrl ? { serverUrl } : {}),
             ...(store ? { store } : {}),
@@ -523,11 +525,11 @@ function parseVaultCommand(args) {
     }
     if (sub === "recover") {
         if (sources.length === 0) {
-            throw new Error("Usage: ouro vault recover --agent <name> --from <json> [--from <json> ...]");
+            throw new Error("Usage: ouro vault recover [--agent <name>] --from <json> [--from <json> ...]");
         }
         return {
             kind: "vault.recover",
-            agent,
+            ...(agent ? { agent } : {}),
             sources,
             ...(email ? { email } : {}),
             ...(serverUrl ? { serverUrl } : {}),
@@ -536,9 +538,9 @@ function parseVaultCommand(args) {
         };
     }
     if (sub === "unlock") {
-        return { kind: "vault.unlock", agent, ...(store ? { store } : {}) };
+        return { kind: "vault.unlock", ...(agent ? { agent } : {}), ...(store ? { store } : {}) };
     }
-    return { kind: "vault.status", agent, ...(store ? { store } : {}) };
+    return { kind: "vault.status", ...(agent ? { agent } : {}), ...(store ? { store } : {}) };
 }
 function parseVaultConfigCommand(args) {
     const sub = args[0];
@@ -567,23 +569,23 @@ function parseVaultConfigCommand(args) {
             i += 1;
             continue;
         }
-        throw new Error("Usage: ouro vault config set --agent <name> --key <path> [--value <value>] OR ouro vault config status --agent <name>");
+        throw new Error("Usage: ouro vault config set [--agent <name>] --key <path> [--value <value>] OR ouro vault config status [--agent <name>]");
     }
-    if (!agent || (sub !== "set" && sub !== "status")) {
-        throw new Error("Usage: ouro vault config set --agent <name> --key <path> [--value <value>] OR ouro vault config status --agent <name>");
+    if (sub !== "set" && sub !== "status") {
+        throw new Error("Usage: ouro vault config set [--agent <name>] --key <path> [--value <value>] OR ouro vault config status [--agent <name>]");
     }
     if (sub === "status") {
         if (key || value) {
-            throw new Error("Usage: ouro vault config status --agent <name>");
+            throw new Error("Usage: ouro vault config status [--agent <name>]");
         }
-        return { kind: "vault.config.status", agent, ...(scope ? { scope } : {}) };
+        return { kind: "vault.config.status", ...(agent ? { agent } : {}), ...(scope ? { scope } : {}) };
     }
     if (scope === "all")
         throw new Error("vault config --scope all is only valid for status");
     if (!key) {
-        throw new Error("Usage: ouro vault config set --agent <name> --key <path> [--value <value>]");
+        throw new Error("Usage: ouro vault config set [--agent <name>] --key <path> [--value <value>]");
     }
-    return { kind: "vault.config.set", agent, key, ...(value !== undefined ? { value } : {}), ...(scope ? { scope } : {}) };
+    return { kind: "vault.config.set", ...(agent ? { agent } : {}), key, ...(value !== undefined ? { value } : {}), ...(scope ? { scope } : {}) };
 }
 function normalizeConnectTarget(value) {
     if (!value)
@@ -598,16 +600,14 @@ function normalizeConnectTarget(value) {
         return "teams";
     if (value === "bluebubbles" || value === "imessage" || value === "messages")
         return "bluebubbles";
-    throw new Error("Usage: ouro connect [providers|perplexity|embeddings|teams|bluebubbles] --agent <name>");
+    throw new Error("Usage: ouro connect [providers|perplexity|embeddings|teams|bluebubbles] [--agent <name>]");
 }
 function parseConnectCommand(args) {
     const { agent, rest } = extractAgentFlag(args);
-    if (!agent)
-        throw new Error("Usage: ouro connect --agent <name> [providers|perplexity|embeddings|teams|bluebubbles]");
     if (rest.length > 1)
-        throw new Error("Usage: ouro connect [providers|perplexity|embeddings|teams|bluebubbles] --agent <name>");
+        throw new Error("Usage: ouro connect [providers|perplexity|embeddings|teams|bluebubbles] [--agent <name>]");
     const target = normalizeConnectTarget(rest[0]);
-    return { kind: "connect", agent, ...(target ? { target } : {}) };
+    return { kind: "connect", ...(agent ? { agent } : {}), ...(target ? { target } : {}) };
 }
 function parseProviderUseCommand(args) {
     const { agent, rest: afterAgent } = extractAgentFlag(args);
@@ -621,7 +621,7 @@ function parseProviderUseCommand(args) {
         if (token === "--provider") {
             const value = rest[i + 1];
             if (!isAgentProvider(value))
-                throw new Error(`Usage: ouro use --agent <name> --lane outward|inner --provider <provider> --model <model>`);
+                throw new Error("Usage: ouro use [--agent <name>] --lane outward|inner --provider <provider> --model <model>");
             provider = value;
             i += 1;
             continue;
@@ -635,15 +635,15 @@ function parseProviderUseCommand(args) {
             force = true;
             continue;
         }
-        throw new Error("Usage: ouro use --agent <name> --lane outward|inner --provider <provider> --model <model> [--force]");
+        throw new Error("Usage: ouro use [--agent <name>] --lane outward|inner --provider <provider> --model <model> [--force]");
     }
     const resolvedLane = lane ?? (facing ? facingToProviderLane(facing) : undefined);
-    if (!agent || !resolvedLane || !provider || !model) {
-        throw new Error("Usage: ouro use --agent <name> --lane outward|inner --provider <provider> --model <model> [--force]");
+    if (!resolvedLane || !provider || !model) {
+        throw new Error("Usage: ouro use [--agent <name>] --lane outward|inner --provider <provider> --model <model> [--force]");
     }
     return {
         kind: "provider.use",
-        agent,
+        ...(agent ? { agent } : {}),
         lane: resolvedLane,
         provider,
         model,
@@ -656,12 +656,12 @@ function parseProviderCheckCommand(args) {
     const { facing, rest: afterFacing } = extractFacingFlag(afterAgent);
     const { lane, rest } = extractLaneFlag(afterFacing);
     const resolvedLane = lane ?? (facing ? facingToProviderLane(facing) : undefined);
-    if (!agent || !resolvedLane || rest.length > 0) {
-        throw new Error("Usage: ouro check --agent <name> --lane outward|inner");
+    if (!resolvedLane || rest.length > 0) {
+        throw new Error("Usage: ouro check [--agent <name>] --lane outward|inner");
     }
     return {
         kind: "provider.check",
-        agent,
+        ...(agent ? { agent } : {}),
         lane: resolvedLane,
         ...(facing ? { legacyFacing: facing } : {}),
     };
@@ -669,10 +669,10 @@ function parseProviderCheckCommand(args) {
 function parseProviderCommand(args) {
     const sub = args[0];
     const { agent, rest } = extractAgentFlag(args.slice(1));
-    if (sub === "refresh" && agent && rest.length === 0) {
-        return { kind: "provider.refresh", agent };
+    if (sub === "refresh" && rest.length === 0) {
+        return { kind: "provider.refresh", ...(agent ? { agent } : {}) };
     }
-    throw new Error("Usage: ouro provider refresh --agent <name>");
+    throw new Error("Usage: ouro provider refresh [--agent <name>]");
 }
 function parseReminderCommand(args) {
     const { agent, rest: cleaned } = extractAgentFlag(args);
@@ -836,17 +836,18 @@ function parseConfigCommand(args) {
     if (!sub)
         throw new Error(`Usage\n${usage()}`);
     if (sub === "model") {
-        if (!agent)
-            throw new Error("--agent is required for config model");
         const modelName = rest[0];
         if (!modelName)
-            throw new Error(`Usage: ouro config model --agent <name> <model-name>`);
-        return facing ? { kind: "config.model", agent, modelName, facing } : { kind: "config.model", agent, modelName };
+            throw new Error("Usage: ouro config model [--agent <name>] <model-name>");
+        return {
+            kind: "config.model",
+            ...(agent ? { agent } : {}),
+            modelName,
+            ...(facing ? { facing } : {}),
+        };
     }
     if (sub === "models") {
-        if (!agent)
-            throw new Error("--agent is required for config models");
-        return { kind: "config.models", agent };
+        return { kind: "config.models", ...(agent ? { agent } : {}) };
     }
     throw new Error(`Usage\n${usage()}`);
 }
@@ -937,13 +938,13 @@ function parseSetupCommand(args) {
             continue;
         }
     }
+    if (args.includes("--agent") && !agent)
+        throw new Error("setup requires --agent <name>");
     if (!tool)
         throw new Error("setup requires --tool (claude-code | codex)");
     if (tool !== "claude-code" && tool !== "codex")
         throw new Error(`Unknown tool: ${tool}. Supported: claude-code, codex`);
-    if (!agent)
-        throw new Error("setup requires --agent <name>");
-    return { kind: "setup", tool, agent };
+    return { kind: "setup", tool, ...(agent ? { agent } : {}) };
 }
 function parseBlueBubblesCommand(args) {
     const subcommand = args[0];
@@ -976,13 +977,11 @@ function parseBlueBubblesCommand(args) {
             continue;
         }
     }
-    if (!agent)
-        throw new Error("bluebubbles replay requires --agent <name>");
     if (!messageGuid)
         throw new Error("bluebubbles replay requires --message-guid <guid>");
     return {
         kind: "bluebubbles.replay",
-        agent,
+        ...(agent ? { agent } : {}),
         messageGuid,
         eventType,
         ...(json ? { json: true } : {}),

package/dist/heart/daemon/daemon-runtime-sync.js

@@ -9,6 +9,7 @@ async function verifyDaemonStarted(deps) {
     const maxWaitMs = 10_000;
     const pollIntervalMs = 500;
     const deadline = Date.now() + maxWaitMs;
+    deps.onProgress?.("waiting for the replacement daemon to answer");
     while (Date.now() < deadline) {
         await new Promise((r) => setTimeout(r, pollIntervalMs));
         if (await deps.checkSocketAlive(deps.socketPath))
@@ -102,7 +103,9 @@ async function ensureCurrentDaemonRuntime(deps) {
         if (driftReasons.length > 0) {
             const includesVersionDrift = driftReasons.some((entry) => entry.key === "version");
             const publicDriftSummary = formatRuntimeDriftPublicSummary(driftReasons);
+            deps.onProgress?.("preparing a replacement for the running background service");
             try {
+                deps.onProgress?.("stopping the running background service");
                 await deps.stopDaemon();
             }
             catch (error) {
@@ -110,8 +113,8 @@ async function ensureCurrentDaemonRuntime(deps) {
                 result = {
                     alreadyRunning: true,
                     message: includesVersionDrift
-                        ? `daemon already running (${deps.socketPath}; could not replace stale daemon ${runningVersion} -> ${deps.localVersion}: ${reason})`
-                        : `daemon already running (${deps.socketPath}; could not replace runtime drift ${publicDriftSummary}: ${reason})`,
+                        ? `daemon already running (${deps.socketPath}; could not replace the running background service ${runningVersion} -> ${deps.localVersion}: ${reason})`
+                        : `daemon already running (${deps.socketPath}; could not replace the running background service after runtime drift ${publicDriftSummary}: ${reason})`,
                 };
                 (0, runtime_1.emitNervesEvent)({
                     level: "warn",
@@ -138,16 +141,17 @@ async function ensureCurrentDaemonRuntime(deps) {
                 return result;
             }
             deps.cleanupStaleSocket(deps.socketPath);
+            deps.onProgress?.("starting the replacement background service");
             const started = await deps.startDaemonProcess(deps.socketPath);
             const pid = started.pid ?? "unknown";
             const verified = await verifyDaemonStarted(deps);
             /* v8 ignore next -- daemon liveness failure: requires real daemon crash timing @preserve */
-            const suffix = verified ? "" : "\ndaemon restart has not answered yet; check logs with `ouro logs` or run `ouro doctor`.";
+            const suffix = verified ? "" : "\nreplacement daemon did not answer in time; check logs with `ouro logs` or run `ouro doctor`.";
             result = {
                 alreadyRunning: false,
                 message: includesVersionDrift
-                    ? `restarted stale daemon ${runningVersion} -> ${deps.localVersion} (pid ${pid})${suffix}`
-                    : `restarted daemon after runtime drift: ${publicDriftSummary} (pid ${pid})${suffix}`,
+                    ? `replaced the running background service ${runningVersion} -> ${deps.localVersion} (pid ${pid})${suffix}`
+                    : `replaced the running background service after runtime drift: ${publicDriftSummary} (pid ${pid})${suffix}`,
                 verifyStartupStatus: verified,
                 startedPid: started.pid ?? null,
             };

package/dist/repertoire/tasks/index.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTaskModule = createTaskModule;
 exports.getTaskModule = getTaskModule;
 exports.resetTaskModule = resetTaskModule;
 const fs = __importStar(require("fs"));
@@ -67,8 +68,12 @@ function removeRuntimeFrontmatter(frontmatter) {
     return clean;
 }
 class FileTaskModule {
+    root;
+    constructor(root = (0, scanner_1.getTaskRoot)()) {
+        this.root = root;
+    }
     scan() {
-        return (0, scanner_1.scanTasks)((0, scanner_1.getTaskRoot)());
+        return (0, scanner_1.scanTasks)(this.root);
     }
     getBoard() {
         return (0, board_1.buildTaskBoard)(this.scan());
@@ -94,7 +99,7 @@ class FileTaskModule {
         const collection = (0, transitions_1.canonicalCollectionForTaskType)(type);
         const stem = `${formatStemTimestamp()}-${(0, config_1.slugify)(input.title).slice(0, 64) || "task"}`;
         const filename = `${stem}.md`;
-        const root = (0, scanner_1.getTaskRoot)();
+        const root = this.root;
         const filePath = path.join(root, collection, filename);
         const today = formatDate();
         const frontmatter = {
@@ -194,7 +199,7 @@ class FileTaskModule {
         return (0, middleware_1.validateSpawn)(task, spawnType);
     }
     fix(options) {
-        return (0, fix_1.applyFixes)(options, (0, scanner_1.getTaskRoot)());
+        return (0, fix_1.applyFixes)(options, this.root);
     }
     detectStale(thresholdDays) {
         return (0, lifecycle_1.detectStaleTasks)(this.scan(), thresholdDays);
@@ -216,9 +221,12 @@ class FileTaskModule {
     }
 }
 let taskModule = null;
+function createTaskModule(root = (0, scanner_1.getTaskRoot)()) {
+    return new FileTaskModule(root);
+}
 function getTaskModule() {
     if (!taskModule) {
-        taskModule = new FileTaskModule();
+        taskModule = createTaskModule();
     }
     return taskModule;
 }

package/package.json

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