@ouro.bot/cli 0.1.0-alpha.69 → 0.1.0-alpha.690

package/dist/arc/flight-recorder.js

@@ -0,0 +1,810 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHabitRunTrigger = isHabitRunTrigger;
+exports.flightRecorderLatestPath = flightRecorderLatestPath;
+exports.isFlightRecorderResume = isFlightRecorderResume;
+exports.readFlightRecorderResume = readFlightRecorderResume;
+exports.writeFlightRecorderResume = writeFlightRecorderResume;
+exports.recordFlightRecorderEvent = recordFlightRecorderEvent;
+exports.isSafeHabitRunId = isSafeHabitRunId;
+exports.readHabitRunReceipt = readHabitRunReceipt;
+exports.listHabitRunReceipts = listHabitRunReceipts;
+exports.writeHabitRunReceipt = writeHabitRunReceipt;
+exports.formatFlightRecorderResume = formatFlightRecorderResume;
+exports.createHabitRunId = createHabitRunId;
+const fs = __importStar(require("fs"));
+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"
+        || value === "poke"
+        || value === "overdue"
+        || value === "manual";
+}
+function flightRecorderDir(agentRoot) {
+    return path.join(agentRoot, "arc", "flight-recorder");
+}
+function eventsDir(agentRoot) {
+    return path.join(flightRecorderDir(agentRoot), "events");
+}
+function receiptsDir(agentRoot) {
+    return path.join(flightRecorderDir(agentRoot), "habit-receipts");
+}
+function habitReceiptPath(agentRoot, runId) {
+    return path.join(receiptsDir(agentRoot), `${runId}.json`);
+}
+function flightRecorderLatestPath(agentRoot) {
+    return path.join(flightRecorderDir(agentRoot), "latest.json");
+}
+function eventDay(recordedAt) {
+    return recordedAt.slice(0, 10) || "unknown";
+}
+function atomicWriteJson(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmpPath, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
+    fs.renameSync(tmpPath, filePath);
+}
+function cappedArray(values) {
+    return values.map((value) => (0, session_events_1.capStructuredRecordString)(value));
+}
+function normalizeEvent(input) {
+    const recordedAt = input.recordedAt ?? new Date().toISOString();
+    return {
+        schemaVersion: 1,
+        id: input.id ?? `fr-${(0, crypto_1.randomUUID)()}`,
+        kind: input.kind,
+        recordedAt,
+        ...(input.turnId ? { turnId: input.turnId } : {}),
+        ...(input.sessionRef ? { sessionRef: input.sessionRef } : {}),
+        summary: (0, session_events_1.capStructuredRecordString)(input.summary),
+        ...(input.currentAsk !== undefined ? { currentAsk: input.currentAsk ? (0, session_events_1.capStructuredRecordString)(input.currentAsk) : null } : {}),
+        ...(input.nextSafeAction !== undefined ? { nextSafeAction: input.nextSafeAction ? (0, session_events_1.capStructuredRecordString)(input.nextSafeAction) : null } : {}),
+        ...(input.stopBefore ? { stopBefore: cappedArray(input.stopBefore) } : {}),
+        ...(input.blockedBecause ? { blockedBecause: cappedArray(input.blockedBecause) } : {}),
+        ...(input.activeObligationIds ? { activeObligationIds: cappedArray(input.activeObligationIds) } : {}),
+        ...(input.activeReturnObligationIds ? { activeReturnObligationIds: cappedArray(input.activeReturnObligationIds) } : {}),
+        ...(input.activePacketIds ? { activePacketIds: cappedArray(input.activePacketIds) } : {}),
+        ...(input.openEvolutionCaseIds ? { openEvolutionCaseIds: cappedArray(input.openEvolutionCaseIds) } : {}),
+        ...(input.recentClaimIds ? { recentClaimIds: cappedArray(input.recentClaimIds) } : {}),
+        ...(input.unverifiedClaimIds ? { unverifiedClaimIds: cappedArray(input.unverifiedClaimIds) } : {}),
+        ...(input.producedRefs ? { producedRefs: input.producedRefs.map((ref) => ({ ...ref, locator: (0, session_events_1.capStructuredRecordString)(ref.locator) })) } : {}),
+        ...(input.meta ? { meta: (0, session_events_1.capStructuredRecordStringLeaves)(input.meta) } : {}),
+    };
+}
+function degradedResume(issues) {
+    return {
+        schemaVersion: 1,
+        hasCompleteState: false,
+        canContinue: false,
+        missing: ["currentAsk", "nextSafeAction"],
+        gaps: [],
+        currentAsk: { value: null, confidence: "unknown", sourceEventIds: [] },
+        nextSafeAction: { value: null, stopBefore: [], sourceEventIds: [] },
+        blockedBecause: [],
+        activeObligationIds: [],
+        activeReturnObligationIds: [],
+        activePacketIds: [],
+        openEvolutionCaseIds: [],
+        recentClaimIds: [],
+        unverifiedClaimIds: [],
+        lastSafeCheckpoint: { turnId: null, sessionRef: null, recordedAt: null, sourceEventIds: [] },
+        recorderHealth: {
+            status: "degraded",
+            issues,
+        },
+    };
+}
+/* v8 ignore start -- defensive schema guard fan-out; tests cover valid load and malformed-shape degradation @preserve */
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isNullableString(value) {
+    return value === null || typeof value === "string";
+}
+function isFlightRecorderResume(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    const currentAsk = record.currentAsk;
+    const nextSafeAction = record.nextSafeAction;
+    const lastSafeCheckpoint = record.lastSafeCheckpoint;
+    const recorderHealth = record.recorderHealth;
+    return record.schemaVersion === 1
+        && typeof record.hasCompleteState === "boolean"
+        && typeof record.canContinue === "boolean"
+        && isStringArray(record.missing)
+        && isStringArray(record.gaps)
+        && !!currentAsk
+        && typeof currentAsk === "object"
+        && !Array.isArray(currentAsk)
+        && isNullableString(currentAsk.value)
+        && (currentAsk.confidence === "current" || currentAsk.confidence === "stale_risky" || currentAsk.confidence === "unknown")
+        && isStringArray(currentAsk.sourceEventIds)
+        && !!nextSafeAction
+        && typeof nextSafeAction === "object"
+        && !Array.isArray(nextSafeAction)
+        && isNullableString(nextSafeAction.value)
+        && isStringArray(nextSafeAction.stopBefore)
+        && isStringArray(nextSafeAction.sourceEventIds)
+        && isStringArray(record.blockedBecause)
+        && isStringArray(record.activeObligationIds)
+        && isStringArray(record.activeReturnObligationIds)
+        && isStringArray(record.activePacketIds)
+        && isStringArray(record.openEvolutionCaseIds)
+        && isStringArray(record.recentClaimIds)
+        && isStringArray(record.unverifiedClaimIds)
+        && !!lastSafeCheckpoint
+        && typeof lastSafeCheckpoint === "object"
+        && !Array.isArray(lastSafeCheckpoint)
+        && isNullableString(lastSafeCheckpoint.turnId)
+        && isNullableString(lastSafeCheckpoint.sessionRef)
+        && isNullableString(lastSafeCheckpoint.recordedAt)
+        && isStringArray(lastSafeCheckpoint.sourceEventIds)
+        && !!recorderHealth
+        && typeof recorderHealth === "object"
+        && !Array.isArray(recorderHealth)
+        && (recorderHealth.status === "ok" || recorderHealth.status === "degraded" || recorderHealth.status === "unavailable")
+        && isStringArray(recorderHealth.issues);
+}
+/* v8 ignore stop */
+/* v8 ignore start -- semantic invariant fan-out is defensive; regression tests cover unsafe continuation normalization @preserve */
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function normalizeResumeInvariants(resume) {
+    const hasCurrentAsk = nonEmpty(resume.currentAsk.value);
+    const hasNextSafeAction = nonEmpty(resume.nextSafeAction.value);
+    const hasCompleteState = hasCurrentAsk && hasNextSafeAction;
+    const missing = [
+        ...(hasCurrentAsk ? [] : ["currentAsk"]),
+        ...(hasNextSafeAction ? [] : ["nextSafeAction"]),
+    ];
+    const missingChanged = resume.missing.join("\n") !== missing.join("\n");
+    const issues = [
+        ...(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"] : []),
+        ...(resume.canContinue && resume.recorderHealth.status !== "ok" ? ["canContinue true while recorder health is not ok"] : []),
+    ];
+    if (issues.length === 0 && resume.hasCompleteState === hasCompleteState && !missingChanged)
+        return resume;
+    return {
+        ...resume,
+        hasCompleteState,
+        canContinue: issues.length === 0 ? resume.canContinue : false,
+        missing,
+        currentAsk: {
+            ...resume.currentAsk,
+            confidence: hasCurrentAsk ? resume.currentAsk.confidence : "unknown",
+        },
+        recorderHealth: issues.length > 0
+            ? {
+                status: resume.recorderHealth.status === "unavailable" ? "unavailable" : "degraded",
+                issues: uniqueStrings([...resume.recorderHealth.issues, ...issues]),
+            }
+            : resume.recorderHealth,
+    };
+}
+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;
+    const currentAskSourceEventIds = event.currentAsk !== undefined ? [event.id] : previous.currentAsk.sourceEventIds;
+    const nextSafeActionSourceEventIds = event.nextSafeAction !== undefined ? [event.id] : previous.nextSafeAction.sourceEventIds;
+    const inheritedBlocker = event.blockedBecause === undefined && previous.blockedBecause.length > 0;
+    const lastSafeCheckpointEventIds = inheritedBlocker
+        ? uniqueStrings([...previous.lastSafeCheckpoint.sourceEventIds, event.id])
+        : [event.id];
+    const hasCurrentAsk = typeof currentAskValue === "string" && currentAskValue.trim().length > 0;
+    const hasNextSafeAction = typeof nextSafeActionValue === "string" && nextSafeActionValue.trim().length > 0;
+    return {
+        ...previous,
+        hasCompleteState: hasCurrentAsk && hasNextSafeAction,
+        canContinue: hasCurrentAsk && hasNextSafeAction && (event.blockedBecause?.length ?? previous.blockedBecause.length) === 0,
+        missing: [
+            ...(hasCurrentAsk ? [] : ["currentAsk"]),
+            ...(hasNextSafeAction ? [] : ["nextSafeAction"]),
+        ],
+        currentAsk: {
+            value: currentAskValue,
+            confidence: hasCurrentAsk ? "current" : "unknown",
+            sourceEventIds: currentAskSourceEventIds,
+        },
+        nextSafeAction: {
+            value: nextSafeActionValue,
+            stopBefore: event.stopBefore ?? previous.nextSafeAction.stopBefore,
+            sourceEventIds: nextSafeActionSourceEventIds,
+        },
+        blockedBecause: event.blockedBecause ?? previous.blockedBecause,
+        activeObligationIds: event.activeObligationIds ?? previous.activeObligationIds,
+        activeReturnObligationIds: event.activeReturnObligationIds ?? previous.activeReturnObligationIds,
+        activePacketIds: event.activePacketIds ?? previous.activePacketIds,
+        openEvolutionCaseIds: event.openEvolutionCaseIds ?? previous.openEvolutionCaseIds,
+        recentClaimIds: event.recentClaimIds ?? previous.recentClaimIds,
+        unverifiedClaimIds: event.unverifiedClaimIds ?? previous.unverifiedClaimIds,
+        lastSafeCheckpoint: {
+            turnId: event.turnId ?? previous.lastSafeCheckpoint.turnId,
+            sessionRef: event.sessionRef ?? previous.lastSafeCheckpoint.sessionRef,
+            recordedAt: event.recordedAt,
+            sourceEventIds: lastSafeCheckpointEventIds,
+        },
+        recorderHealth: { status: "ok", issues: [] },
+    };
+}
+function readFlightRecorderResume(agentRoot) {
+    const latestPath = flightRecorderLatestPath(agentRoot);
+    try {
+        const parsed = JSON.parse(fs.readFileSync(latestPath, "utf-8"));
+        if (!isFlightRecorderResume(parsed)) {
+            throw new Error("latest.json has invalid flight-recorder resume shape");
+        }
+        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",
+            message: "flight recorder resume read",
+            meta: { agentRoot, canContinue: resume.canContinue, hasCompleteState: resume.hasCompleteState },
+        });
+        return resume;
+    }
+    catch (error) {
+        const issue = fs.existsSync(latestPath)
+            ? `latest.json unreadable: ${error instanceof Error ? error.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(error)}`
+            : "latest.json missing";
+        (0, runtime_1.emitNervesEvent)({
+            component: "mind",
+            event: "mind.flight_recorder_resume_read",
+            message: "flight recorder resume missing or degraded",
+            meta: { agentRoot, issue },
+        });
+        return degradedResume([issue]);
+    }
+}
+function writeFlightRecorderResume(agentRoot, 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",
+        message: "flight recorder resume written",
+        meta: { agentRoot, canContinue: safeResume.canContinue, hasCompleteState: safeResume.hasCompleteState },
+    });
+}
+function recordFlightRecorderEvent(agentRoot, input) {
+    const event = normalizeEvent(input);
+    fs.mkdirSync(eventsDir(agentRoot), { recursive: true });
+    fs.appendFileSync(path.join(eventsDir(agentRoot), `${eventDay(event.recordedAt)}.jsonl`), `${JSON.stringify(event)}\n`, "utf-8");
+    const latest = latestFromEvent(event, readFlightRecorderResume(agentRoot));
+    writeFlightRecorderResume(agentRoot, latest);
+    (0, runtime_1.emitNervesEvent)({
+        component: "mind",
+        event: "mind.flight_recorder_event_recorded",
+        message: "flight recorder event recorded",
+        meta: { agentRoot, eventId: event.id, kind: event.kind },
+    });
+    return event;
+}
+function isSafeHabitRunId(value) {
+    return typeof value === "string"
+        && /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/.test(value)
+        && !value.includes("..");
+}
+function isPlainRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isProducedRefArray(value) {
+    return Array.isArray(value)
+        && value.every((entry) => isPlainRecord(entry)
+            && (entry.kind === "arc"
+                || entry.kind === "desk_task"
+                || entry.kind === "desk_record"
+                || entry.kind === "claim"
+                || entry.kind === "surface"
+                || entry.kind === "none")
+            && typeof entry.locator === "string");
+}
+function isHabitSurfaceAttemptArray(value) {
+    return Array.isArray(value)
+        && value.every((entry) => isPlainRecord(entry)
+            && typeof entry.recipient === "string"
+            && typeof entry.channel === "string"
+            && (entry.reason === "needed_input"
+                || entry.reason === "status"
+                || entry.reason === "answer"
+                || entry.reason === "blocked"
+                || entry.reason === "other")
+            && (entry.result === "sent"
+                || entry.result === "delivered"
+                || entry.result === "delivered_now"
+                || entry.result === "queued"
+                || entry.result === "deferred"
+                || entry.result === "blocked"
+                || entry.result === "failed"
+                || entry.result === "unavailable")
+            && (entry.routeKind === undefined
+                || entry.routeKind === "family"
+                || entry.routeKind === "originator"
+                || entry.routeKind === "extra")
+            && (entry.rawStatus === undefined || typeof entry.rawStatus === "string")
+            && (entry.error === undefined || typeof entry.error === "string"));
+}
+function isHabitReturnRouteArray(value) {
+    return Array.isArray(value)
+        && value.every((entry) => isPlainRecord(entry)
+            && (entry.kind === "family" || entry.kind === "originator" || entry.kind === "extra")
+            && typeof entry.recipient === "string"
+            && (entry.status === "allowed" || entry.status === "unresolved")
+            && (entry.friendId === undefined || typeof entry.friendId === "string")
+            && (entry.channel === undefined || typeof entry.channel === "string")
+            && (entry.key === undefined || typeof entry.key === "string")
+            && (entry.reason === undefined || typeof entry.reason === "string"));
+}
+function isHabitPermissionEnvelope(value) {
+    if (!isPlainRecord(value))
+        return false;
+    return value.schemaVersion === 1
+        && typeof value.canMessageOutward === "boolean"
+        && isHabitReturnRouteArray(value.returnRoutes)
+        && isStringArray(value.deniedTools)
+        && isStringArray(value.warnings);
+}
+function isHabitToolPolicy(value) {
+    if (!isPlainRecord(value))
+        return false;
+    return (value.requestedTools === null || isStringArray(value.requestedTools))
+        && isStringArray(value.grantedTools)
+        && 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;
+    return value.schemaVersion === 2
+        && isSafeHabitRunId(value.runId)
+        && typeof value.sessionId === "string"
+        && typeof value.habitName === "string"
+        && (value.trigger === "cron"
+            || value.trigger === "launchd"
+            || value.trigger === "poke"
+            || value.trigger === "overdue"
+            || value.trigger === "manual")
+        && typeof value.startedAt === "string"
+        && typeof value.endedAt === "string"
+        && (value.outcome === "no_change"
+            || value.outcome === "wrote_arc"
+            || value.outcome === "updated_desk"
+            || value.outcome === "wrote_record"
+            || value.outcome === "surfaced"
+            || value.outcome === "blocked"
+            || value.outcome === "error")
+        && typeof value.definitionLocator === "string"
+        && typeof value.sessionLocator === "string"
+        && 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);
+}
+function isLegacyHabitRunReceipt(value) {
+    if (!isPlainRecord(value))
+        return false;
+    return value.schemaVersion === 1
+        && isSafeHabitRunId(value.runId)
+        && typeof value.habitName === "string"
+        && (value.trigger === "cron"
+            || value.trigger === "launchd"
+            || value.trigger === "poke"
+            || value.trigger === "overdue"
+            || value.trigger === "manual")
+        && typeof value.startedAt === "string"
+        && typeof value.endedAt === "string"
+        && (value.outcome === "no_change"
+            || value.outcome === "wrote_arc"
+            || value.outcome === "updated_desk"
+            || value.outcome === "wrote_record"
+            || value.outcome === "surfaced"
+            || value.outcome === "blocked"
+            || value.outcome === "error")
+        && isProducedRefArray(value.producedRefs)
+        && isHabitSurfaceAttemptArray(value.surfaceAttempts)
+        && isStringArray(value.errors);
+}
+function warnMalformedHabitReceipt(agentRoot, runId, reason) {
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "mind",
+        event: "mind.flight_recorder_habit_receipt_malformed",
+        message: "flight recorder habit receipt malformed",
+        meta: { agentRoot, runId: (0, session_events_1.capStructuredRecordString)(runId), reason },
+    });
+}
+function normalizeLegacyHabitRunReceipt(receipt) {
+    const sawSurface = receipt.surfaceAttempts.length > 0 || receipt.producedRefs.some((ref) => ref.kind === "surface");
+    return {
+        schemaVersion: 2,
+        runId: receipt.runId,
+        sessionId: receipt.runId,
+        habitName: receipt.habitName,
+        trigger: receipt.trigger,
+        startedAt: receipt.startedAt,
+        endedAt: receipt.endedAt,
+        outcome: receipt.outcome,
+        definitionLocator: `habits/${receipt.habitName}.md`,
+        sessionLocator: `state/habit-sessions/${receipt.runId}/session.json`,
+        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,
+            canMessageOutward: sawSurface,
+            returnRoutes: [],
+            deniedTools: sawSurface ? [] : ["send_message", "surface"],
+            warnings: ["legacy receipt normalized without habit permission envelope"],
+        },
+        toolPolicy: {
+            requestedTools: null,
+            grantedTools: sawSurface ? ["surface"] : [],
+            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),
+        definitionLocator: (0, session_events_1.capStructuredRecordString)(receipt.definitionLocator),
+        sessionLocator: (0, session_events_1.capStructuredRecordString)(receipt.sessionLocator),
+        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) => ({
+                ...route,
+                recipient: (0, session_events_1.capStructuredRecordString)(route.recipient),
+                ...(route.friendId ? { friendId: (0, session_events_1.capStructuredRecordString)(route.friendId) } : {}),
+                ...(route.channel ? { channel: (0, session_events_1.capStructuredRecordString)(route.channel) } : {}),
+                ...(route.key ? { key: (0, session_events_1.capStructuredRecordString)(route.key) } : {}),
+                ...(route.reason ? { reason: (0, session_events_1.capStructuredRecordString)(route.reason) } : {}),
+            })),
+            deniedTools: cappedArray(receipt.permissionEnvelope.deniedTools),
+            warnings: cappedArray(receipt.permissionEnvelope.warnings),
+        },
+        toolPolicy: {
+            requestedTools: receipt.toolPolicy.requestedTools ? cappedArray(receipt.toolPolicy.requestedTools) : null,
+            grantedTools: cappedArray(receipt.toolPolicy.grantedTools),
+            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,
+            recipient: (0, session_events_1.capStructuredRecordString)(attempt.recipient),
+            channel: (0, session_events_1.capStructuredRecordString)(attempt.channel),
+            ...(attempt.rawStatus ? { rawStatus: (0, session_events_1.capStructuredRecordString)(attempt.rawStatus) } : {}),
+            ...(attempt.error ? { error: (0, session_events_1.capStructuredRecordString)(attempt.error) } : {}),
+        })),
+        errors: receipt.errors.map((error) => (0, session_events_1.capStructuredRecordString)(error)),
+    };
+}
+function normalizeHabitRunReceiptForWrite(receipt) {
+    return capHabitRunReceipt(receipt.schemaVersion === 1 ? normalizeLegacyHabitRunReceipt(receipt) : receipt);
+}
+function readHabitRunReceipt(agentRoot, runId) {
+    if (!isSafeHabitRunId(runId)) {
+        warnMalformedHabitReceipt(agentRoot, runId, "unsafe run id");
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(habitReceiptPath(agentRoot, runId), "utf-8"));
+        const receipt = isHabitRunReceipt(parsed)
+            ? parsed
+            : isLegacyHabitRunReceipt(parsed)
+                ? normalizeLegacyHabitRunReceipt(parsed)
+                : null;
+        if (!receipt) {
+            warnMalformedHabitReceipt(agentRoot, runId, "invalid habit receipt shape");
+            return null;
+        }
+        (0, runtime_1.emitNervesEvent)({
+            component: "mind",
+            event: "mind.flight_recorder_habit_receipt_read",
+            message: "flight recorder habit receipt read",
+            meta: { agentRoot, runId },
+        });
+        return capHabitRunReceipt(receipt);
+    }
+    catch (error) {
+        warnMalformedHabitReceipt(agentRoot, runId, error instanceof Error ? error.message : /* v8 ignore next -- defensive: non-Error catch branch @preserve */ String(error));
+        return null;
+    }
+}
+function listHabitRunReceipts(agentRoot, options = {}) {
+    const dir = receiptsDir(agentRoot);
+    if (!fs.existsSync(dir))
+        return [];
+    const receipts = fs.readdirSync(dir)
+        .filter((fileName) => fileName.endsWith(".json"))
+        .map((fileName) => readHabitRunReceipt(agentRoot, path.basename(fileName, ".json")))
+        .filter((receipt) => receipt !== null)
+        .sort((left, right) => right.endedAt.localeCompare(left.endedAt) || right.runId.localeCompare(left.runId));
+    return typeof options.limit === "number" && options.limit >= 0 ? receipts.slice(0, options.limit) : receipts;
+}
+function writeHabitRunReceipt(agentRoot, receipt) {
+    fs.mkdirSync(receiptsDir(agentRoot), { recursive: true });
+    const safeReceipt = normalizeHabitRunReceiptForWrite(receipt);
+    if (!isSafeHabitRunId(safeReceipt.runId)) {
+        warnMalformedHabitReceipt(agentRoot, safeReceipt.runId, "unsafe run id");
+        throw new Error(`unsafe habit run id: ${safeReceipt.runId}`);
+    }
+    atomicWriteJson(habitReceiptPath(agentRoot, safeReceipt.runId), safeReceipt);
+    recordFlightRecorderEvent(agentRoot, {
+        kind: "habit_run",
+        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`),
+            operationId: safeReceipt.operationId ?? null,
+        },
+    });
+    (0, runtime_1.emitNervesEvent)({
+        component: "mind",
+        event: "mind.flight_recorder_habit_receipt_written",
+        message: "flight recorder habit receipt written",
+        meta: { agentRoot, runId: safeReceipt.runId, habitName: safeReceipt.habitName, outcome: safeReceipt.outcome },
+    });
+}
+function formatFlightRecorderResume(resume) {
+    const lines = ["## Arc resume"];
+    lines.push(`can continue: ${resume.canContinue ? "yes" : "no"}`);
+    lines.push(`complete state: ${resume.hasCompleteState ? "yes" : "no"}`);
+    if (resume.currentAsk.value)
+        lines.push(`current ask: ${resume.currentAsk.value}`);
+    if (resume.nextSafeAction.value)
+        lines.push(`next safe action: ${resume.nextSafeAction.value}`);
+    if (resume.nextSafeAction.stopBefore.length > 0)
+        lines.push(`stop before: ${resume.nextSafeAction.stopBefore.join(", ")}`);
+    if (resume.blockedBecause.length > 0)
+        lines.push(`blocked: ${resume.blockedBecause.join("; ")}`);
+    if (resume.missing.length > 0)
+        lines.push(`missing: ${resume.missing.join(", ")}`);
+    if (resume.gaps.length > 0)
+        lines.push(`gaps: ${resume.gaps.join("; ")}`);
+    if (resume.activeObligationIds.length > 0)
+        lines.push(`obligations: ${resume.activeObligationIds.join(", ")}`);
+    if (resume.activeReturnObligationIds.length > 0)
+        lines.push(`return obligations: ${resume.activeReturnObligationIds.join(", ")}`);
+    if (resume.activePacketIds.length > 0)
+        lines.push(`packets: ${resume.activePacketIds.join(", ")}`);
+    if (resume.unverifiedClaimIds.length > 0)
+        lines.push(`unverified claims: ${resume.unverifiedClaimIds.join(", ")}`);
+    if (resume.recorderHealth.status !== "ok") {
+        lines.push(`recorder health: ${resume.recorderHealth.status} (${resume.recorderHealth.issues.join("; ")})`);
+    }
+    return lines.join("\n");
+}
+function createHabitRunId(habitName, now = new Date()) {
+    const safeName = habitName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "habit";
+    return `${now.toISOString().replace(/[:.]/g, "-")}-${safeName}-${(0, crypto_1.randomUUID)().slice(0, 8)}`;
+}