@ouro.bot/cli 0.1.0-alpha.83 → 0.1.0-alpha.831

package/dist/heart/mailbox/readers/runtime-readers.js

@@ -0,0 +1,823 @@
+"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.readCodingDeep = readCodingDeep;
+exports.readAttentionView = readAttentionView;
+exports.readContextPacketListView = readContextPacketListView;
+exports.readContextPacketView = readContextPacketView;
+exports.readBridgeInventory = readBridgeInventory;
+exports.readDaemonHealthDeep = readDaemonHealthDeep;
+exports.readNotesView = readNotesView;
+exports.readFriendView = readFriendView;
+exports.readLogView = readLogView;
+exports.readHabitView = readHabitView;
+exports.readHabitRunView = readHabitRunView;
+exports.readHabitRunReceiptView = readHabitRunReceiptView;
+exports.readHabitSessionSummaryListView = readHabitSessionSummaryListView;
+exports.readHabitSessionSummaryView = readHabitSessionSummaryView;
+exports.readNeedsMeView = readNeedsMeView;
+exports.readDeskPrefs = readDeskPrefs;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../../../nerves/runtime");
+const habit_parser_1 = require("../../habits/habit-parser");
+const habit_runtime_state_1 = require("../../habits/habit-runtime-state");
+const habit_session_summary_1 = require("../../habits/habit-session-summary");
+const identity_1 = require("../../identity");
+const daemon_health_1 = require("../../daemon/daemon-health");
+const flight_recorder_1 = require("../../../arc/flight-recorder");
+const context_packet_ledger_1 = require("../../../senses/context-packet-ledger");
+const shared_1 = require("./shared");
+const agent_machine_1 = require("./agent-machine");
+const sessions_1 = require("./sessions");
+const record_paths_1 = require("../../../mind/record-paths");
+const NOTES_VIEW_LIMIT = 20;
+const DEFAULT_HABIT_RUN_LIMIT = 20;
+const MAX_HABIT_RUN_LIMIT = 100;
+/* v8 ignore start — defensive parsing of on-disk JSON, fallback branches are safety nets */
+function readCodingDeep(agentRoot) {
+    const stateFilePath = path.join(agentRoot, "state", "coding", "sessions.json");
+    if (!fs.existsSync(stateFilePath)) {
+        return { totalCount: 0, activeCount: 0, blockedCount: 0, items: [] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(stateFilePath, "utf-8"));
+    }
+    catch {
+        return { totalCount: 0, activeCount: 0, blockedCount: 0, items: [] };
+    }
+    const items = Array.isArray(parsed.records)
+        ? parsed.records.flatMap((record) => {
+            const s = record?.session;
+            if (!s || typeof s.id !== "string" || typeof s.status !== "string")
+                return [];
+            const checkpoint = typeof s.checkpoint === "string" ? s.checkpoint
+                : typeof s.stderrTail === "string" && s.stderrTail.trim().length > 0 ? s.stderrTail.trim()
+                    : typeof s.stdoutTail === "string" && s.stdoutTail.trim().length > 0 ? s.stdoutTail.trim()
+                        : null;
+            const originSession = s.originSession;
+            const normalizedOrigin = originSession
+                && typeof originSession.friendId === "string"
+                && typeof originSession.channel === "string"
+                && typeof originSession.key === "string"
+                ? { friendId: originSession.friendId, channel: originSession.channel, key: originSession.key }
+                : null;
+            const failure = s.failure;
+            const normalizedFailure = failure && typeof failure === "object"
+                ? {
+                    command: typeof failure.command === "string" ? failure.command : "",
+                    args: Array.isArray(failure.args) ? failure.args.map(String) : [],
+                    code: typeof failure.code === "number" ? failure.code : null,
+                    signal: typeof failure.signal === "string" ? failure.signal : null,
+                    stdoutTail: typeof failure.stdoutTail === "string" ? failure.stdoutTail : "",
+                    stderrTail: typeof failure.stderrTail === "string" ? failure.stderrTail : "",
+                }
+                : null;
+            return [{
+                    id: s.id,
+                    runner: (typeof s.runner === "string" ? s.runner : "claude"),
+                    status: s.status,
+                    checkpoint,
+                    taskRef: typeof s.taskRef === "string" ? s.taskRef : null,
+                    workdir: typeof s.workdir === "string" ? s.workdir : "",
+                    originSession: normalizedOrigin,
+                    obligationId: typeof s.obligationId === "string" ? s.obligationId : null,
+                    scopeFile: typeof s.scopeFile === "string" ? s.scopeFile : null,
+                    stateFile: typeof s.stateFile === "string" ? s.stateFile : null,
+                    artifactPath: typeof s.artifactPath === "string" ? s.artifactPath : null,
+                    pid: typeof s.pid === "number" ? s.pid : null,
+                    startedAt: typeof s.startedAt === "string" ? s.startedAt : "",
+                    lastActivityAt: typeof s.lastActivityAt === "string" ? s.lastActivityAt : "",
+                    endedAt: typeof s.endedAt === "string" ? s.endedAt : null,
+                    restartCount: typeof s.restartCount === "number" ? s.restartCount : 0,
+                    lastExitCode: typeof s.lastExitCode === "number" ? s.lastExitCode : null,
+                    lastSignal: typeof s.lastSignal === "string" ? s.lastSignal : null,
+                    stdoutTail: typeof s.stdoutTail === "string" ? s.stdoutTail : "",
+                    stderrTail: typeof s.stderrTail === "string" ? s.stderrTail : "",
+                    failure: normalizedFailure,
+                }];
+        })
+        : [];
+    return {
+        totalCount: items.length,
+        activeCount: items.filter((item) => shared_1.ACTIVE_CODING_STATUSES.has(item.status)).length,
+        blockedCount: items.filter((item) => shared_1.BLOCKED_CODING_STATUSES.has(item.status)).length,
+        items,
+    };
+}
+/* v8 ignore stop */
+function scanPendingChannels(agentRoot) {
+    const pendingRoot = path.join(agentRoot, "state", "pending");
+    const channels = [];
+    for (const friendId of (0, shared_1.safeReaddir)(pendingRoot)) {
+        if (friendId === "self")
+            continue;
+        const friendDir = path.join(pendingRoot, friendId);
+        if (!(0, shared_1.safeIsDirectory)(friendDir))
+            continue;
+        for (const channel of (0, shared_1.safeReaddir)(friendDir)) {
+            const channelDir = path.join(friendDir, channel);
+            if (!(0, shared_1.safeIsDirectory)(channelDir))
+                continue;
+            for (const key of (0, shared_1.safeReaddir)(channelDir)) {
+                const keyDir = path.join(channelDir, key);
+                if (!(0, shared_1.safeIsDirectory)(keyDir))
+                    continue;
+                const files = (0, shared_1.safeReaddir)(keyDir).filter((f) => f.endsWith(".json") || f.endsWith(".json.processing"));
+                if (files.length > 0) {
+                    channels.push({ friendId, channel, key, messageCount: files.length });
+                }
+            }
+        }
+    }
+    return channels;
+}
+function readPendingMessagesNonDestructive(pendingDir) {
+    const files = (0, shared_1.safeReaddir)(pendingDir).filter((f) => f.endsWith(".json") || f.endsWith(".json.processing"));
+    const messages = [];
+    for (const file of files.sort()) {
+        try {
+            const raw = fs.readFileSync(path.join(pendingDir, file), "utf-8");
+            messages.push(JSON.parse(raw));
+        }
+        catch {
+            // skip unparseable pending messages
+        }
+    }
+    return messages;
+}
+function readAttentionView(agentName, options = {}) {
+    const bundlesRoot = options.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
+    const agentRoot = path.join(bundlesRoot, `${agentName}.ouro`);
+    const friendsDir = path.join(agentRoot, "friends");
+    const pendingChannels = scanPendingChannels(agentRoot);
+    const queueItems = [];
+    const pendingRoot = path.join(agentRoot, "state", "pending");
+    for (const pending of pendingChannels) {
+        const pendingDir = path.join(pendingRoot, pending.friendId, pending.channel, pending.key);
+        const messages = readPendingMessagesNonDestructive(pendingDir);
+        for (const msg of messages) {
+            const delegatedFrom = msg.delegatedFrom;
+            queueItems.push({
+                id: typeof msg.timestamp === "number" ? `${msg.timestamp}-${pending.friendId}` : `pending-${Date.now()}`,
+                friendId: pending.friendId,
+                friendName: (0, shared_1.resolveFriendName)(friendsDir, pending.friendId),
+                channel: pending.channel,
+                key: pending.key,
+                bridgeId: delegatedFrom && typeof delegatedFrom.bridgeId === "string" ? delegatedFrom.bridgeId : null,
+                delegatedContent: typeof msg.content === "string" ? msg.content : "",
+                obligationId: typeof msg.obligationId === "string" ? msg.obligationId : null,
+                source: "pending",
+                timestamp: typeof msg.timestamp === "number" ? msg.timestamp : 0,
+            });
+        }
+    }
+    queueItems.sort((a, b) => a.timestamp - b.timestamp);
+    const returnObligations = (0, agent_machine_1.readObligationSummary)(agentRoot).items;
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.mailbox_attention_read",
+        message: "reading mailbox attention queue",
+        meta: { agentName, queueLength: queueItems.length, pendingChannelCount: pendingChannels.length },
+    });
+    return {
+        queueLength: queueItems.length,
+        queueItems,
+        pendingChannels,
+        returnObligations,
+    };
+}
+function readContextPacketListView(agentRoot, options = {}) {
+    return (0, context_packet_ledger_1.listSenseContextPacketSummaries)(agentRoot, options);
+}
+function readContextPacketView(agentRoot, packetId) {
+    return (0, context_packet_ledger_1.readSenseContextPacketView)(agentRoot, packetId);
+}
+/* v8 ignore start — defensive parsing */
+function readBridgeInventory(agentRoot) {
+    const bridgesDir = path.join(agentRoot, "state", "bridges");
+    const items = [];
+    for (const file of (0, shared_1.safeReaddir)(bridgesDir)) {
+        if (!file.endsWith(".json"))
+            continue;
+        try {
+            const raw = fs.readFileSync(path.join(bridgesDir, file), "utf-8");
+            const bridge = JSON.parse(raw);
+            if (typeof bridge.id !== "string")
+                continue;
+            const attachedSessions = Array.isArray(bridge.attachedSessions)
+                ? bridge.attachedSessions
+                    .filter((s) => typeof s.friendId === "string")
+                    .map((s) => ({
+                    friendId: s.friendId,
+                    channel: typeof s.channel === "string" ? s.channel : "",
+                    key: typeof s.key === "string" ? s.key : "",
+                    sessionPath: typeof s.sessionPath === "string" ? s.sessionPath : "",
+                    snapshot: typeof s.snapshot === "string" ? s.snapshot : null,
+                }))
+                : [];
+            const taskLink = bridge.task;
+            const normalizedTask = taskLink && typeof taskLink === "object" && typeof taskLink.taskName === "string"
+                ? {
+                    taskName: taskLink.taskName,
+                    path: typeof taskLink.path === "string" ? taskLink.path : "",
+                    mode: typeof taskLink.mode === "string" ? taskLink.mode : "bound",
+                    boundAt: typeof taskLink.boundAt === "string" ? taskLink.boundAt : "",
+                }
+                : null;
+            items.push({
+                id: bridge.id,
+                objective: typeof bridge.objective === "string" ? bridge.objective : "",
+                summary: typeof bridge.summary === "string" ? bridge.summary : "",
+                lifecycle: typeof bridge.lifecycle === "string" ? bridge.lifecycle : "unknown",
+                runtime: typeof bridge.runtime === "string" ? bridge.runtime : "unknown",
+                createdAt: typeof bridge.createdAt === "string" ? bridge.createdAt : "",
+                updatedAt: typeof bridge.updatedAt === "string" ? bridge.updatedAt : "",
+                attachedSessions,
+                task: normalizedTask,
+            });
+        }
+        catch {
+            // skip unparseable bridge files
+        }
+    }
+    items.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    const activeCount = items.filter((item) => item.lifecycle === "active").length;
+    return {
+        totalCount: items.length,
+        activeCount,
+        items,
+    };
+}
+/* v8 ignore stop */
+/* v8 ignore start — defensive parsing */
+function readDaemonHealthDeep(healthPath) {
+    const resolvedPath = healthPath ?? path.join(process.env.HOME ?? "", ".ouro-cli", "daemon-health.json");
+    try {
+        const raw = fs.readFileSync(resolvedPath, "utf-8");
+        const health = JSON.parse(raw);
+        return {
+            // Layer 1: tighten the parse so only post-Layer-1 vocabulary
+            // carries through. Stale cached files that still hold legacy
+            // string values like "ok" or "running" — written by an older
+            // daemon binary — fall back to "unknown" so downstream Mailbox
+            // consumers can detect the unparseable case explicitly.
+            status: (0, daemon_health_1.isDaemonStatus)(health.status) ? health.status : "unknown",
+            mode: typeof health.mode === "string" ? health.mode : "unknown",
+            pid: typeof health.pid === "number" ? health.pid : 0,
+            startedAt: typeof health.startedAt === "string" ? health.startedAt : "",
+            uptimeSeconds: typeof health.uptimeSeconds === "number" ? health.uptimeSeconds : 0,
+            safeMode: health.safeMode && typeof health.safeMode === "object"
+                ? {
+                    active: health.safeMode.active === true,
+                    reason: typeof health.safeMode.reason === "string" ? health.safeMode.reason : "",
+                    enteredAt: typeof health.safeMode.enteredAt === "string" ? health.safeMode.enteredAt : "",
+                }
+                : null,
+            degradedComponents: Array.isArray(health.degraded)
+                ? health.degraded.map((c) => ({
+                    component: typeof c.component === "string" ? c.component : "",
+                    reason: typeof c.reason === "string" ? c.reason : "",
+                    since: typeof c.since === "string" ? c.since : "",
+                }))
+                : [],
+            agentHealth: health.agents && typeof health.agents === "object"
+                ? Object.fromEntries(Object.entries(health.agents).map(([name, entry]) => [
+                    name,
+                    {
+                        status: typeof entry.status === "string" ? entry.status : "unknown",
+                        pid: typeof entry.pid === "number" ? entry.pid : null,
+                        crashes: typeof entry.crashes === "number" ? entry.crashes : 0,
+                    },
+                ]))
+                : {},
+            habitHealth: health.habits && typeof health.habits === "object"
+                ? Object.fromEntries(Object.entries(health.habits).map(([name, entry]) => [
+                    name,
+                    {
+                        cronStatus: typeof entry.cronStatus === "string" ? entry.cronStatus : "unknown",
+                        lastFired: typeof entry.lastFired === "string" ? entry.lastFired : null,
+                        fallback: entry.fallback === true,
+                    },
+                ]))
+                : {},
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/* v8 ignore stop */
+function readNotesView(agentRoot) {
+    const recordPaths = (0, record_paths_1.resolveDeskRecordPaths)(agentRoot);
+    const diaryEntries = [];
+    try {
+        const raw = fs.readFileSync(recordPaths.factsPath, "utf-8");
+        for (const line of raw.split("\n")) {
+            if (!line.trim())
+                continue;
+            try {
+                const entry = JSON.parse(line);
+                if (typeof entry.id === "string" && typeof entry.text === "string") {
+                    diaryEntries.push({
+                        id: entry.id,
+                        text: entry.text,
+                        source: typeof entry.source === "string" ? entry.source : "",
+                        createdAt: typeof entry.createdAt === "string" ? entry.createdAt : "",
+                    });
+                }
+            }
+            catch {
+                // skip unparseable lines
+            }
+        }
+    }
+    catch {
+        // no diary facts file
+    }
+    diaryEntries.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    const canonicalNotes = readCanonicalNotes(recordPaths.notesRoot);
+    return {
+        diaryEntryCount: diaryEntries.length,
+        recentDiaryEntries: diaryEntries.slice(0, NOTES_VIEW_LIMIT),
+        canonicalNoteCount: canonicalNotes.length,
+        recentCanonicalNotes: canonicalNotes.slice(0, NOTES_VIEW_LIMIT),
+    };
+}
+function readCanonicalNotes(notesRoot) {
+    const notes = [];
+    for (const filename of (0, shared_1.safeReaddir)(notesRoot)) {
+        if (!filename.endsWith(".md"))
+            continue;
+        const filePath = path.join(notesRoot, filename);
+        if ((0, shared_1.safeIsDirectory)(filePath))
+            continue;
+        try {
+            const raw = fs.readFileSync(filePath, "utf-8");
+            const { frontmatter, body } = parseMarkdownFrontmatter(raw);
+            const writtenAt = safeCanonicalNoteTimestamp(frontmatter.created_at, filePath);
+            notes.push({
+                filename,
+                title: firstMarkdownHeading(body) ?? titleFromFilename(filename),
+                tags: Array.isArray(frontmatter.tags) ? frontmatter.tags : [],
+                preview: body.slice(0, 200),
+                writtenAt,
+            });
+        }
+        catch {
+            // skip unreadable notes
+        }
+    }
+    notes.sort((a, b) => b.writtenAt.localeCompare(a.writtenAt) || b.filename.localeCompare(a.filename));
+    return notes;
+}
+function safeCanonicalNoteTimestamp(value, filePath) {
+    const fallback = (0, shared_1.safeFileMtime)(filePath);
+    if (typeof value !== "string")
+        return fallback;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return fallback;
+    return Number.isNaN(new Date(trimmed).getTime()) ? fallback : trimmed;
+}
+function parseMarkdownFrontmatter(raw) {
+    const lines = raw.split(/\r?\n/);
+    if (lines[0] !== "---")
+        return { frontmatter: {}, body: raw };
+    const endIndex = lines.findIndex((line, index) => index > 0 && line === "---");
+    if (endIndex === -1)
+        return { frontmatter: {}, body: raw };
+    return {
+        frontmatter: parseMinimalFrontmatter(lines.slice(1, endIndex)),
+        body: lines.slice(endIndex + 1).join("\n").replace(/^\n/, ""),
+    };
+}
+function parseMinimalFrontmatter(lines) {
+    const frontmatter = {};
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        const match = line?.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!match)
+            continue;
+        const key = match[1];
+        const rawValue = match[2];
+        if (key === "tags") {
+            frontmatter.tags = parseFrontmatterTags(rawValue, lines, index + 1);
+            continue;
+        }
+        frontmatter[key] = rawValue.trim();
+    }
+    return frontmatter;
+}
+function parseFrontmatterTags(rawValue, lines, startIndex) {
+    const trimmed = rawValue.trim();
+    if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            return parsed.filter((item) => typeof item === "string");
+        }
+        catch {
+            return trimmed.slice(1, -1).split(",").map((tag) => tag.trim().replace(/^['"]|['"]$/g, "")).filter(Boolean);
+        }
+    }
+    if (trimmed.length > 0)
+        return [trimmed];
+    const tags = [];
+    for (let index = startIndex; index < lines.length; index += 1) {
+        const itemMatch = lines[index]?.match(/^\s*-\s*(.+)$/);
+        if (!itemMatch)
+            break;
+        const tag = itemMatch[1].trim().replace(/^['"]|['"]$/g, "");
+        if (tag)
+            tags.push(tag);
+    }
+    return tags;
+}
+function firstMarkdownHeading(body) {
+    const heading = body
+        .split(/\r?\n/)
+        .map((line) => line.match(/^#\s+(.+)$/)?.[1]?.trim())
+        .find((title) => title && title.length > 0);
+    return heading ?? null;
+}
+function titleFromFilename(filename) {
+    const stem = filename.replace(/\.md$/i, "").replace(/^\d{4}-\d{2}-\d{2}-/, "");
+    return stem.replace(/[-_]+/g, " ").trim() || filename;
+}
+function readFriendView(agentName, options = {}) {
+    const bundlesRoot = options.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
+    const agentRoot = path.join(bundlesRoot, `${agentName}.ouro`);
+    const friendsDir = path.join(agentRoot, "friends");
+    const sessionsDir = path.join(agentRoot, "state", "sessions");
+    const friends = [];
+    for (const file of (0, shared_1.safeReaddir)(friendsDir)) {
+        if (!file.endsWith(".json"))
+            continue;
+        const friendId = file.slice(0, -5);
+        try {
+            const raw = fs.readFileSync(path.join(friendsDir, file), "utf-8");
+            const record = JSON.parse(raw);
+            const friendSessionsDir = path.join(sessionsDir, friendId);
+            const channels = new Set();
+            let sessionCount = 0;
+            let latestActivity = null;
+            for (const channel of (0, shared_1.safeReaddir)(friendSessionsDir)) {
+                const channelDir = path.join(friendSessionsDir, channel);
+                if (!(0, shared_1.safeIsDirectory)(channelDir))
+                    continue;
+                for (const keyFile of (0, shared_1.safeReaddir)(channelDir)) {
+                    if (!keyFile.endsWith(".json"))
+                        continue;
+                    channels.add(channel);
+                    sessionCount++;
+                    const mtime = (0, shared_1.safeFileMtime)(path.join(channelDir, keyFile));
+                    if (mtime && (!latestActivity || mtime > latestActivity)) {
+                        latestActivity = mtime;
+                    }
+                }
+            }
+            friends.push({
+                friendId,
+                friendName: typeof record.name === "string" ? record.name : friendId,
+                totalTokens: typeof record.totalTokens === "number" ? record.totalTokens : 0,
+                sessionCount,
+                channels: [...channels].sort(),
+                lastActivityAt: latestActivity,
+            });
+        }
+        catch {
+            // skip unparseable friend records
+        }
+    }
+    friends.sort((a, b) => b.totalTokens - a.totalTokens);
+    return {
+        totalFriends: friends.length,
+        friends,
+    };
+}
+function readLogView(logPath, limit = 100) {
+    if (!logPath || !fs.existsSync(logPath)) {
+        return { logPath, totalLines: 0, entries: [] };
+    }
+    try {
+        const raw = fs.readFileSync(logPath, "utf-8");
+        const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+        const totalLines = lines.length;
+        const recentLines = lines.slice(-limit);
+        const entries = [];
+        for (const line of recentLines) {
+            try {
+                const parsed = JSON.parse(line);
+                entries.push({
+                    ts: typeof parsed.ts === "string" ? parsed.ts : "",
+                    level: typeof parsed.level === "string" ? parsed.level : "info",
+                    event: typeof parsed.event === "string" ? parsed.event : "",
+                    component: typeof parsed.component === "string" ? parsed.component : "",
+                    message: typeof parsed.message === "string" ? parsed.message : "",
+                    trace_id: typeof parsed.trace_id === "string" ? parsed.trace_id : "",
+                    meta: parsed.meta && typeof parsed.meta === "object" ? parsed.meta : {},
+                });
+            }
+            catch {
+                // skip unparseable log lines
+            }
+        }
+        return { logPath, totalLines, entries };
+    }
+    catch { /* v8 ignore next */
+        return { logPath, totalLines: 0, entries: [] };
+    }
+}
+function readHabitView(agentRoot, options = {}) {
+    const habitsDir = path.join(agentRoot, "habits");
+    const now = options.now?.() ?? new Date();
+    const items = [];
+    for (const file of (0, shared_1.safeReaddir)(habitsDir)) {
+        if (!file.endsWith(".md"))
+            continue;
+        const filePath = path.join(habitsDir, file);
+        let habit;
+        try {
+            const raw = fs.readFileSync(filePath, "utf-8");
+            habit = (0, habit_runtime_state_1.applyHabitRuntimeState)(agentRoot, (0, habit_parser_1.parseHabitFile)(raw, filePath));
+        }
+        catch {
+            habit = (0, habit_parser_1.createDegradedHabitFile)(filePath, "read_error");
+        }
+        const cadenceMs = parseCadenceMs(habit.cadence);
+        let isOverdue = false;
+        let overdueMs = null;
+        if (habit.status === "active" && habit.lastRun && cadenceMs) {
+            const elapsed = now.getTime() - Date.parse(habit.lastRun);
+            if (elapsed > cadenceMs) {
+                isOverdue = true;
+                overdueMs = elapsed - cadenceMs;
+            }
+        }
+        items.push({
+            name: habit.name,
+            title: habit.title,
+            cadence: habit.cadence,
+            status: habit.status,
+            lastRun: habit.lastRun,
+            bodyExcerpt: (0, shared_1.truncateExcerpt)(habit.body, 120),
+            isDegraded: habit.status === "degraded",
+            degradedReason: habit.status === "degraded" ? habit.degradedReason : null,
+            isOverdue,
+            overdueMs,
+        });
+    }
+    items.sort((a, b) => {
+        if (a.isOverdue && !b.isOverdue)
+            return -1;
+        if (!a.isOverdue && b.isOverdue)
+            return 1;
+        return a.name.localeCompare(b.name);
+    });
+    return {
+        totalCount: items.length,
+        activeCount: items.filter((h) => h.status === "active").length,
+        pausedCount: items.filter((h) => h.status === "paused").length,
+        degradedCount: items.filter((h) => h.isDegraded).length,
+        overdueCount: items.filter((h) => h.isOverdue).length,
+        items,
+    };
+}
+function normalizeHabitRunLimit(limit) {
+    if (limit === undefined || !Number.isInteger(limit))
+        return DEFAULT_HABIT_RUN_LIMIT;
+    return Math.min(MAX_HABIT_RUN_LIMIT, Math.max(1, limit));
+}
+function summarizeHabitRunReceipt(receipt) {
+    return {
+        runId: receipt.runId,
+        habitName: receipt.habitName,
+        trigger: receipt.trigger,
+        startedAt: receipt.startedAt,
+        endedAt: receipt.endedAt,
+        outcome: receipt.outcome,
+        nextRunAt: receipt.nextRunAt,
+        permissionEnvelope: receipt.permissionEnvelope,
+        toolPolicy: receipt.toolPolicy,
+        producedRefs: receipt.producedRefs,
+        surfaceAttempts: receipt.surfaceAttempts,
+        errorCount: receipt.errors.length,
+        errors: receipt.errors,
+        receiptLocator: receipt.receiptLocator,
+        sessionLocator: receipt.sessionLocator,
+        runtimeStateLocator: receipt.runtimeStateLocator,
+    };
+}
+function readHabitRunView(agentRoot, options = {}) {
+    const limit = normalizeHabitRunLimit(options.limit);
+    const receipts = (0, flight_recorder_1.listHabitRunReceipts)(agentRoot);
+    const items = receipts.slice(0, limit).map(summarizeHabitRunReceipt);
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.mailbox_habit_runs_read",
+        message: "reading mailbox habit run receipts",
+        meta: { agentRoot, totalCount: receipts.length, limit, itemCount: items.length },
+    });
+    return {
+        totalCount: receipts.length,
+        limit,
+        items,
+    };
+}
+function readHabitRunReceiptView(agentRoot, runId) {
+    const receipt = (0, flight_recorder_1.readHabitRunReceipt)(agentRoot, runId);
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.mailbox_habit_run_receipt_read",
+        message: "reading mailbox habit run receipt",
+        meta: { agentRoot, runId, found: receipt !== null },
+    });
+    return receipt ? { receipt } : null;
+}
+function readHabitSessionSummaryListView(agentRoot, options = {}) {
+    const limit = normalizeHabitRunLimit(options.limit);
+    const receipts = (0, flight_recorder_1.listHabitRunReceipts)(agentRoot);
+    const items = receipts.slice(0, limit)
+        .map((receipt) => (0, habit_session_summary_1.readHabitSessionSummary)(agentRoot, { runId: receipt.runId }))
+        .filter((summary) => summary !== null);
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.mailbox_habit_run_summaries_read",
+        message: "reading mailbox habit run summaries",
+        meta: { agentRoot, totalCount: receipts.length, limit, itemCount: items.length },
+    });
+    return {
+        totalCount: receipts.length,
+        limit,
+        items,
+    };
+}
+function readHabitSessionSummaryView(agentRoot, selector) {
+    const summary = (0, habit_session_summary_1.readHabitSessionSummary)(agentRoot, selector);
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.mailbox_habit_run_summary_read",
+        message: "reading mailbox habit run summary",
+        meta: { agentRoot, runId: summary?.runId ?? null, habitName: summary?.habitName ?? selector.habitName ?? null, found: summary !== null },
+    });
+    return summary;
+}
+function readNeedsMeView(agentName, options = {}) {
+    const bundlesRoot = options.bundlesRoot ?? (0, identity_1.getAgentBundlesRoot)();
+    const now = options.now?.() ?? new Date();
+    const agentRoot = path.join(bundlesRoot, `${agentName}.ouro`);
+    const items = [];
+    const prefs = readDeskPrefs(agentRoot);
+    const dismissed = new Set(prefs.dismissedObligations);
+    const sessions = (0, sessions_1.readSessionInventory)(agentName, options);
+    for (const s of sessions.items) {
+        if (s.replyState === "needs-reply") {
+            items.push({
+                urgency: "owed-reply",
+                label: `${s.friendName} is waiting for a reply`,
+                detail: `via ${s.channel} · ${s.latestUserExcerpt ? (0, shared_1.truncateExcerpt)(s.latestUserExcerpt, 80) : ""}`,
+                ref: { tab: "sessions", focus: `${s.friendId}/${s.channel}/${s.key}` },
+                ageMs: now.getTime() - Date.parse(s.lastActivityAt),
+            });
+        }
+    }
+    const obligations = (0, agent_machine_1.readObligationSummary)(agentRoot);
+    for (const o of obligations.items) {
+        if (dismissed.has(o.id))
+            continue;
+        const ageMs = now.getTime() - Date.parse(o.updatedAt);
+        const isStale = ageMs > 24 * 60 * 60 * 1000;
+        const hasResult = o.currentSurface !== null;
+        const isOpen = o.status === "pending" || o.status === "investigating" || o.status === "waiting_for_merge" || o.status === "updating_runtime";
+        if (isOpen) {
+            items.push({
+                urgency: hasResult ? "return-ready" : isStale ? "stale-delegation" : "blocking-obligation",
+                label: (0, shared_1.truncateExcerpt)(o.content, 80) ?? o.id,
+                detail: hasResult ? `result ready — ${o.currentSurface.kind}: ${o.currentSurface.label}` : `${o.status}${o.nextAction ? ` · next: ${o.nextAction}` : ""}`,
+                ref: { tab: "work", focus: o.id },
+                ageMs,
+            });
+        }
+    }
+    const pendingChannels = scanPendingChannels(agentRoot);
+    for (const p of pendingChannels) {
+        const friendName = (0, shared_1.resolveFriendName)(path.join(agentRoot, "friends"), p.friendId);
+        items.push({
+            urgency: "stale-delegation",
+            label: `${p.messageCount} pending from ${friendName}`,
+            detail: `${p.channel}/${p.key}`,
+            ref: { tab: "connections" },
+            ageMs: null,
+        });
+    }
+    const habits = readHabitView(agentRoot, options);
+    for (const h of habits.items) {
+        if (h.isOverdue) {
+            items.push({
+                urgency: "overdue-habit",
+                label: `${h.title} is overdue`,
+                detail: `every ${h.cadence} · last ${h.lastRun}`,
+                ref: { tab: "inner" },
+                ageMs: h.overdueMs,
+            });
+        }
+    }
+    const urgencyOrder = {
+        "owed-reply": 0,
+        "blocking-obligation": 1,
+        "broken-return": 2,
+        "stale-delegation": 3,
+        "return-ready": 4,
+        "overdue-habit": 5,
+    };
+    items.sort((a, b) => urgencyOrder[a.urgency] - urgencyOrder[b.urgency]);
+    return { items };
+}
+/* v8 ignore start — defensive JSON parsing in desk prefs reader */
+function readDeskPrefs(agentRoot) {
+    const prefsPath = path.join(agentRoot, "state", "mailbox-prefs.json");
+    const legacyPrefsPath = path.join(agentRoot, "state", "outlook-prefs.json");
+    const defaults = {
+        carrying: null,
+        statusLine: null,
+        tabOrder: null,
+        starredFriends: [],
+        pinnedConstellations: [],
+        dismissedObligations: [],
+    };
+    try {
+        const raw = fs.readFileSync(fs.existsSync(prefsPath) ? prefsPath : legacyPrefsPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        return {
+            carrying: typeof parsed.carrying === "string" ? parsed.carrying : null,
+            statusLine: typeof parsed.statusLine === "string" ? parsed.statusLine : null,
+            tabOrder: Array.isArray(parsed.tabOrder) ? parsed.tabOrder.filter((t) => typeof t === "string") : null,
+            starredFriends: Array.isArray(parsed.starredFriends) ? parsed.starredFriends.filter((f) => typeof f === "string") : [],
+            pinnedConstellations: Array.isArray(parsed.pinnedConstellations)
+                ? parsed.pinnedConstellations.map((c) => ({
+                    label: typeof c.label === "string" ? c.label : "",
+                    friendIds: Array.isArray(c.friendIds) ? c.friendIds.filter((f) => typeof f === "string") : [],
+                    taskRefs: Array.isArray(c.taskRefs) ? c.taskRefs.filter((t) => typeof t === "string") : [],
+                    bridgeIds: Array.isArray(c.bridgeIds) ? c.bridgeIds.filter((b) => typeof b === "string") : [],
+                    codingIds: Array.isArray(c.codingIds) ? c.codingIds.filter((c2) => typeof c2 === "string") : [],
+                }))
+                : [],
+            dismissedObligations: Array.isArray(parsed.dismissedObligations) ? parsed.dismissedObligations.filter((id) => typeof id === "string") : [],
+        };
+    }
+    catch {
+        return defaults;
+    }
+}
+/* v8 ignore stop */
+function parseCadenceMs(cadence) {
+    if (!cadence)
+        return null;
+    const match = /^(\d+)\s*(m|min|h|hr|d|day)s?$/i.exec(cadence.trim());
+    if (!match)
+        return null;
+    const value = parseInt(match[1], 10);
+    const multipliers = {
+        m: 60 * 1000,
+        min: 60 * 1000,
+        h: 60 * 60 * 1000,
+        hr: 60 * 60 * 1000,
+        d: 24 * 60 * 60 * 1000,
+        day: 24 * 60 * 60 * 1000,
+    };
+    const unit = match[2].toLowerCase();
+    return value * multipliers[unit];
+}