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

package/changelog.json

@@ -1,6 +1,19 @@
 {
   "_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.668",
+      "changes": [
+        "Harden flight-recorder reconciliation so terminal fulfilled-only repairs are not continuable work, unverifiable active obligation ids are preserved and degraded, parseable-invalid obligation records are excluded from verified recovery state, synthesized recovery actions get fresh provenance, reads remain side-effect-free, and legacy obligation records stay visible in Mailbox, Workbench, and Work Card summaries."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.667",
+      "changes": [
+        "Add stateful habit session summaries, summary tooling, mailbox APIs, nerves review, and habit history visibility.",
+        "Harden habit summary receipts as the canonical summary snapshot, validate agent-scoped Mailbox routes, await post-turn persistence, and preserve session-summary recovery through malformed locators and projected session edge cases."
+      ]
+    },
     {
       "version": "0.1.0-alpha.666",
       "changes": [

package/dist/arc/flight-recorder.js

@@ -50,6 +50,7 @@ const path = __importStar(require("path"));
 const crypto_1 = require("crypto");
 const session_events_1 = require("../heart/session-events");
 const runtime_1 = require("../nerves/runtime");
+const obligations_1 = require("./obligations");
 function isHabitRunTrigger(value) {
     return value === "cron"
         || value === "launchd"
@@ -201,7 +202,7 @@ function normalizeResumeInvariants(resume) {
     ];
     const missingChanged = resume.missing.join("\n") !== missing.join("\n");
     const issues = [
-        ...(resume.canContinue && !resume.hasCompleteState ? ["canContinue true while hasCompleteState false"] : []),
+        ...(resume.canContinue && !hasCompleteState ? ["canContinue true while hasCompleteState false"] : []),
         ...(resume.canContinue && !hasCurrentAsk ? ["canContinue true without currentAsk"] : []),
         ...(resume.canContinue && !hasNextSafeAction ? ["canContinue true without nextSafeAction"] : []),
         ...(resume.canContinue && resume.blockedBecause.length > 0 ? ["canContinue true while blocked"] : []),
@@ -226,7 +227,117 @@ function normalizeResumeInvariants(resume) {
             : resume.recorderHealth,
     };
 }
-/* v8 ignore stop */
+const FLIGHT_RECORDER_RECONCILE_SOURCE_ID = "reconcile:active-obligations";
+function remainingArcWorkDescriptions(resume) {
+    return [
+        ...resume.activeReturnObligationIds.map((id) => `return obligation ${id}`),
+        ...resume.activePacketIds.map((id) => `packet ${id}`),
+        ...resume.openEvolutionCaseIds.map((id) => `evolution case ${id}`),
+    ];
+}
+function nextSafeActionAfterObligationReconcile(resume, activeObligations, staleActiveObligationIds, unverifiableActiveObligationIds) {
+    if (unverifiableActiveObligationIds.length > 0) {
+        return (0, session_events_1.capStructuredRecordString)(`inspect unverifiable active obligations before acting: ${unverifiableActiveObligationIds.join(", ")}`);
+    }
+    const firstActive = activeObligations[0];
+    if (firstActive) {
+        const detail = firstActive.nextAction?.trim() || firstActive.content;
+        return (0, session_events_1.capStructuredRecordString)(`continue open obligation ${firstActive.id}: ${detail}`);
+    }
+    const remainingWork = remainingArcWorkDescriptions(resume);
+    if (remainingWork.length > 0) {
+        return (0, session_events_1.capStructuredRecordString)(`continue remaining Arc work: ${remainingWork.slice(0, 5).join(", ")}`);
+    }
+    return (0, session_events_1.capStructuredRecordString)(`wait for new input; reconciled completed or missing obligations: ${staleActiveObligationIds.join(", ")}`);
+}
+function reconcileActiveObligations(agentRoot, resume) {
+    const obligations = (0, obligations_1.readVerifiedObligations)(agentRoot);
+    const activeObligations = (0, obligations_1.readVerifiedPendingObligations)(agentRoot);
+    const canonicalIdSet = new Set(obligations.map((obligation) => obligation.id));
+    const openIdSet = new Set(activeObligations.map((obligation) => obligation.id));
+    const resumeIdSet = new Set(resume.activeObligationIds);
+    const staleActiveObligationIds = resume.activeObligationIds.filter((id) => canonicalIdSet.has(id) && !openIdSet.has(id));
+    const unverifiableActiveObligationIds = resume.activeObligationIds.filter((id) => !canonicalIdSet.has(id));
+    const missingActiveObligationIds = activeObligations
+        .map((obligation) => obligation.id)
+        .filter((id) => !resumeIdSet.has(id));
+    if (staleActiveObligationIds.length === 0
+        && missingActiveObligationIds.length === 0
+        && unverifiableActiveObligationIds.length === 0) {
+        return { resume, staleActiveObligationIds, missingActiveObligationIds, unverifiableActiveObligationIds };
+    }
+    const activeObligationIds = uniqueStrings([
+        ...resume.activeObligationIds.filter((id) => !staleActiveObligationIds.includes(id)),
+        ...missingActiveObligationIds,
+    ]);
+    const hasActiveArcContinuation = activeObligationIds.length > 0
+        || resume.activeReturnObligationIds.length > 0
+        || resume.activePacketIds.length > 0
+        || resume.openEvolutionCaseIds.length > 0;
+    const isTerminalWait = staleActiveObligationIds.length > 0 && !hasActiveArcContinuation;
+    const mustSynthesizeAction = staleActiveObligationIds.length > 0
+        || unverifiableActiveObligationIds.length > 0
+        || !nonEmpty(resume.nextSafeAction.value);
+    const nextSafeActionValue = mustSynthesizeAction
+        ? nextSafeActionAfterObligationReconcile(resume, activeObligations, staleActiveObligationIds, unverifiableActiveObligationIds)
+        : resume.nextSafeAction.value;
+    const recorderHealth = unverifiableActiveObligationIds.length > 0
+        ? {
+            status: resume.recorderHealth.status === "unavailable" ? "unavailable" : "degraded",
+            issues: uniqueStrings([
+                ...resume.recorderHealth.issues,
+                `active obligation ids could not be verified in arc/obligations: ${unverifiableActiveObligationIds.join(", ")}`,
+            ]),
+        }
+        : resume.recorderHealth;
+    const canContinue = nonEmpty(resume.currentAsk.value)
+        && nonEmpty(nextSafeActionValue)
+        && resume.blockedBecause.length === 0
+        && recorderHealth.status === "ok"
+        && hasActiveArcContinuation
+        && !isTerminalWait;
+    return {
+        resume: normalizeResumeInvariants({
+            ...resume,
+            canContinue,
+            recorderHealth,
+            activeObligationIds,
+            nextSafeAction: {
+                ...resume.nextSafeAction,
+                value: nextSafeActionValue,
+                sourceEventIds: mustSynthesizeAction
+                    ? [FLIGHT_RECORDER_RECONCILE_SOURCE_ID]
+                    : resume.nextSafeAction.sourceEventIds,
+                stopBefore: unverifiableActiveObligationIds.length > 0
+                    ? uniqueStrings([...resume.nextSafeAction.stopBefore, "acting on unverifiable obligation state"])
+                    : resume.nextSafeAction.stopBefore,
+            },
+        }),
+        staleActiveObligationIds,
+        missingActiveObligationIds,
+        unverifiableActiveObligationIds,
+    };
+}
+function normalizeResumeForAgentRoot(agentRoot, resume) {
+    return reconcileActiveObligations(agentRoot, normalizeResumeInvariants(resume));
+}
+function emitFlightRecorderReconciled(agentRoot, staleActiveObligationIds, missingActiveObligationIds, unverifiableActiveObligationIds) {
+    if (staleActiveObligationIds.length === 0
+        && missingActiveObligationIds.length === 0
+        && unverifiableActiveObligationIds.length === 0)
+        return;
+    (0, runtime_1.emitNervesEvent)({
+        component: "mind",
+        event: "mind.flight_recorder_resume_reconciled",
+        message: "flight recorder resume reconciled with canonical Arc state",
+        meta: {
+            agentRoot,
+            staleActiveObligationIds,
+            missingActiveObligationIds,
+            unverifiableActiveObligationIds,
+        },
+    });
+}
 function latestFromEvent(event, previous) {
     const currentAskValue = event.currentAsk !== undefined ? event.currentAsk : previous.currentAsk.value;
     const nextSafeActionValue = event.nextSafeAction !== undefined ? event.nextSafeAction : previous.nextSafeAction.value;
@@ -279,7 +390,12 @@ function readFlightRecorderResume(agentRoot) {
         if (!isFlightRecorderResume(parsed)) {
             throw new Error("latest.json has invalid flight-recorder resume shape");
         }
-        const resume = normalizeResumeInvariants(parsed);
+        const { resume, staleActiveObligationIds, missingActiveObligationIds, unverifiableActiveObligationIds, } = normalizeResumeForAgentRoot(agentRoot, parsed);
+        if (staleActiveObligationIds.length > 0
+            || missingActiveObligationIds.length > 0
+            || unverifiableActiveObligationIds.length > 0) {
+            emitFlightRecorderReconciled(agentRoot, staleActiveObligationIds, missingActiveObligationIds, unverifiableActiveObligationIds);
+        }
         (0, runtime_1.emitNervesEvent)({
             component: "mind",
             event: "mind.flight_recorder_resume_read",
@@ -302,8 +418,9 @@ function readFlightRecorderResume(agentRoot) {
     }
 }
 function writeFlightRecorderResume(agentRoot, resume) {
-    const safeResume = normalizeResumeInvariants(resume);
+    const { resume: safeResume, staleActiveObligationIds, missingActiveObligationIds, unverifiableActiveObligationIds, } = normalizeResumeForAgentRoot(agentRoot, resume);
     atomicWriteJson(flightRecorderLatestPath(agentRoot), safeResume);
+    emitFlightRecorderReconciled(agentRoot, staleActiveObligationIds, missingActiveObligationIds, unverifiableActiveObligationIds);
     (0, runtime_1.emitNervesEvent)({
         component: "mind",
         event: "mind.flight_recorder_resume_written",
@@ -397,6 +514,52 @@ function isHabitToolPolicy(value) {
         && isStringArray(value.deniedTools)
         && typeof value.outwardMessagingAllowed === "boolean";
 }
+function defaultHabitRunSummarySnapshot(receipt) {
+    if (receipt.errors.length > 0) {
+        return {
+            summary: `Habit ${receipt.habitName} finished with errors: ${receipt.errors.join("; ")}`,
+            decisions: [],
+            nextLikelyStep: null,
+        };
+    }
+    const surface = receipt.surfaceAttempts.find((attempt) => attempt.result !== "blocked" && attempt.result !== "failed" && attempt.result !== "unavailable");
+    if (surface) {
+        return {
+            summary: `Habit ${receipt.habitName} surfaced via ${surface.recipient}/${surface.channel}.`,
+            decisions: [],
+            nextLikelyStep: null,
+        };
+    }
+    const produced = receipt.producedRefs.find((ref) => ref.kind !== "none");
+    if (produced) {
+        return {
+            summary: `Habit ${receipt.habitName} produced ${produced.kind}: ${produced.locator}.`,
+            decisions: [],
+            nextLikelyStep: null,
+        };
+    }
+    return {
+        summary: `Habit ${receipt.habitName} finished with ${receipt.outcome}.`,
+        decisions: [],
+        nextLikelyStep: null,
+    };
+}
+function normalizeHabitRunSummarySnapshot(value, fallback) {
+    const snapshot = isPlainRecord(value) ? value : {};
+    const summary = typeof snapshot.summary === "string" && snapshot.summary.trim().length > 0
+        ? snapshot.summary
+        : fallback.summary;
+    const nextLikelyStep = snapshot.nextLikelyStep === null
+        ? null
+        : typeof snapshot.nextLikelyStep === "string" && snapshot.nextLikelyStep.trim().length > 0
+            ? snapshot.nextLikelyStep
+            : fallback.nextLikelyStep;
+    return {
+        summary: (0, session_events_1.capStructuredRecordString)(summary),
+        decisions: cappedArray(isStringArray(snapshot.decisions) ? snapshot.decisions : fallback.decisions),
+        nextLikelyStep: nextLikelyStep === null ? null : (0, session_events_1.capStructuredRecordString)(nextLikelyStep),
+    };
+}
 function isHabitRunReceipt(value) {
     if (!isPlainRecord(value))
         return false;
@@ -423,9 +586,11 @@ function isHabitRunReceipt(value) {
         && typeof value.pendingLocator === "string"
         && typeof value.runtimeStateLocator === "string"
         && typeof value.receiptLocator === "string"
+        && (value.operationId === undefined || value.operationId === null || typeof value.operationId === "string")
         && (value.nextRunAt === null || typeof value.nextRunAt === "string")
         && isHabitPermissionEnvelope(value.permissionEnvelope)
         && isHabitToolPolicy(value.toolPolicy)
+        && (value.summarySnapshot === undefined || isPlainRecord(value.summarySnapshot))
         && isProducedRefArray(value.producedRefs)
         && isHabitSurfaceAttemptArray(value.surfaceAttempts)
         && isStringArray(value.errors);
@@ -479,6 +644,7 @@ function normalizeLegacyHabitRunReceipt(receipt) {
         pendingLocator: `state/habit-sessions/${receipt.runId}/pending`,
         runtimeStateLocator: `state/habits/${receipt.habitName}.json`,
         receiptLocator: `arc/flight-recorder/habit-receipts/${receipt.runId}.json`,
+        operationId: null,
         nextRunAt: null,
         permissionEnvelope: {
             schemaVersion: 1,
@@ -493,12 +659,14 @@ function normalizeLegacyHabitRunReceipt(receipt) {
             deniedTools: sawSurface ? [] : ["send_message", "surface"],
             outwardMessagingAllowed: sawSurface,
         },
+        summarySnapshot: defaultHabitRunSummarySnapshot(receipt),
         producedRefs: receipt.producedRefs,
         surfaceAttempts: receipt.surfaceAttempts,
         errors: receipt.errors,
     };
 }
 function capHabitRunReceipt(receipt) {
+    const fallbackSnapshot = defaultHabitRunSummarySnapshot(receipt);
     return {
         ...receipt,
         habitName: (0, session_events_1.capStructuredRecordString)(receipt.habitName),
@@ -507,6 +675,7 @@ function capHabitRunReceipt(receipt) {
         pendingLocator: (0, session_events_1.capStructuredRecordString)(receipt.pendingLocator),
         runtimeStateLocator: (0, session_events_1.capStructuredRecordString)(receipt.runtimeStateLocator),
         receiptLocator: (0, session_events_1.capStructuredRecordString)(receipt.receiptLocator),
+        operationId: receipt.operationId ? (0, session_events_1.capStructuredRecordString)(receipt.operationId) : null,
         permissionEnvelope: {
             ...receipt.permissionEnvelope,
             returnRoutes: receipt.permissionEnvelope.returnRoutes.map((route) => ({
@@ -526,6 +695,7 @@ function capHabitRunReceipt(receipt) {
             deniedTools: cappedArray(receipt.toolPolicy.deniedTools),
             outwardMessagingAllowed: receipt.toolPolicy.outwardMessagingAllowed,
         },
+        summarySnapshot: normalizeHabitRunSummarySnapshot(receipt.summarySnapshot, fallbackSnapshot),
         producedRefs: receipt.producedRefs.map((ref) => ({ ...ref, locator: (0, session_events_1.capStructuredRecordString)(ref.locator) })),
         surfaceAttempts: receipt.surfaceAttempts.map((attempt) => ({
             ...attempt,
@@ -562,7 +732,7 @@ function readHabitRunReceipt(agentRoot, runId) {
             message: "flight recorder habit receipt read",
             meta: { agentRoot, runId },
         });
-        return receipt;
+        return capHabitRunReceipt(receipt);
     }
     catch (error) {
         warnMalformedHabitReceipt(agentRoot, runId, error instanceof Error ? error.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(error));
@@ -593,7 +763,10 @@ function writeHabitRunReceipt(agentRoot, receipt) {
         recordedAt: safeReceipt.endedAt,
         summary: `habit ${safeReceipt.habitName} finished with ${safeReceipt.outcome}`,
         producedRefs: safeReceipt.producedRefs,
-        meta: { receiptPath: path.join("arc", "flight-recorder", "habit-receipts", `${safeReceipt.runId}.json`) },
+        meta: {
+            receiptPath: path.join("arc", "flight-recorder", "habit-receipts", `${safeReceipt.runId}.json`),
+            operationId: safeReceipt.operationId ?? null,
+        },
     });
     (0, runtime_1.emitNervesEvent)({
         component: "mind",

package/dist/arc/obligations.js

@@ -38,6 +38,8 @@ exports.isOpenObligation = isOpenObligation;
 exports.createObligation = createObligation;
 exports.readObligations = readObligations;
 exports.readPendingObligations = readPendingObligations;
+exports.readVerifiedObligations = readVerifiedObligations;
+exports.readVerifiedPendingObligations = readVerifiedPendingObligations;
 exports.advanceObligation = advanceObligation;
 exports.fulfillObligation = fulfillObligation;
 exports.findPendingObligationForOrigin = findPendingObligationForOrigin;
@@ -64,6 +66,31 @@ function isOpenObligationStatus(status) {
 function isOpenObligation(obligation) {
     return isOpenObligationStatus(obligation.status);
 }
+function isReadableObligation(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const obligation = value;
+    return typeof obligation.id === "string"
+        && typeof obligation.content === "string";
+}
+function isVerifiedObligationStatus(value) {
+    return value === "pending"
+        || value === "investigating"
+        || value === "waiting_for_merge"
+        || value === "updating_runtime"
+        || value === "fulfilled";
+}
+function isVerifiedObligation(value) {
+    if (!isReadableObligation(value))
+        return false;
+    const obligation = value;
+    return isVerifiedObligationStatus(obligation.status)
+        && typeof obligation.createdAt === "string"
+        && !!obligation.origin
+        && typeof obligation.origin.friendId === "string"
+        && typeof obligation.origin.channel === "string"
+        && typeof obligation.origin.key === "string";
+}
 function createObligation(agentRoot, input) {
     const now = new Date().toISOString();
     const id = (0, json_store_1.generateTimestampId)();
@@ -92,11 +119,18 @@ function createObligation(agentRoot, input) {
 }
 function readObligations(agentRoot) {
     const all = (0, json_store_1.readJsonDir)(obligationsDir(agentRoot));
-    return all.filter((parsed) => typeof parsed.id === "string" && typeof parsed.content === "string");
+    return all.filter(isReadableObligation);
 }
 function readPendingObligations(agentRoot) {
     return readObligations(agentRoot).filter(isOpenObligation);
 }
+function readVerifiedObligations(agentRoot) {
+    const all = (0, json_store_1.readJsonDir)(obligationsDir(agentRoot));
+    return all.filter(isVerifiedObligation);
+}
+function readVerifiedPendingObligations(agentRoot) {
+    return readVerifiedObligations(agentRoot).filter(isOpenObligation);
+}
 function advanceObligation(agentRoot, obligationId, update) {
     const dir = obligationsDir(agentRoot);
     const obligation = (0, json_store_1.readJsonFile)(dir, obligationId);

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

@@ -96,6 +96,7 @@ const cli_help_1 = require("./cli-help");
 const plugin_cli_1 = require("./plugin-cli");
 const cli_desk_1 = require("./cli-desk");
 const migrate_to_desk_1 = require("./migrate-to-desk");
+const core_2 = require("../../nerves/review/core");
 const cli_render_1 = require("./cli-render");
 const cli_defaults_1 = require("./cli-defaults");
 const agent_config_check_1 = require("./agent-config-check");
@@ -150,6 +151,58 @@ function returnCliFailure(deps, message, exitCode = 1) {
     deps.writeStdout(message);
     return message;
 }
+function renderHabitSummaryCli(summary) {
+    return [
+        `${summary.runId}  habit=${summary.habitName}  outcome=${summary.status}  completedAt=${summary.completedAt}`,
+        summary.operationId ? `operation=${summary.operationId}` : null,
+        `summary=${summary.summary}`,
+        summary.nextLikelyStep ? `next=${summary.nextLikelyStep}` : null,
+        summary.decisions.length > 0 ? `decisions=${summary.decisions.join("; ")}` : null,
+        `pending=${summary.pending.count}${summary.pending.files.length > 0 ? ` (${summary.pending.files.join(", ")})` : ""}`,
+        `messages=${summary.messagesSent.length}`,
+        `tools=${summary.toolsUsed.length > 0 ? summary.toolsUsed.join(",") : "none"}`,
+        summary.producedRefs.length > 0 ? `refs=${summary.producedRefs.map((ref) => `${ref.kind}:${ref.locator}`).join(",")}` : null,
+        summary.errors.length > 0 ? `errors=${summary.errors.join("; ")}` : null,
+        summary.warnings.length > 0 ? `warnings=${summary.warnings.join("; ")}` : null,
+        `receipt=${summary.sources.receipt}`,
+        `session=${summary.sources.session}`,
+        `runtime=${summary.sources.runtimeState}`,
+    ].filter((line) => Boolean(line)).join("\n");
+}
+function executeNervesReviewCommand(command, deps) {
+    let sinceMs;
+    if (command.since) {
+        const parsed = (0, core_2.parseDuration)(command.since);
+        if (parsed === null) {
+            const message = `nerves-review: --since '${command.since}' is not a valid duration (e.g. 5m, 2h, 1d)`;
+            deps.setExitCode?.(2);
+            deps.writeStdout(message);
+            return message;
+        }
+        sinceMs = parsed;
+    }
+    const logsDir = (0, identity_1.getAgentDaemonLogsDir)(command.agent);
+    const filePath = path.join(logsDir, `${command.process}.ndjson`);
+    const entries = (0, core_2.reviewNerveEvents)(filePath, {
+        componentSubstring: command.component,
+        eventSubstring: command.event,
+        level: command.level,
+        sinceMs,
+        limit: command.limit,
+        nowMs: Date.now(),
+    });
+    const message = entries.length === 0
+        ? `(no matching nerves events in ${filePath})`
+        : entries.map((entry) => command.json ? entry.raw : (0, core_2.formatNerveEntry)(entry)).join("\n");
+    deps.writeStdout(message);
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.nerves_review_cli_read",
+        message: "nerves review CLI read local log events",
+        meta: { agent: command.agent, process: command.process, count: entries.length, json: command.json },
+    });
+    return message;
+}
 function summarizeDaemonStartupFailure(result) {
     if (result.startupFailureReason && result.startupFailureReason.trim().length > 0) {
         return result.startupFailureReason;
@@ -366,6 +419,8 @@ function agentResolutionFailureMode(command) {
         case "habit.create":
         case "habit.runs":
         case "habit.inspect":
+        case "habit.summary":
+        case "nerves-review":
         case "thoughts":
         case "attention.list":
         case "attention.show":
@@ -5684,6 +5739,9 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     if (command.kind === "hook") {
         await refreshHookSentinel(command, deps);
     }
+    if (command.kind === "nerves-review") {
+        return executeNervesReviewCommand(command, deps);
+    }
     if (args.length === 0) {
         const discovered = await Promise.resolve(deps.listDiscoveredAgents ? deps.listDiscoveredAgents() : (0, cli_defaults_1.defaultListDiscoveredAgents)());
         /* v8 ignore start -- the interactive home shell is exercised extensively in daemon-cli tests; V8 miscounts this orchestrator because it chains through recursive command handoffs and early chat health exits @preserve */
@@ -6843,10 +6901,11 @@ 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" || command.kind === "habit.runs" || command.kind === "habit.inspect") {
+    if (command.kind === "habit.list" || command.kind === "habit.create" || command.kind === "habit.runs" || command.kind === "habit.inspect" || command.kind === "habit.summary") {
         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")));
+        const { readHabitSessionSummary } = await Promise.resolve().then(() => __importStar(require("../habits/habit-session-summary")));
         /* 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 */
@@ -6923,6 +6982,36 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
             });
             return message;
         }
+        if (command.kind === "habit.summary") {
+            const summary = readHabitSessionSummary(bundleRoot, {
+                ...(command.runId ? { runId: command.runId } : {}),
+                ...(command.habitName ? { habitName: command.habitName } : {}),
+                ...(command.operationId ? { operationId: command.operationId } : {}),
+                ...(command.which ? { which: command.which } : {}),
+            });
+            if (!summary) {
+                const message = "error: habit summary not found";
+                deps.writeStdout(message);
+                deps.setExitCode?.(1);
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "daemon",
+                    event: "daemon.habit_summary_cli_read_missing",
+                    message: "habit run summary not found from CLI",
+                    meta: { agent: command.agent, runId: command.runId, habitName: command.habitName, operationId: command.operationId, which: command.which },
+                });
+                return message;
+            }
+            const message = command.json ? `${JSON.stringify(summary, null, 2)}\n` : renderHabitSummaryCli(summary);
+            deps.writeStdout(message);
+            (0, runtime_1.emitNervesEvent)({
+                component: "daemon",
+                event: "daemon.habit_summary_cli_read",
+                message: "habit run summary read from CLI",
+                meta: { agent: command.agent, runId: summary.runId, habitName: summary.habitName, json: command.json },
+            });
+            return message;
+        }
         // habit.create
         const filePath = path.join(habitsDir, `${command.name}.md`);
         if (fs.existsSync(filePath)) {

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

@@ -135,7 +135,7 @@ exports.COMMAND_REGISTRY = {
         description: "Manage agent habits",
         usage: "ouro habit <subcommand> [--agent <name>]",
         example: "ouro habit list",
-        subcommands: ["list", "create", "poke"],
+        subcommands: ["list", "create", "runs", "inspect", "summary", "poke"],
     },
     desk: {
         category: "Tasks",
@@ -158,6 +158,12 @@ exports.COMMAND_REGISTRY = {
         example: "ouro work sentinel --agent slugger --format json",
         subcommands: ["card", "gauntlet", "sentinel"],
     },
+    "nerves-review": {
+        category: "Internal",
+        description: "Read-only review of recent nerves events from an agent log stream",
+        usage: "ouro nerves-review [--agent <name>] [--process <name>] [--component <substr>] [--event <substr>] [--level <level>] [--since <duration>] [--limit <n>] [--json]",
+        example: "ouro nerves-review --agent slugger --component daemon --event habit --since 30m --json",
+    },
     "work card": {
         category: "Tasks",
         description: "Show the agent's durable Work Card compiled from arc records.",
@@ -395,6 +401,11 @@ const SUBCOMMAND_HELP = {
         usage: "ouro account ensure [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
         example: "ouro account ensure --agent <agent> --owner-email you@example.com --source hey",
     },
+    "habit summary": {
+        description: "Read a habit run summary from receipts and session artifacts without contacting the daemon",
+        usage: "ouro habit summary [--agent <name>] (--run-id <id>|--habit <name>|--operation-id <id>) [--which latest|previous|latest-success|latest-failure] [--json]",
+        example: "ouro habit summary --agent slugger --operation-id habit:standup --which latest --json",
+    },
     "mail import-mbox": {
         description: "Import a HEY or other MBOX export into an existing delegated Mailroom source grant",
         usage: "ouro mail import-mbox (--file <path>|--discover) [--owner-email <email>] [--source <label>] [--agent <name>] [--foreground]",

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

@@ -110,6 +110,7 @@ function usage() {
         "  ouro habit create [--agent <name>] <name> [--cadence <interval>]",
         "  ouro habit runs [--agent <name>] [--limit <n>]",
         "  ouro habit inspect [--agent <name>] <runId>",
+        "  ouro habit summary [--agent <name>] (--run-id <id>|--habit <name>|--operation-id <id>) [--which latest|previous|latest-success|latest-failure] [--json]",
         "  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>]",
@@ -118,6 +119,7 @@ function usage() {
         "  ouro friend update <id> --trust <level> [--agent <name>]",
         "  ouro thoughts [--last <n>] [--json] [--follow] [--agent <name>]",
         "  ouro work card|gauntlet|sentinel [refresh] [--agent <name>] [--format text|json|--json]",
+        "  ouro nerves-review [--agent <name>] [--process <name>] [--component <substr>] [--event <substr>] [--level <level>] [--since <duration>] [--limit <n>] [--json]",
         "  ouro inner [--agent <name>]",
         "  ouro friend link <agent> --friend <id> --provider <p> --external-id <eid>",
         "  ouro friend unlink <agent> --friend <id> --provider <p> --external-id <eid>",
@@ -261,6 +263,53 @@ function parseHabitCommand(args) {
             throw new Error(`Usage\n${usage()}`);
         return { kind: "habit.inspect", ...(agent ? { agent } : {}), runId: positional[0] };
     }
+    if (sub === "summary") {
+        let runId;
+        let habitName;
+        let operationId;
+        let which;
+        let json = false;
+        const options = rest.slice(1);
+        for (let i = 0; i < options.length; i += 1) {
+            const option = options[i];
+            if (option === "--json") {
+                json = true;
+                continue;
+            }
+            if ((option === "--run-id" || option === "--habit" || option === "--operation-id" || option === "--which") && options[i + 1]) {
+                const value = options[++i];
+                if (option === "--run-id")
+                    runId = value;
+                if (option === "--habit")
+                    habitName = value;
+                if (option === "--operation-id")
+                    operationId = value;
+                if (option === "--which") {
+                    if (!["latest", "previous", "latest-success", "latest-failure"].includes(value)) {
+                        throw new Error("--which must be latest, previous, latest-success, or latest-failure");
+                    }
+                    which = value;
+                }
+                continue;
+            }
+            throw new Error(`Usage\n${usage()}`);
+        }
+        if (runId !== undefined && (habitName !== undefined || operationId !== undefined || which !== undefined)) {
+            throw new Error("--run-id cannot be combined with --habit, --operation-id, or --which");
+        }
+        if (runId === undefined && habitName === undefined && operationId === undefined) {
+            throw new Error("provide --run-id, --habit, or --operation-id");
+        }
+        return {
+            kind: "habit.summary",
+            ...(agent ? { agent } : {}),
+            ...(runId ? { runId } : {}),
+            ...(habitName ? { habitName } : {}),
+            ...(operationId ? { operationId } : {}),
+            ...(which ? { which } : {}),
+            json,
+        };
+    }
     throw new Error(`Usage\n${usage()}`);
 }
 function parseLinkCommand(args, kind = "friend.link") {
@@ -1537,6 +1586,57 @@ function parseBlueBubblesCommand(args) {
         ...(json ? { json: true } : {}),
     };
 }
+function parseNervesReviewCommand(args) {
+    const { agent, rest } = extractAgentFlag(args);
+    let processName = "daemon";
+    let component;
+    let event;
+    let level;
+    let since;
+    let limit;
+    let json = false;
+    for (let i = 0; i < rest.length; i += 1) {
+        const token = rest[i];
+        const next = rest[i + 1];
+        if (token === "--json") {
+            json = true;
+            continue;
+        }
+        if ((token === "--process" || token === "--component" || token === "--event" || token === "--level" || token === "--since" || token === "--limit") && next) {
+            if (token === "--process")
+                processName = next;
+            if (token === "--component")
+                component = next;
+            if (token === "--event")
+                event = next;
+            if (token === "--level")
+                level = next;
+            if (token === "--since")
+                since = next;
+            if (token === "--limit") {
+                const parsed = Number.parseInt(next, 10);
+                if (!Number.isInteger(parsed) || String(parsed) !== next || parsed < 1 || parsed > 1000) {
+                    throw new Error("--limit must be an integer between 1 and 1000");
+                }
+                limit = parsed;
+            }
+            i += 1;
+            continue;
+        }
+        throw new Error(`Usage\n${usage()}`);
+    }
+    return {
+        kind: "nerves-review",
+        ...(agent ? { agent } : {}),
+        process: processName,
+        ...(component ? { component } : {}),
+        ...(event ? { event } : {}),
+        ...(level ? { level } : {}),
+        ...(since ? { since } : {}),
+        ...(limit ? { limit } : {}),
+        json,
+    };
+}
 // ── Main dispatch ──
 function parseOuroCommand(args) {
     const [head, second] = args;
@@ -1704,6 +1804,8 @@ function parseOuroCommand(args) {
         return parseMessageCommand(args.slice(1));
     if (head === "poke")
         return parsePokeCommand(args.slice(1));
+    if (head === "nerves-review")
+        return parseNervesReviewCommand(args.slice(1));
     if (head === "link")
         return parseLinkCommand(args.slice(1));
     if (head === "mcp-serve")