@ouro.bot/cli 0.1.0-alpha.664 → 0.1.0-alpha.666

package/dist/heart/core.js

@@ -6,6 +6,7 @@ exports.getModel = getModel;
 exports.getProvider = getProvider;
 exports.createSummarize = createSummarize;
 exports.getProviderDisplayLabel = getProviderDisplayLabel;
+exports.createHabitCallbackBuffer = createHabitCallbackBuffer;
 exports.isChatStyleChannel = isChatStyleChannel;
 exports.buildPonderResult = buildPonderResult;
 exports.isExternalStateQuery = isExternalStateQuery;
@@ -36,6 +37,7 @@ const packets_1 = require("../arc/packets");
 const tool_friction_1 = require("./tool-friction");
 const provider_models_1 = require("./provider-models");
 const provider_credentials_1 = require("./provider-credentials");
+const habit_session_1 = require("./habits/habit-session");
 const provider_attempt_1 = require("./provider-attempt");
 const openai_codex_token_1 = require("./providers/openai-codex-token");
 const _providerRuntimes = {
@@ -185,6 +187,43 @@ function getProviderDisplayLabel(facing = "human") {
     };
     return providerLabelBuilders[provider]();
 }
+function createHabitCallbackBuffer(callbacks) {
+    const events = [];
+    return {
+        callbacks: {
+            ...callbacks,
+            onModelStreamStart: () => { events.push({ kind: "stream-start" }); },
+            onTextChunk: (text) => { events.push({ kind: "text", text }); },
+            onReasoningChunk: (text) => { events.push({ kind: "reasoning", text }); },
+            onClearText: () => { events.push({ kind: "clear" }); },
+            flushNow: () => { events.push({ kind: "flush" }); },
+        },
+        async flush() {
+            for (const event of events.splice(0)) {
+                switch (event.kind) {
+                    case "stream-start":
+                        callbacks.onModelStreamStart();
+                        break;
+                    case "text":
+                        callbacks.onTextChunk(event.text);
+                        break;
+                    case "reasoning":
+                        callbacks.onReasoningChunk(event.text);
+                        break;
+                    case "clear":
+                        callbacks.onClearText?.();
+                        break;
+                    case "flush":
+                        await callbacks.flushNow?.();
+                        break;
+                }
+            }
+        },
+        discard() {
+            events.splice(0);
+        },
+    };
+}
 /**
  * Strip <think>...</think> blocks for the violation-detection check at the
  * end of a streaming turn. Used to tell legitimate text-only responses
@@ -215,6 +254,85 @@ function hasFreshPendingWork(options) {
     return pendingMessages.some((message) => typeof message?.content === "string"
         && message.content.trim().length > 0);
 }
+const HABIT_CONTROL_TOOLS = new Set(["rest", "ponder", "observe"]);
+function habitToolArgs(call) {
+    try {
+        const parsed = JSON.parse(call.arguments);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { ok: false, reason: `habit tool '${call.name}' arguments must be a JSON object` };
+        }
+        return { ok: true, args: parsed };
+    }
+    catch {
+        return { ok: false, reason: `habit tool '${call.name}' has malformed JSON arguments` };
+    }
+}
+function highRiskExternalMutation(profile) {
+    if (profile.risk !== "high")
+        return null;
+    const mutates = typeof profile.mutates === "string" ? [profile.mutates] : [...profile.mutates];
+    return mutates.includes("external_side_effect") ? mutates.join(", ") : null;
+}
+function recordBlockedHabitSurfaceAttempts(habitSession, toolCalls, reason) {
+    if (toolCalls.some((call) => call.name !== "send_message" && call.name !== "surface")) {
+        habitSession?.recordError?.(`blocked habit tool batch: ${reason}`);
+    }
+    if (!habitSession?.recordSurfaceAttempt)
+        return;
+    for (const call of toolCalls) {
+        if (call.name !== "send_message" && call.name !== "surface")
+            continue;
+        const parsed = habitToolArgs(call);
+        const args = parsed.ok ? parsed.args : {};
+        habitSession.recordSurfaceAttempt({
+            recipient: String(args.friendId ?? args.delegationId ?? "unknown"),
+            channel: String(args.channel ?? call.name),
+            reason: "blocked",
+            result: "blocked",
+            rawStatus: "blocked",
+            error: reason,
+        });
+    }
+}
+async function habitToolBatchBlockReason(habitSession, toolCalls, delegatedOrigins, activeToolNames) {
+    if (!habitSession)
+        return null;
+    const granted = new Set(habitSession.toolPolicy.grantedTools);
+    const denied = new Set(habitSession.toolPolicy.deniedTools);
+    for (const call of toolCalls) {
+        if (denied.has(call.name))
+            return `habit tool '${call.name}' is denied by this habit session`;
+        if (!activeToolNames.has(call.name))
+            return `habit tool '${call.name}' was not advertised to this model turn`;
+        if (HABIT_CONTROL_TOOLS.has(call.name))
+            continue;
+        if (!granted.has(call.name))
+            return `habit tool '${call.name}' was not granted to this habit session`;
+        const parsed = habitToolArgs(call);
+        if (!parsed.ok)
+            return parsed.reason;
+        const riskProfile = (0, tools_1.riskProfileForToolName)(call.name, parsed.args);
+        if (!riskProfile)
+            return `habit tool '${call.name}' does not have a known executable risk profile`;
+        const externalMutation = highRiskExternalMutation(riskProfile);
+        if (externalMutation && call.name !== "send_message" && call.name !== "surface") {
+            return `habit tool '${call.name}' has high-risk executable mutation ${externalMutation}: ${riskProfile.reason}`;
+        }
+        if (call.name === "send_message" || call.name === "surface") {
+            const route = await (0, habit_session_1.resolveHabitReturnRoute)({
+                agentRoot: (0, identity_2.getAgentRoot)(),
+                envelope: habitSession.permissionEnvelope,
+                toolName: call.name,
+                args: parsed.args,
+                friendStore: habitSession.friendStore,
+                delegatedOrigins,
+            });
+            if (!route.allowed)
+                return route.reason;
+        }
+    }
+    return null;
+}
 /** Chat-style channels expose the `speak` tool — outer human-conversation channels
  *  where mid-turn delivery is meaningful. Inner dialog has `ponder`. MCP returns
  *  synchronously. Mail is batch. Anything else (unknown channel) treats as non-chat. */
