@ouro.bot/cli 0.1.0-alpha.696 → 0.1.0-alpha.697

package/dist/heart/daemon/doctor.js

@@ -13,6 +13,7 @@ exports.checkDaemon = checkDaemon;
 exports.checkAgents = checkAgents;
 exports.checkSenses = checkSenses;
 exports.checkHabits = checkHabits;
+exports.checkRsvp = checkRsvp;
 exports.checkSecurity = checkSecurity;
 exports.checkTrips = checkTrips;
 exports.checkMailroom = checkMailroom;
@@ -28,6 +29,9 @@ const machine_identity_1 = require("../machine-identity");
 const habit_parser_1 = require("../habits/habit-parser");
 const cadence_1 = require("./cadence");
 const nerves_1 = require("../../nerves");
+const config_1 = require("../../rsvp/config");
+const cutover_1 = require("../../rsvp/cutover");
+const diagnostics_1 = require("../../rsvp/diagnostics");
 const DEFAULT_BLUEBUBBLES_REQUEST_TIMEOUT_MS = 30_000;
 // ── Category checkers ──
 function checkCliPath(deps) {
@@ -397,6 +401,152 @@ function checkHabits(deps) {
     }
     return { name: "Habits", checks };
 }
+function hasRsvpHabitSignal(deps, agentPath) {
+    const habitsDir = `${agentPath}/habits`;
+    if (!deps.existsSync(habitsDir))
+        return false;
+    try {
+        return deps.readdirSync(habitsDir).some((name) => name.toLowerCase().includes("rsvp") && name.endsWith(".md"));
+    }
+    catch {
+        return false;
+    }
+}
+function rsvpDoctorLabel(agentDir, checkId) {
+    const suffix = {
+        "rsvp.native_config": "RSVP native config",
+        "rsvp.aisleplanner_source": "RSVP AislePlanner source",
+        "rsvp.aisleplanner_credentials": "RSVP AislePlanner credentials",
+        "rsvp.bluebubbles_route": "RSVP BlueBubbles route",
+        "rsvp.bluebubbles_attachment": "RSVP BlueBubbles attachment",
+    };
+    return `${agentDir} ${suffix[checkId]}`;
+}
+function rsvpDoctorId(checkId) {
+    const ids = {
+        "rsvp.native_config": "rsvp.native_config",
+        "rsvp.aisleplanner_source": "rsvp.aisleplanner.source",
+        "rsvp.aisleplanner_credentials": "rsvp.aisleplanner.credentials",
+        "rsvp.bluebubbles_route": "rsvp.bluebubbles.route",
+        "rsvp.bluebubbles_attachment": "rsvp.bluebubbles.attachment",
+    };
+    return ids[checkId];
+}
+function rsvpDoctorDetail(readinessCheck) {
+    return readinessCheck.id === "rsvp.bluebubbles_route" && readinessCheck.status === "pass"
+        ? "configured"
+        : readinessCheck.detail;
+}
+function doctorStatus(status) {
+    return status;
+}
+function discoverRsvpCutoverLegacyRoot(deps, config) {
+    const configured = typeof config?.cutover?.legacyRoot === "string" ? config.cutover.legacyRoot.trim() : "";
+    if (configured)
+        return configured;
+    if (deps.rsvpCutoverLegacyRoot)
+        return deps.rsvpCutoverLegacyRoot;
+    const candidate = `${deps.homedir}/Projects/rsvp-tracker`;
+    return deps.existsSync(`${candidate}/config.json`) ? candidate : null;
+}
+function rsvpCutoverDetail(checks, sendAllowed, denialCount) {
+    return [
+        `sendAllowed=${sendAllowed}`,
+        `launchAgentInactive=${checks.launchAgentInactive}`,
+        `legacyProcessInactive=${checks.legacyProcessInactive}`,
+        `legacyConfigSendInactive=${checks.legacyConfigSendInactive}`,
+        `legacyLiveSendInactive=${checks.legacyLiveSendInactive}`,
+        `nativeBlueBubblesCredentialHealthy=${checks.nativeBlueBubblesCredentialHealthy}`,
+        `denialCount=${denialCount}`,
+    ].join("; ");
+}
+async function checkRsvp(deps) {
+    const checks = [];
+    const agents = discoverAgents(deps);
+    if (agents.length === 0) {
+        checks.push({ label: "RSVP", status: "warn", detail: "no agent bundles found" });
+        return { name: "RSVP", checks };
+    }
+    for (const agentDir of agents) {
+        const agentName = agentDir.replace(/\.ouro$/, "");
+        const agentPath = `${deps.bundlesRoot}/${agentDir}`;
+        const config = (0, config_1.readRsvpConfig)(agentPath);
+        const hasRsvpSignal = config.ok || hasRsvpHabitSignal(deps, agentPath);
+        if (!hasRsvpSignal) {
+            checks.push({ label: `${agentDir} RSVP`, status: "pass", detail: "not configured" });
+            continue;
+        }
+        const machineId = (0, machine_identity_1.loadOrCreateMachineIdentity)({ homeDir: deps.homedir }).machineId;
+        const runtimeConfig = await (0, runtime_credentials_1.refreshRuntimeCredentialConfig)(agentName, { preserveCachedOnFailure: true });
+        const machineRuntimeConfig = await (0, runtime_credentials_1.refreshMachineRuntimeCredentialConfig)(agentName, machineId, { preserveCachedOnFailure: true });
+        const readiness = (0, config_1.validateRsvpReadiness)({
+            agent: agentName,
+            agentRoot: agentPath,
+            runtimeConfig,
+            machineRuntimeConfig,
+            config,
+        });
+        for (const readinessCheck of readiness.checks) {
+            checks.push({
+                id: rsvpDoctorId(readinessCheck.id),
+                label: rsvpDoctorLabel(agentDir, readinessCheck.id),
+                status: readinessCheck.status === "pass" ? "pass" : "fail",
+                detail: rsvpDoctorDetail(readinessCheck),
+            });
+        }
+        const attachment = readiness.checks.find((check) => check.id === "rsvp.bluebubbles_attachment");
+        if (attachment) {
+            checks.push({
+                id: "rsvp.bluebubbles.attachment_identity",
+                label: `${agentDir} RSVP BlueBubbles attachment identity`,
+                status: attachment.status === "pass" ? "pass" : "fail",
+                detail: attachment.status === "pass" ? "machine attachment credential present" : attachment.detail,
+            });
+        }
+        const diagnostics = (0, diagnostics_1.collectRsvpDiagnostics)(agentPath, deps);
+        checks.push({
+            id: "rsvp.context_packet_ledger",
+            label: `${agentDir} RSVP context packet ledger`,
+            status: doctorStatus(diagnostics.contextPacketLedger.status),
+            detail: diagnostics.contextPacketLedger.detail,
+        }, {
+            id: "rsvp.habit.schedule",
+            label: `${agentDir} RSVP habit schedule`,
+            status: doctorStatus(diagnostics.habitSchedule.status),
+            detail: diagnostics.habitSchedule.detail,
+        }, {
+            id: "rsvp.latest_fetch",
+            label: `${agentDir} RSVP latest fetch`,
+            status: doctorStatus(diagnostics.latestFetch.status),
+            detail: diagnostics.latestFetch.detail,
+        }, {
+            id: "rsvp.delivery.reconciliation",
+            label: `${agentDir} RSVP delivery reconciliation`,
+            status: doctorStatus(diagnostics.deliveryReconciliation.status),
+            detail: diagnostics.deliveryReconciliation.detail,
+        }, {
+            id: "rsvp.spend_timeline",
+            label: `${agentDir} RSVP spend timeline`,
+            status: doctorStatus(diagnostics.spendTimeline.status),
+            detail: diagnostics.spendTimeline.detail,
+        });
+        const legacyRoot = discoverRsvpCutoverLegacyRoot(deps, config.ok ? config.config : undefined);
+        if (config.ok && legacyRoot) {
+            const cutover = await (0, cutover_1.checkRsvpCutover)({
+                agent: agentName,
+                legacyRoot,
+                ...(deps.rsvpCutoverDeps ? { deps: deps.rsvpCutoverDeps } : {}),
+            });
+            checks.push({
+                id: "rsvp.cutover.live_send_preflight",
+                label: `${agentDir} RSVP legacy live-send preflight`,
+                status: cutover.sendAllowed ? "pass" : "fail",
+                detail: rsvpCutoverDetail(cutover.checks, cutover.sendAllowed, cutover.denialReasons.length),
+            });
+        }
+    }
+    return { name: "RSVP", checks };
+}
 function checkSecurity(deps) {
     const checks = [];
     const agents = discoverAgents(deps);
@@ -934,6 +1084,7 @@ const CATEGORY_CHECKERS = [
     { name: "Agents", fn: checkAgents },
     { name: "Senses", fn: checkSenses },
     { name: "Habits", fn: checkHabits },
+    { name: "RSVP", fn: checkRsvp },
     { name: "Security", fn: checkSecurity },
     { name: "Trips", fn: checkTrips },
     { name: "Mailroom", fn: checkMailroom },

package/dist/heart/daemon/stale-bundle-prune.js

@@ -39,13 +39,16 @@ const path = __importStar(require("path"));
 const identity_1 = require("../identity");
 const runtime_1 = require("../../nerves/runtime");
 /**
- * Scan the bundles root for `.ouro` directories that have no `agent.json`
- * file (definitively dead ephemeral bundles) and delete them.
+ * Scan the bundles root for `.ouro` directories that have no bundle contract
+ * or durable state markers (definitively dead ephemeral bundles) and delete
+ * them.
  *
  * Returns a list of pruned bundle directory names (e.g. `["stale.ouro"]`)
  * for display purposes. Bundles that have `agent.json` -- even if disabled
- * -- are never deleted. Errors on individual bundles are swallowed so that
- * one permission-denied doesn't block pruning the rest.
+ * -- are never deleted. Task-doc-only bundles are also durable work state, so
+ * directories with state roots such as `tasks`, `desk`, `arc`, `state`, or
+ * `.git` are preserved. Errors on individual bundles are swallowed so that one
+ * permission-denied doesn't block pruning the rest.
  */
 function pruneStaleEphemeralBundles(deps = {}) {
     const bundlesRoot = deps.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
@@ -64,8 +67,7 @@ function pruneStaleEphemeralBundles(deps = {}) {
         if (!entry.isDirectory() || !entry.name.endsWith(".ouro"))
             continue;
         const bundlePath = path.join(bundlesRoot, entry.name);
-        const agentJsonPath = path.join(bundlePath, "agent.json");
-        if (existsSync(agentJsonPath))
+        if (hasDurableBundleMarker(bundlePath, existsSync))
             continue;
         try {
             rmSync(bundlePath, { recursive: true, force: true });
@@ -94,3 +96,18 @@ function pruneStaleEphemeralBundles(deps = {}) {
     }
     return pruned;
 }
+const DURABLE_BUNDLE_MARKERS = [
+    "agent.json",
+    "tasks",
+    "desk",
+    "arc",
+    "state",
+    "habits",
+    "friends",
+    "facts",
+    "vault",
+    ".git",
+];
+function hasDurableBundleMarker(bundlePath, existsSync) {
+    return DURABLE_BUNDLE_MARKERS.some((marker) => existsSync(path.join(bundlePath, marker)));
+}

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

@@ -38,6 +38,7 @@ exports.renderHabitFile = renderHabitFile;
 const path = __importStar(require("path"));
 const frontmatter_1 = require("../../util/frontmatter");
 const runtime_1 = require("../../nerves/runtime");
+const habit_policy_1 = require("../../rsvp/habit-policy");
 function isHabitStatus(value) {
     return value === "active" || value === "paused";
 }
@@ -157,7 +158,8 @@ function parseHabitFile(content, filePath) {
     const lastRun = typeof rawLastRun === "string" && rawLastRun.length > 0 ? rawLastRun : null;
     const rawCreated = frontmatter.created;
     const created = typeof rawCreated === "string" && rawCreated.length > 0 ? rawCreated : null;
-    const tools = parseToolsField(frontmatter.tools);
+    const rsvp = (0, habit_policy_1.parseRsvpHabitMetadata)(frontmatter.rsvp);
+    const tools = rsvp ? [...habit_policy_1.RSVP_HABIT_ALLOWED_TOOLS] : parseToolsField(frontmatter.tools);
     const origin = parseOrigin(frontmatter.origin);
     const surface = parseSurface(frontmatter.surface);
     const continuity = parseContinuity(frontmatter.continuity);
@@ -169,6 +171,7 @@ function parseHabitFile(content, filePath) {
         lastRun,
         created,
         tools,
+        ...(rsvp ? { rsvp } : {}),
         origin,
         surface,
         continuity,

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

@@ -39,6 +39,7 @@ const runtime_1 = require("../../nerves/runtime");
 const habit_parser_1 = require("./habit-parser");
 const habit_runtime_state_1 = require("./habit-runtime-state");
 const cadence_1 = require("../daemon/cadence");
+const habit_policy_1 = require("../../rsvp/habit-policy");
 const WATCH_DEBOUNCE_MS = 200;
 class HabitScheduler {
     agent;
@@ -97,33 +98,21 @@ class HabitScheduler {
                 continue;
             if (!habit.cadence)
                 continue;
-            const cadenceMs = (0, cadence_1.parseCadenceToMs)(habit.cadence);
-            if (cadenceMs === null)
+            if (this.rejectInvalidRsvpHabit(habit))
                 continue;
             const nowMs = this.deps.now();
-            if (habit.lastRun === null) {
-                (0, runtime_1.emitNervesEvent)({
-                    component: "daemon",
-                    event: "daemon.habit_fire",
-                    message: "firing overdue habit (never run)",
-                    meta: { habitName: habit.name, agent: this.agent },
-                });
-                this.onHabitFire(habit.name, "overdue", {
-                    occurrenceId: this.overdueOccurrenceId(habit),
-                });
+            const dueState = (0, cadence_1.evaluateCadenceDue)(habit.cadence, habit.lastRun, nowMs);
+            if (dueState === null)
                 continue;
-            }
-            const lastRunMs = new Date(habit.lastRun).getTime();
-            const elapsed = nowMs - lastRunMs;
-            if (elapsed >= cadenceMs) {
+            if (dueState.due) {
                 (0, runtime_1.emitNervesEvent)({
                     component: "daemon",
                     event: "daemon.habit_fire",
-                    message: "firing overdue habit",
-                    meta: { habitName: habit.name, agent: this.agent, elapsedMs: elapsed },
+                    message: habit.lastRun === null ? "firing overdue habit (never run)" : "firing overdue habit",
+                    meta: { habitName: habit.name, agent: this.agent, elapsedMs: dueState.elapsedMs },
                 });
                 this.onHabitFire(habit.name, "overdue", {
-                    occurrenceId: this.overdueOccurrenceId(habit),
+                    occurrenceId: dueState.occurrenceId ?? this.overdueOccurrenceId(habit),
                 });
             }
         }
@@ -150,18 +139,11 @@ class HabitScheduler {
                 continue;
             if (!habit.cadence)
                 continue;
-            const cadenceMs = (0, cadence_1.parseCadenceToMs)(habit.cadence);
-            if (cadenceMs === null)
+            if (this.rejectInvalidRsvpHabit(habit))
                 continue;
-            if (habit.lastRun === null) {
-                overdue.push({ name: habit.name, elapsedMs: Infinity });
-                continue;
-            }
-            const lastRunMs = new Date(habit.lastRun).getTime();
-            const elapsed = nowMs - lastRunMs;
-            if (elapsed >= cadenceMs) {
-                overdue.push({ name: habit.name, elapsedMs: elapsed });
-            }
+            const dueState = (0, cadence_1.evaluateCadenceDue)(habit.cadence, habit.lastRun, nowMs);
+            if (dueState?.due)
+                overdue.push({ name: habit.name, elapsedMs: dueState.elapsedMs });
         }
         return overdue;
     }
@@ -278,9 +260,9 @@ class HabitScheduler {
                 });
                 // Parse cadence from the original habit file for timer interval
                 const habitFile = this.getHabitFile(job.taskId);
-                const ms = habitFile?.cadence ? (0, cadence_1.parseCadenceToMs)(habitFile.cadence) : null;
+                const ms = habitFile?.cadence ? (0, cadence_1.cadenceFallbackDelayMs)(habitFile.cadence, this.deps.now()) : null;
                 if (ms !== null) {
-                    this.createTimerFallback(job.taskId, ms);
+                    this.createTimerFallback(job.taskId, habitFile.cadence, ms);
                 }
                 this.degradedHabitNames.set(job.taskId, "cron registration failed — using timer fallback");
             }
@@ -315,14 +297,15 @@ class HabitScheduler {
         }
         return verified;
     }
-    createTimerFallback(habitName, cadenceMs) {
+    createTimerFallback(habitName, cadence, firstDelayMs) {
         const schedule = () => {
+            const delayMs = (0, cadence_1.cadenceFallbackDelayMs)(cadence, this.deps.now()) ?? firstDelayMs;
             const timer = setTimeout(() => {
                 this.onHabitFire(habitName, "overdue", {
-                    occurrenceId: this.timerOccurrenceId(habitName, cadenceMs),
+                    occurrenceId: this.timerOccurrenceId(habitName, cadence),
                 });
                 schedule();
-            }, cadenceMs);
+            }, delayMs);
             this.timerFallbacks.set(habitName, timer);
         };
         schedule();
@@ -380,6 +363,8 @@ class HabitScheduler {
                 continue;
             if (!habit.cadence)
                 continue;
+            if (this.rejectInvalidRsvpHabit(habit))
+                continue;
             const cronSchedule = (0, cadence_1.parseCadenceToCron)(habit.cadence);
             if (cronSchedule === null)
                 continue;
@@ -395,6 +380,24 @@ class HabitScheduler {
         }
         return jobs;
     }
+    rejectInvalidRsvpHabit(habit) {
+        if (!(0, habit_policy_1.isRsvpHabitName)(habit.name) || habit.rsvp)
+            return false;
+        this.recordHabitParseError(`${habit.name}.md`, "RSVP habit metadata is required before scheduling");
+        return true;
+    }
+    recordHabitParseError(file, error) {
+        if (this.parseErrors.some((existing) => existing.file === file && existing.error === error))
+            return;
+        this.parseErrors.push({ file, error });
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "daemon",
+            event: "daemon.habit_parse_error",
+            message: "failed to parse habit file",
+            meta: { file, error, agent: this.agent },
+        });
+    }
     overdueOccurrenceId(habit) {
         if (habit.lastRun === null)
             return `overdue:first-run:${habit.cadence}`;
@@ -403,9 +406,14 @@ class HabitScheduler {
     jobOccurrenceId(job, trigger) {
         return `job:${job.id}:${trigger}:last-run:${job.lastRun ?? "never"}`;
     }
-    timerOccurrenceId(habitName, cadenceMs) {
-        const slot = Math.floor(this.deps.now() / cadenceMs);
-        return `timer:${habitName}:cadence-ms:${cadenceMs}:slot:${slot}`;
+    timerOccurrenceId(habitName, cadence) {
+        const cadenceMs = (0, cadence_1.parseCadenceToMs)(cadence);
+        if (cadenceMs !== null) {
+            const slot = Math.floor(this.deps.now() / cadenceMs);
+            return `timer:${habitName}:cadence-ms:${cadenceMs}:slot:${slot}`;
+        }
+        const slot = (0, cadence_1.nextCadenceRunAt)(cadence, this.deps.now()) ?? "unknown";
+        return `timer:${habitName}:cadence:${cadence}:slot:${slot}`;
     }
 }
 exports.HabitScheduler = HabitScheduler;

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

@@ -453,11 +453,10 @@ function filterHabitToolsForEnvelope(definitions, requestedTools, envelope, risk
 function computeNextRunAt(habit, endedAt) {
     if (habit.status !== "active" || !habit.cadence)
         return null;
-    const cadenceMs = (0, cadence_1.parseCadenceToMs)(habit.cadence);
     const endedMs = Date.parse(endedAt);
-    if (cadenceMs === null || !Number.isFinite(endedMs))
+    if (!Number.isFinite(endedMs))
         return null;
-    return new Date(endedMs + cadenceMs).toISOString();
+    return (0, cadence_1.nextCadenceRunAt)(habit.cadence, endedMs);
 }
 function defaultSummarySnapshot(input) {
     const errors = input.errors ?? [];

package/dist/heart/run-ledger.js

@@ -0,0 +1,247 @@
+"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.runLedgerHash = runLedgerHash;
+exports.usageMetadataFromUsageData = usageMetadataFromUsageData;
+exports.deriveRunLedgerIds = deriveRunLedgerIds;
+exports.createRunLedgerRecord = createRunLedgerRecord;
+exports.runLedgerPath = runLedgerPath;
+exports.appendRunLedgerRecord = appendRunLedgerRecord;
+exports.appendRunLedgerRecordNonFatal = appendRunLedgerRecordNonFatal;
+exports.readRunLedger = readRunLedger;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+function sha256Hex(input) {
+    return (0, node_crypto_1.createHash)("sha256").update(input).digest("hex");
+}
+function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function hashValue(value) {
+    return sha256Hex(canonicalJson(value));
+}
+function runLedgerHash(value) {
+    return `sha256:${hashValue(value)}`;
+}
+function stableUnique(values) {
+    return [...new Set((values ?? []).filter((value) => typeof value === "string" && value.trim().length > 0))];
+}
+function numberOrZero(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function usageMetadataFromUsageData(usage, source) {
+    return {
+        source,
+        inputTokens: numberOrZero(usage?.input_tokens),
+        outputTokens: numberOrZero(usage?.output_tokens),
+        reasoningTokens: numberOrZero(usage?.reasoning_tokens),
+        totalTokens: numberOrZero(usage?.total_tokens),
+    };
+}
+function deriveRunLedgerIds(input) {
+    const targetHash = runLedgerHash(input.target);
+    const idempotencyKey = `idem_${hashValue({
+        agent: input.agent,
+        triggerType: input.triggerType,
+        sourceKind: input.sourceKind,
+        senseOrHabit: input.senseOrHabit,
+        scope: input.idempotencyScope ?? input.target,
+    }).slice(0, 32)}`;
+    const runId = `run_${hashValue({
+        agent: input.agent,
+        triggerType: input.triggerType,
+        sourceKind: input.sourceKind,
+        senseOrHabit: input.senseOrHabit,
+        targetHash,
+        idempotencyKey,
+        parentRunId: input.parentRunId ?? null,
+    }).slice(0, 24)}`;
+    return {
+        runId,
+        rootRunId: input.rootRunId ?? input.parentRunId ?? runId,
+        ...(input.parentRunId ? { parentRunId: input.parentRunId } : {}),
+        idempotencyKey,
+        targetHash,
+    };
+}
+function createRunLedgerRecord(input) {
+    const ids = deriveRunLedgerIds(input);
+    return {
+        schemaVersion: 1,
+        recordedAt: new Date().toISOString(),
+        ...ids,
+        agent: input.agent,
+        triggerType: input.triggerType,
+        sourceKind: input.sourceKind,
+        senseOrHabit: input.senseOrHabit,
+        lifecycle: input.lifecycle,
+        startedAt: input.startedAt,
+        ...(input.endedAt ? { endedAt: input.endedAt } : {}),
+        ...(input.usage ? { usage: input.usage } : {}),
+        ...(input.provider ? { provider: input.provider } : {}),
+        ...(input.model ? { model: input.model } : {}),
+        ...(input.sessionRef ? { sessionRef: input.sessionRef } : {}),
+        contextPacketIds: stableUnique(input.contextPacketIds),
+        contentStored: false,
+        ...(input.errorName ? { errorName: input.errorName } : {}),
+        ...(input.errorCode ? { errorCode: input.errorCode } : {}),
+    };
+}
+function runLedgerPath(agentRoot) {
+    return path.join(agentRoot, "state", "run-ledger", "runs.jsonl");
+}
+function appendRunLedgerRecord(agentRoot, record) {
+    const filePath = runLedgerPath(agentRoot);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.appendFileSync(filePath, `${JSON.stringify(record)}\n`, "utf-8");
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.run_ledger_recorded",
+        message: "recorded causal run ledger row",
+        meta: {
+            agent: record.agent,
+            runId: record.runId,
+            triggerType: record.triggerType,
+            sourceKind: record.sourceKind,
+            lifecycle: record.lifecycle,
+            senseOrHabit: record.senseOrHabit,
+        },
+    });
+}
+function appendRunLedgerRecordNonFatal(agentRoot, record) {
+    try {
+        appendRunLedgerRecord(agentRoot, record);
+        return true;
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "heart",
+            event: "heart.run_ledger_record_error",
+            message: "failed to record causal run ledger row",
+            meta: {
+                agent: record.agent,
+                runId: record.runId,
+                lifecycle: record.lifecycle,
+                error: String(error),
+            },
+        });
+        return false;
+    }
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isUsageMetadata(value) {
+    const usage = value;
+    return !!usage
+        && (usage.source === "provider" || usage.source === "none" || usage.source === "reported-unavailable")
+        && typeof usage.inputTokens === "number"
+        && typeof usage.outputTokens === "number"
+        && typeof usage.reasoningTokens === "number"
+        && typeof usage.totalTokens === "number";
+}
+function isSessionRef(value) {
+    const ref = value;
+    return !!ref
+        && typeof ref.channel === "string"
+        && typeof ref.keyHash === "string";
+}
+function isRunLedgerRecord(value) {
+    const record = value;
+    return !!record
+        && record.schemaVersion === 1
+        && typeof record.recordedAt === "string"
+        && typeof record.runId === "string"
+        && typeof record.rootRunId === "string"
+        && (record.parentRunId === undefined || typeof record.parentRunId === "string")
+        && typeof record.idempotencyKey === "string"
+        && typeof record.agent === "string"
+        && (record.triggerType === "inbound" || record.triggerType === "habit" || record.triggerType === "reload" || record.triggerType === "recovery" || record.triggerType === "manual")
+        && (record.sourceKind === "sense" || record.sourceKind === "private-runtime" || record.sourceKind === "daemon" || record.sourceKind === "cli")
+        && typeof record.senseOrHabit === "string"
+        && typeof record.targetHash === "string"
+        && (record.lifecycle === "started" || record.lifecycle === "completed" || record.lifecycle === "skipped" || record.lifecycle === "blocked" || record.lifecycle === "error")
+        && typeof record.startedAt === "string"
+        && (record.endedAt === undefined || typeof record.endedAt === "string")
+        && (record.usage === undefined || isUsageMetadata(record.usage))
+        && (record.provider === undefined || typeof record.provider === "string")
+        && (record.model === undefined || typeof record.model === "string")
+        && (record.sessionRef === undefined || isSessionRef(record.sessionRef))
+        && isStringArray(record.contextPacketIds)
+        && record.contentStored === false
+        && (record.errorName === undefined || typeof record.errorName === "string")
+        && (record.errorCode === undefined || typeof record.errorCode === "string");
+}
+function emitMalformedRunLedgerRow(lineNumber, reason) {
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "heart",
+        event: "heart.run_ledger_malformed",
+        message: "skipped malformed causal run ledger row",
+        meta: { lineNumber, reason },
+    });
+}
+function readRunLedger(agentRoot) {
+    const filePath = runLedgerPath(agentRoot);
+    if (!fs.existsSync(filePath))
+        return [];
+    const rows = [];
+    const lines = fs.readFileSync(filePath, "utf-8").split("\n").filter((line) => line.trim().length > 0);
+    lines.forEach((line, index) => {
+        try {
+            const parsed = JSON.parse(line);
+            if (isRunLedgerRecord(parsed)) {
+                rows.push(parsed);
+            }
+            else {
+                emitMalformedRunLedgerRow(index + 1, "invalid shape");
+            }
+        }
+        catch (error) {
+            emitMalformedRunLedgerRow(index + 1, String(error));
+        }
+    });
+    return rows;
+}