@@ -744,6 +862,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
     // Augment tool context with reasoning effort controls from provider
     const baseToolContext = options?.toolContext
         ?? (options?.orientationFrame ? { signin: async () => undefined, orientationFrame: options.orientationFrame } : undefined);
+    const habitSession = options?.habitSession ?? baseToolContext?.habitSession;
     const augmentedToolContext = baseToolContext
         ? {
             ...baseToolContext,
@@ -751,8 +870,16 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             setReasoningEffort: (level) => { currentReasoningEffort = level; },
             activeWorkFrame: options?.activeWorkFrame,
             orientationFrame: options?.orientationFrame ?? baseToolContext.orientationFrame,
+            ...(habitSession ? { habitSession } : {}),
         }
-        : undefined;
+        : habitSession
+            ? {
+                signin: async () => undefined,
+                habitSession,
+                supportedReasoningEfforts: providerRuntime.supportedReasoningEfforts,
+                setReasoningEffort: (level) => { currentReasoningEffort = level; },
+            }
+            : undefined;
     // Rebase provider-owned turn state from canonical messages at user-turn start.
     // This prevents stale provider caches from replaying prior-turn context.
     providerRuntime.resetTurnState(messages);
@@ -766,17 +893,25 @@ async function runAgent(messages, callbacks, channel, signal, options) {
         // Inner dialog gets restTool instead of settleTool (rest = end turn, gated by attention queue).
         // toolChoiceRequired only controls whether tool_choice: "required" is set in the API call.
         const isInnerDialog = channel === "inner";
+        const innerHabitCanSendMessage = isInnerDialog
+            && habitSession?.toolPolicy.outwardMessagingAllowed === true
+            && habitSession.toolPolicy.grantedTools.includes("send_message");
+        const innerHabitCanSurface = isInnerDialog
+            && (!habitSession || (habitSession.toolPolicy.outwardMessagingAllowed === true
+                && habitSession.toolPolicy.grantedTools.includes("surface")));
         const filteredBaseTools = isInnerDialog
-            ? baseTools.filter((t) => t.function.name !== "send_message")
+            ? baseTools.filter((t) => innerHabitCanSendMessage || t.function.name !== "send_message")
             : baseTools;
         const activeTools = [
             ...filteredBaseTools,
             tools_1.ponderTool,
-            ...(isInnerDialog ? [tools_2.surfaceToolDef, tools_1.restTool] : []),
+            ...(isInnerDialog && innerHabitCanSurface ? [tools_2.surfaceToolDef] : []),
+            ...(isInnerDialog ? [tools_1.restTool] : []),
             ...(!isInnerDialog ? [tools_1.observeTool] : []),
             ...(!isInnerDialog ? [tools_1.settleTool] : []),
             ...(isChatStyleChannel(channel ?? "") ? [tools_1.speakTool] : []),
         ];
+        const activeToolNames = new Set(activeTools.map((tool) => tool.function.name));
         const steeringFollowUps = options?.drainSteeringFollowUps?.() ?? [];
         if (steeringFollowUps.length > 0) {
             const hasSupersedingFollowUp = steeringFollowUps.some((followUp) => followUp.effect === "clear_and_supersede");
@@ -803,13 +938,15 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             break;
         }
         try {
+            const habitCallbackBufferRef = { current: null };
             const callProviderTurn = async () => {
                 callbacks.onModelStart();
+                habitCallbackBufferRef.current = habitSession ? createHabitCallbackBuffer(callbacks) : null;
                 try {
                     return await providerRuntime.streamTurn({
                         messages,
                         activeTools,
-                        callbacks,
+                        callbacks: habitCallbackBufferRef.current?.callbacks ?? callbacks,
                         signal,
                         traceId,
                         toolChoiceRequired,
@@ -819,6 +956,8 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     });
                 }
                 catch (error) {
+                    habitCallbackBufferRef.current?.discard();
+                    habitCallbackBufferRef.current = null;
                     if (signal?.aborted)
                         throw new provider_attempt_1.ProviderAttemptAbortError();
                     throw error;
@@ -890,6 +1029,8 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 continue;
             }
             const result = attempt.value;
+            const streamCallbackBuffer = habitCallbackBufferRef.current;
+            habitCallbackBufferRef.current = null;
             // Track usage from the latest API call
             if (result.usage)
                 lastUsage = result.usage;
@@ -968,6 +1109,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                 })
                 : null;
             if (!result.toolCalls.length) {
+                await streamCallbackBuffer?.flush();
                 if (privateReturnTextAckRetryError) {
                     callbacks.onClearText?.();
                     if (noToolCallRetries < NO_TOOL_CALL_MAX_RETRIES) {
@@ -1050,6 +1192,26 @@ async function runAgent(messages, callbacks, channel, signal, options) {
             else {
                 // Reset the retry counter on any successful tool call.
                 noToolCallRetries = 0;
+                const habitBlockReason = await habitToolBatchBlockReason(habitSession, result.toolCalls, augmentedToolContext?.delegatedOrigins, activeToolNames);
+                if (habitBlockReason) {
+                    streamCallbackBuffer?.discard();
+                    recordBlockedHabitSurfaceAttempts(habitSession, result.toolCalls, habitBlockReason);
+                    messages.push(msg);
+                    const blockedOutput = `blocked: ${habitBlockReason}. No tool side effects from this assistant message were executed.`;
+                    for (const call of result.toolCalls) {
+                        messages.push({ role: "tool", tool_call_id: call.id, content: blockedOutput });
+                        providerRuntime.appendToolOutput(call.id, blockedOutput);
+                    }
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn",
+                        component: "engine",
+                        event: "engine.habit_tool_batch_blocked",
+                        message: "habit tool batch blocked before side effects",
+                        meta: { reason: habitBlockReason, toolCalls: result.toolCalls.map((call) => call.name) },
+                    });
+                    continue;
+                }
+                await streamCallbackBuffer?.flush();
                 // Check for settle sole call: intercept before tool execution
                 if (isSoleSettle) {
                     /* v8 ignore next -- defensive: JSON.parse catch for malformed settle args @preserve */
@@ -1501,6 +1663,7 @@ async function runAgent(messages, callbacks, channel, signal, options) {
                     catch (e) {
                         toolResult = `error: ${e}`;
                         success = false;
+                        augmentedToolContext?.habitSession?.recordError?.(toolResult);
                     }
                     toolResult = (0, tool_friction_1.rewriteToolResultForModel)(tc.name, toolResult, toolFrictionLedger);
                     (0, tool_loop_1.recordToolOutcome)(toolLoopState, tc.name, args, toolResult, success);

package/dist/heart/cross-chat-delivery.js

@@ -13,11 +13,12 @@ function buildPendingEnvelope(request, agentName, now) {
         timestamp: now,
     };
 }
-function queueForLater(request, deps, detail) {
+function queueForLater(request, deps, detail, rawStatus = "queued_for_later") {
     deps.queuePending(buildPendingEnvelope(request, deps.agentName, (deps.now ?? Date.now)()));
     return {
         status: "queued_for_later",
         detail,
+        ...(rawStatus !== "queued_for_later" ? { rawStatus } : {}),
     };
 }
 function isExplicitlyAuthorized(request) {
@@ -94,7 +95,7 @@ async function deliverCrossChatMessage(request, deps) {
             });
             return result;
         }
-        const result = queueForLater(request, deps, direct.detail.trim() || "live delivery unavailable right now; queued for the next active turn");
+        const result = queueForLater(request, deps, direct.detail.trim() || "live delivery unavailable right now; queued for the next active turn", direct.status);
         (0, runtime_1.emitNervesEvent)({
             component: "engine",
             event: "engine.cross_chat_delivery_end",

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

@@ -364,6 +364,8 @@ function agentResolutionFailureMode(command) {
         case "friend.update":
         case "habit.list":
         case "habit.create":
+        case "habit.runs":
+        case "habit.inspect":
         case "thoughts":
         case "attention.list":
         case "attention.show":
@@ -6841,9 +6843,10 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
         return result.summary;
     }
     // ── habit subcommands (local, no daemon socket needed) ──
-    if (command.kind === "habit.list" || command.kind === "habit.create") {
+    if (command.kind === "habit.list" || command.kind === "habit.create" || command.kind === "habit.runs" || command.kind === "habit.inspect") {
         const { parseHabitFile, renderHabitFile } = await Promise.resolve().then(() => __importStar(require("../habits/habit-parser")));
         const { applyHabitRuntimeState } = await Promise.resolve().then(() => __importStar(require("../habits/habit-runtime-state")));
+        const { listHabitRunReceipts, readHabitRunReceipt } = await Promise.resolve().then(() => __importStar(require("../../arc/flight-recorder")));
         /* v8 ignore start -- production default: uses real bundle root @preserve */
         const bundleRoot = deps.agentBundleRoot ?? path.join(deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)(), `${command.agent}.ouro`);
         /* v8 ignore stop */
@@ -6874,6 +6877,52 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             deps.writeStdout(message);
             return message;
         }
+        if (command.kind === "habit.runs") {
+            const receipts = listHabitRunReceipts(bundleRoot, { limit: command.limit });
+            const message = receipts.length === 0
+                ? "no habit runs found"
+                : receipts.map((receipt) => [
+                    receipt.runId,
+                    `habit=${receipt.habitName}`,
+                    `trigger=${receipt.trigger}`,
+                    `outcome=${receipt.outcome}`,
+                    `endedAt=${receipt.endedAt}`,
+                    `receipt=${receipt.receiptLocator}`,
+                ].join("  ")).join("\n");
+            deps.writeStdout(message);
+            (0, runtime_1.emitNervesEvent)({
+                component: "daemon",
+                event: "daemon.habit_runs_cli_read",
+                message: "habit run receipts listed from CLI",
+                meta: { agent: command.agent, limit: command.limit, count: receipts.length },
+            });
+            return message;
+        }
+        if (command.kind === "habit.inspect") {
+            const receipt = readHabitRunReceipt(bundleRoot, command.runId);
+            if (!receipt) {
+                const message = `error: habit run '${command.runId}' not found`;
+                deps.writeStdout(message);
+                deps.setExitCode?.(1);
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "daemon",
+                    event: "daemon.habit_run_cli_read_missing",
+                    message: "habit run receipt not found from CLI",
+                    meta: { agent: command.agent, runId: command.runId },
+                });
+                return message;
+            }
+            const message = `${JSON.stringify(receipt, null, 2)}\n`;
+            deps.writeStdout(message);
+            (0, runtime_1.emitNervesEvent)({
+                component: "daemon",
+                event: "daemon.habit_run_cli_read",
+                message: "habit run receipt read from CLI",
+                meta: { agent: command.agent, runId: command.runId },
+            });
+            return message;
+        }
         // habit.create
         const filePath = path.join(habitsDir, `${command.name}.md`);
         if (fs.existsSync(filePath)) {

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

@@ -127,7 +127,7 @@ exports.COMMAND_REGISTRY = {
     poke: {
         category: "Tasks",
         description: "Poke an agent about a task or habit",
-        usage: "ouro poke <agent> --task <task-id> | --habit <name>",
+        usage: "ouro poke <agent> --task <task-id> | --habit <name> [--trigger poke|launchd|cron|overdue|manual]",
         example: "ouro poke ouroboros --task abc123",
     },
     habit: {

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

@@ -17,6 +17,7 @@ exports.parseOuroCommand = parseOuroCommand;
 const types_1 = require("../../mind/friends/types");
 const cli_help_1 = require("./cli-help");
 const cli_desk_1 = require("./cli-desk");
+const flight_recorder_1 = require("../../arc/flight-recorder");
 const vault_items_1 = require("./vault-items");
 // ── Shared helpers ──
 function extractAgentFlag(args) {
@@ -104,9 +105,11 @@ function usage() {
         "  ouro chat <agent>",
         "  ouro msg --to <agent> [--session <id>] [--task <ref>] <message>",
         "  ouro poke <agent> --task <task-id>",
-        "  ouro poke <agent> --habit <name>",
+        "  ouro poke <agent> --habit <name> [--trigger poke|launchd|cron|overdue|manual]",
         "  ouro habit list [--agent <name>]",
         "  ouro habit create [--agent <name>] <name> [--cadence <interval>]",
+        "  ouro habit runs [--agent <name>] [--limit <n>]",
+        "  ouro habit inspect [--agent <name>] <runId>",
         "  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 friend list [--agent <name>]",
@@ -175,6 +178,7 @@ function parsePokeCommand(args) {
     let taskId;
     let habitName;
     let awaitName;
+    let trigger;
     for (let i = 1; i < args.length; i += 1) {
         if (args[i] === "--task") {
             taskId = args[i + 1];
@@ -188,12 +192,21 @@ function parsePokeCommand(args) {
             awaitName = args[i + 1];
             i += 1;
         }
+        if (args[i] === "--trigger") {
+            const rawTrigger = args[i + 1];
+            if (!(0, flight_recorder_1.isHabitRunTrigger)(rawTrigger))
+                throw new Error("invalid habit trigger");
+            trigger = rawTrigger;
+            i += 1;
+        }
     }
     // Priority order: --await > --habit > --task
     if (awaitName)
         return { kind: "await.poke", agent, awaitName };
     if (habitName)
-        return { kind: "habit.poke", agent, habitName };
+        return { kind: "habit.poke", agent, habitName, trigger: trigger ?? "poke" };
+    if (trigger)
+        throw new Error(`Usage\n${usage()}`);
     if (!taskId)
         throw new Error(`Usage\n${usage()}`);
     return { kind: "task.poke", agent, taskId };
@@ -227,6 +240,27 @@ function parseHabitCommand(args) {
             throw new Error(`Usage\n${usage()}`);
         return { kind: "habit.create", name, ...(agent ? { agent } : {}), ...(cadence ? { cadence } : {}) };
     }
+    if (sub === "runs") {
+        let limit = 20;
+        const options = rest.slice(1);
+        for (let i = 0; i < options.length; i += 1) {
+            if (options[i] !== "--limit" || !options[i + 1])
+                throw new Error(`Usage\n${usage()}`);
+            const parsedLimit = Number.parseInt(options[i + 1], 10);
+            if (!Number.isInteger(parsedLimit) || String(parsedLimit) !== options[i + 1] || parsedLimit < 1 || parsedLimit > 100) {
+                throw new Error("--limit must be an integer between 1 and 100");
+            }
+            limit = parsedLimit;
+            i += 1;
+        }
+        return { kind: "habit.runs", ...(agent ? { agent } : {}), limit };
+    }
+    if (sub === "inspect") {
+        const positional = rest.slice(1);
+        if (positional.length !== 1 || !positional[0])
+            throw new Error(`Usage\n${usage()}`);
+        return { kind: "habit.inspect", ...(agent ? { agent } : {}), runId: positional[0] };
+    }
     throw new Error(`Usage\n${usage()}`);
 }
 function parseLinkCommand(args, kind = "friend.link") {

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

@@ -149,9 +149,30 @@ const processManager = new process_manager_1.DaemonProcessManager({
     },
     /* v8 ignore stop */
 });
-const scheduler = new task_scheduler_1.TaskDrivenScheduler({
+const taskScheduler = new task_scheduler_1.TaskDrivenScheduler({
     agents: [...managedAgents],
 });
+const habitSchedulers = [];
+const awaitSchedulers = [];
+const scheduler = {
+    listJobs: () => [
+        ...taskScheduler.listJobs(),
+        ...habitSchedulers.flatMap((habitScheduler) => habitScheduler.listJobs()),
+    ],
+    triggerJob: (jobId) => taskScheduler.triggerJob(jobId),
+    triggerHabitJob: async (jobId) => {
+        for (const habitScheduler of habitSchedulers) {
+            const result = await habitScheduler.triggerJob(jobId, "cron");
+            if (result.ok)
+                return result;
+        }
+        return { ok: false, message: `unknown habit job: ${jobId}` };
+    },
+    start: () => taskScheduler.start(),
+    stop: () => taskScheduler.stop(),
+    reconcile: () => taskScheduler.reconcile(),
+    recordTaskRun: (agent, taskId) => taskScheduler.recordTaskRun(agent, taskId),
+};
 const router = new message_router_1.FileMessageRouter();
 const senseManager = new sense_manager_1.DaemonSenseManager({
     agents: [...managedAgents],
@@ -201,8 +222,6 @@ const healthMonitor = new health_monitor_1.HealthMonitor({
         catch { /* recovery is best-effort */ }
     },
 });
-const habitSchedulers = [];
-const awaitSchedulers = [];
 let entryRuntimeStopping = false;
 let stopCommandExitScheduled = false;
 function stopEntryRuntime() {
@@ -393,8 +412,8 @@ void daemon.start().then(async () => {
                 agent,
                 habitsDir,
                 osCronManager,
-                onHabitFire: (habitName) => {
-                    processManager.sendToAgent(agent, { type: "habit", habitName, trigger: "overdue" });
+                onHabitFire: (habitName, trigger) => {
+                    processManager.sendToAgent(agent, { type: "habit", habitName, trigger });
                 },
                 deps: {
                     readdir: (dir) => fs.readdirSync(dir),

package/dist/heart/daemon/daemon.js

@@ -67,6 +67,7 @@ const mailbox_read_1 = require("../mailbox/mailbox-read");
 const mailbox_view_1 = require("../mailbox/mailbox-view");
 const provider_visibility_1 = require("../provider-visibility");
 const socket_client_1 = require("./socket-client");
+const flight_recorder_1 = require("../../arc/flight-recorder");
 const PIDFILE_PATH = path.join(os.homedir(), ".ouro-cli", "daemon.pids");
 /**
  * Defense-in-depth: detect if we're running under vitest. The pidfile lives
@@ -1236,6 +1237,10 @@ class OuroDaemon {
                 return { ok: true, summary, data: jobs };
             }
             case "cron.trigger": {
+                const habitResult = await this.scheduler.triggerHabitJob?.(command.jobId);
+                if (habitResult?.ok) {
+                    return { ok: true, message: habitResult.message };
+                }
                 const result = await this.scheduler.triggerJob(command.jobId);
                 return { ok: result.ok, message: result.message };
             }
@@ -1302,7 +1307,11 @@ class OuroDaemon {
                 };
             }
             case "habit.poke": {
-                this.processManager.sendToAgent?.(command.agent, { type: "habit", habitName: command.habitName, trigger: "poke" });
+                const trigger = command.trigger ?? "poke";
+                if (!(0, flight_recorder_1.isHabitRunTrigger)(trigger)) {
+                    return { ok: false, error: `invalid habit trigger: ${String(trigger)}` };
+                }
+                this.processManager.sendToAgent?.(command.agent, { type: "habit", habitName: command.habitName, trigger });
                 return {
                     ok: true,
                     message: `poked habit ${command.habitName} for ${command.agent}`,

package/dist/heart/habits/habit-scheduler.js

@@ -108,7 +108,7 @@ class HabitScheduler {
                     message: "firing overdue habit (never run)",
                     meta: { habitName: habit.name, agent: this.agent },
                 });
-                this.onHabitFire(habit.name);
+                this.onHabitFire(habit.name, "overdue");
                 continue;
             }
             const lastRunMs = new Date(habit.lastRun).getTime();
@@ -120,7 +120,7 @@ class HabitScheduler {
                     message: "firing overdue habit",
                     meta: { habitName: habit.name, agent: this.agent, elapsedMs: elapsed },
                 });
-                this.onHabitFire(habit.name);
+                this.onHabitFire(habit.name, "overdue");
             }
         }
     }
@@ -174,6 +174,25 @@ class HabitScheduler {
             return null;
         }
     }
+    listJobs() {
+        return this.buildJobs(this.scanHabits())
+            .map((job) => ({ id: job.id, schedule: job.schedule, lastRun: job.lastRun }))
+            .sort((a, b) => a.id.localeCompare(b.id));
+    }
+    async triggerJob(jobId, trigger = "cron") {
+        const job = this.buildJobs(this.scanHabits()).find((candidate) => candidate.id === jobId);
+        if (!job) {
+            return { ok: false, message: `unknown habit job: ${jobId}` };
+        }
+        this.onHabitFire(job.taskId, trigger);
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.habit_job_triggered",
+            message: "habit scheduler job triggered",
+            meta: { agent: job.agent, habitName: job.taskId, jobId, trigger },
+        });
+        return { ok: true, message: `triggered habit ${jobId}` };
+    }
     watchForChanges() {
         const watchFn = this.deps.watch;
         if (!watchFn)
@@ -278,7 +297,7 @@ class HabitScheduler {
                 const output = this.execForVerify("crontab -l");
                 const lines = output.split("\n");
                 for (const line of lines) {
-                    const match = line.match(/ouro poke \S+ --habit (\S+)/);
+                    const match = line.match(/ouro poke \S+ --habit (\S+)(?:\s+--trigger\s+\S+)?/);
                     if (match) {
                         verified.add(match[1]);
                     }
@@ -293,7 +312,7 @@ class HabitScheduler {
     createTimerFallback(habitName, cadenceMs) {
         const schedule = () => {
             const timer = setTimeout(() => {
-                this.onHabitFire(habitName);
+                this.onHabitFire(habitName, "overdue");
                 schedule();
             }, cadenceMs);
             this.timerFallbacks.set(habitName, timer);
@@ -362,7 +381,7 @@ class HabitScheduler {
                 taskId: habit.name,
                 schedule: cronSchedule,
                 lastRun: habit.lastRun,
-                command: `${this.deps.ouroPath} poke ${this.agent} --habit ${habit.name}`,
+                command: `${this.deps.ouroPath} poke ${this.agent} --habit ${habit.name} --trigger launchd`,
                 taskPath: path.join(this.habitsDir, `${habit.name}.md`),
             });
         }