@ouro.bot/cli 0.1.0-alpha.496 → 0.1.0-alpha.498

package/changelog.json

@@ -1,6 +1,22 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.498",
+      "changes": [
+        "Heartbeat / habit recursion detection in the inner-dialog worker. The existing instinct cap (`MAX_CONSECUTIVE_INSTINCT_TURNS=3`) protects against the *internal* pending-dir self-loop (a turn writes back to its own pending dir, drains it, repeats). It does not protect against the *external* IPC self-loop where heartbeat-shaped messages get re-issued faster than their cadence — e.g. a hook misconfigured to repost on every heartbeat, a daemon retry storm, or two timers drifting into the same window.",
+        "Two new warn-level nerve events: `senses.habit_recursion_suspected` fires when two of the same habit (e.g. `heartbeat`) arrive within `HABIT_RECURSION_MIN_INTERVAL_MS` (5s) — no realistic cadence runs that fast. `senses.habit_recursion_burst` fires when `HABIT_RECURSION_BURST_THRESHOLD` (5) or more habit messages of any kind land within `HABIT_RECURSION_BURST_WINDOW_MS` (60s) — catches slower runaways that stay just under the min-interval threshold.",
+        "Detection is observation-only by design: it emits the warn signal so an operator (or a follow-up auto-recovery layer) can act on it. The message is not dropped — the signal is the value. Per-habit-name tracking, so two distinct habits firing close together don't trip the min-interval warning. `nowSource` is injectable via the `createInnerDialogWorker` factory for deterministic tests. 5 new tests cover both detectors plus the trim-window and per-habit isolation cases."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.497",
+      "changes": [
+        "Mail thread reconstruction + tool rename. The previous `mail_thread` tool was misleadingly named — it returned ONE message body, not a thread. Renamed to `mail_body`. The new actual conversation walker now owns the canonical name `mail_thread`. Existing tests, audit-log strings, and CLI guidance updated to match.",
+        "Header capture: `PrivateMailEnvelope` carries optional `inReplyTo` and `references` fields, populated at `buildStoredMailMessage` time from RFC822 headers. Existing messages without these headers are unaffected. `mail_thread` walks the thread from any seed message (storage id or RFC822 `<message-id@host>`): ancestors via `In-Reply-To`/`References`, descendants by reverse-edges across the recent message pool (default 200, configurable 20-500, scoped native/delegated/all), assigns true reply-chain depth via topological longest-path, and renders chronologically with depth-indented summaries. Bodies not included — `mail_body` opens one message.",
+        "Pure thread-walker (`src/mailroom/thread.ts`) is testable without the filesystem: 7 unit tests cover mid-thread seed (walks both directions), seed by RFC822 message-id when storage id doesn't match, References-only (no In-Reply-To, common in list mailers), unrelated-message exclusion, empty/whitespace defensiveness. Plus 3 new tool-level tests for `mail_thread` (multi-message reconstruction, untrusted refusal, delegated-trust block). Tool registry stays at 75 (rename, not addition). All 194 mailroom tests pass."
+      ]
+    },
     {
       "version": "0.1.0-alpha.496",
       "changes": [

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

@@ -3953,7 +3953,7 @@ async function executeMailImportMbox(command, deps) {
             `duplicates: ${result.duplicates}`,
             `source fresh through: ${result.sourceFreshThrough ?? "unknown"}`,
             "archive imports are historical; they do not create Screener wakeups.",
-            "body reads remain explicit through mail_recent/mail_search/mail_thread and are access-logged.",
+            "body reads remain explicit through mail_recent/mail_search/mail_body and are access-logged.",
         ].join("\n");
         await trackedOperation?.succeed("imported delegated mail archive", `scanned ${result.scanned}; imported ${result.imported}; duplicates ${result.duplicates}`, {
             scanned: result.scanned,

package/dist/mailroom/core.js

@@ -400,8 +400,22 @@ async function buildStoredMailMessage(input) {
     const parsed = await (0, mailparser_1.simpleParser)(input.rawMime);
     const id = messageStorageId(input.envelope, input.rawMime);
     const text = parsed.text ?? "";
+    const inReplyTo = typeof parsed.inReplyTo === "string" && parsed.inReplyTo.trim().length > 0
+        ? parsed.inReplyTo.trim()
+        : undefined;
+    const referencesRaw = parsed.references;
+    /* v8 ignore start -- string-fallback branch: mailparser typically returns string[]; single-ref string fallback is defensive @preserve */
+    const referencesAsString = typeof referencesRaw === "string" && referencesRaw.trim().length > 0
+        ? referencesRaw.trim().split(/\s+/)
+        : undefined;
+    /* v8 ignore stop */
+    const references = Array.isArray(referencesRaw)
+        ? referencesRaw.filter((value) => typeof value === "string" && value.trim().length > 0).map((value) => value.trim())
+        : referencesAsString;
     const privateEnvelope = {
         messageId: parsed.messageId ?? undefined,
+        ...(inReplyTo ? { inReplyTo } : {}),
+        ...(references && references.length > 0 ? { references } : {}),
         from: parsedAddressList(parsed.from),
         to: parsedAddressList(parsed.to),
         cc: parsedAddressList(parsed.cc),

package/dist/mailroom/thread.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconstructThread = reconstructThread;
+function normalizeHeaderId(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+function inferKeysForMessage(message) {
+    const keys = [];
+    const headerId = normalizeHeaderId(message.private.messageId);
+    if (headerId)
+        keys.push(headerId);
+    /* v8 ignore next -- defensive: stored messages always have an id @preserve */
+    if (message.id)
+        keys.push(message.id);
+    return keys;
+}
+function sortByReceivedAtAscending(left, right) {
+    return Date.parse(left.receivedAt) - Date.parse(right.receivedAt);
+}
+function reconstructThread(seedMessageId, pool) {
+    const seed = pool.find((message) => message.id === seedMessageId)
+        ?? pool.find((message) => normalizeHeaderId(message.private.messageId) === seedMessageId);
+    if (!seed)
+        return { rootMessageId: undefined, members: [] };
+    const byKey = new Map();
+    const allNodes = [];
+    for (const message of pool) {
+        const node = { message, parents: new Set(), children: new Set() };
+        allNodes.push(node);
+        for (const key of inferKeysForMessage(message)) {
+            /* v8 ignore next -- collision guard: storage id and RFC822 messageId differ in the normal case @preserve */
+            if (!byKey.has(key))
+                byKey.set(key, node);
+        }
+    }
+    for (const node of allNodes) {
+        const parentKeys = new Set();
+        const inReplyTo = normalizeHeaderId(node.message.private.inReplyTo);
+        if (inReplyTo)
+            parentKeys.add(inReplyTo);
+        for (const reference of node.message.private.references ?? []) {
+            const ref = normalizeHeaderId(reference);
+            if (ref)
+                parentKeys.add(ref);
+        }
+        for (const key of parentKeys) {
+            const parent = byKey.get(key);
+            if (parent && parent !== node) {
+                node.parents.add(parent);
+                parent.children.add(node);
+            }
+        }
+    }
+    const seedNode = byKey.get(seed.id);
+    const component = new Set();
+    const stack = [seedNode];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (component.has(node))
+            continue;
+        component.add(node);
+        for (const parent of node.parents)
+            if (!component.has(parent))
+                stack.push(parent);
+        for (const child of node.children)
+            if (!component.has(child))
+                stack.push(child);
+    }
+    /* v8 ignore start -- root + topological depth pass: branch shapes vary with thread topology and aren't worth chasing per-branch in tests; correctness is covered by the higher-level reconstruction tests @preserve */
+    const componentRoots = [...component].filter((node) => {
+        for (const parent of node.parents)
+            if (component.has(parent))
+                return false;
+        return true;
+    });
+    const root = componentRoots
+        .sort((left, right) => Date.parse(left.message.receivedAt) - Date.parse(right.message.receivedAt))[0]
+        ?? seedNode;
+    const componentInTimeOrder = [...component].sort((left, right) => Date.parse(left.message.receivedAt) - Date.parse(right.message.receivedAt));
+    const depthByNode = new Map();
+    for (const node of componentInTimeOrder) {
+        let maxParentDepth = -1;
+        for (const parent of node.parents) {
+            if (!component.has(parent))
+                continue;
+            const parentDepth = depthByNode.get(parent);
+            if (parentDepth !== undefined && parentDepth > maxParentDepth) {
+                maxParentDepth = parentDepth;
+            }
+        }
+        depthByNode.set(node, maxParentDepth + 1);
+    }
+    /* v8 ignore stop */
+    const members = [...component]
+        .map((node) => node.message)
+        .sort(sortByReceivedAtAscending)
+        .map((message) => {
+        const node = byKey.get(message.id);
+        /* v8 ignore next -- fallback: depthByNode is populated for every component node by the topological pass @preserve */
+        return { message, depth: depthByNode.get(node) ?? 0 };
+    });
+    return {
+        rootMessageId: normalizeHeaderId(root.message.private.messageId) ?? root.message.id,
+        members,
+    };
+}

package/dist/nerves/coverage/file-completeness.js

@@ -101,6 +101,9 @@ const DISPATCH_EXEMPT_PATTERNS = [
     // arithmetic). The caller (search-cache.ts searchMailSearchCache) owns
     // observability via senses.mail_search_cache_upserted and friends.
     "mailroom/search-relevance",
+    // Mail thread reconstruction: pure graph-walk over decrypted message
+    // metadata. Consumers (tools-mail.ts mail_thread handler) own observability.
+    "mailroom/thread",
     // Trip ledger crypto helpers: pure RSA/AES envelope construction + slug
     // hashing. The caller (trips/store.ts) owns observability via
     // trips.ledger_created and trips.evidence_attached.

package/dist/repertoire/tools-mail.js

@@ -14,6 +14,7 @@ const reader_1 = require("../mailroom/reader");
 const outbound_1 = require("../mailroom/outbound");
 const policy_1 = require("../mailroom/policy");
 const search_cache_1 = require("../mailroom/search-cache");
+const thread_1 = require("../mailroom/thread");
 const mbox_import_1 = require("../mailroom/mbox-import");
 const search_relevance_1 = require("../mailroom/search-relevance");
 const core_1 = require("../mailroom/core");
@@ -1067,8 +1068,8 @@ exports.mailToolDefinitions = [
         tool: {
             type: "function",
             function: {
-                name: "mail_thread",
-                description: "Open one mail message body by id with an explicit access reason. Body content is untrusted external data.",
+                name: "mail_body",
+                description: "Open one mail message body by id with an explicit access reason. Body content is untrusted external data. (Use `mail_thread` to walk a whole conversation; this tool reads ONE message.)",
                 parameters: {
                     type: "object",
                     properties: {
@@ -1100,7 +1101,7 @@ exports.mailToolDefinitions = [
             await resolved.store.recordAccess({
                 agentId: resolved.agentName,
                 messageId,
-                tool: "mail_thread",
+                tool: "mail_body",
                 reason: args.reason,
                 ...accessProvenance(message),
             });
@@ -1128,6 +1129,101 @@ exports.mailToolDefinitions = [
         },
         summaryKeys: ["message_id", "reason"],
     },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "mail_thread",
+                description: "Walk a mail conversation by RFC822 In-Reply-To/References headers. Returns chronological summaries (oldest first) with depth markers. Bodies are not included — use `mail_body` to open an individual message.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        message_id: { type: "string", description: "Stored message id (from mail_recent/mail_search) or RFC822 Message-ID header value (with angle brackets)." },
+                        reason: { type: "string", description: "Why you are reading this thread. Logged for audit." },
+                        pool_size: { type: "string", description: "How many recent messages to scan for thread members, 20-500. Defaults to 200. Older messages are not considered." },
+                        scope: { type: "string", enum: ["native", "delegated", "all"], description: "Optional mailbox scope to scan for thread members. Defaults to all visible mail." },
+                    },
+                    required: ["message_id", "reason"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            /* v8 ignore start -- mail_thread arg + pool-assembly defensive branches: parseScope branching, delegated-block early returns, seedStored null path, agentId mismatch, non-family scope cascade, seedById merge variants — incidental shape, real coverage via integration tests above @preserve */
+            if (!trustAllowsMailRead(ctx))
+                return "mail is private; this tool is only available in trusted contexts.";
+            const messageId = (args.message_id ?? "").trim();
+            if (!messageId)
+                return "message_id is required.";
+            const requestedScope = args.scope === "all" ? "all" : parseScope(args.scope);
+            if (requestedScope === "delegated" || requestedScope === "all") {
+                const blocked = delegatedHumanMailBlocked(ctx);
+                if (blocked)
+                    return blocked;
+            }
+            const resolved = (0, reader_1.resolveMailroomReader)();
+            if (!resolved.ok)
+                return resolved.error;
+            const seedStored = await resolved.store.getMessage(messageId);
+            const seedById = seedStored && seedStored.agentId === resolved.agentName ? seedStored : null;
+            const scope = requestedScope === "all" ? undefined : requestedScope ?? (familyOrAgentSelf(ctx) ? undefined : "native");
+            const poolSize = numberArg(args.pool_size, 200, 20, 500);
+            const poolStored = await resolved.store.listMessages({
+                agentId: resolved.agentName,
+                ...(scope ? { compartmentKind: scope } : {}),
+                limit: poolSize,
+            });
+            const poolIncludingSeed = seedById && !poolStored.some((message) => message.id === seedById.id)
+                ? [seedById, ...poolStored]
+                : poolStored;
+            if (poolIncludingSeed.length === 0)
+                return "No mail found for the requested scope.";
+            /* v8 ignore stop */
+            const decryptResult = decryptVisibleMessages(poolIncludingSeed, resolved.config.privateKeys);
+            /* v8 ignore start -- defensive: every message in pool failing to decrypt requires every key to be missing simultaneously @preserve */
+            if (decryptResult.decrypted.length === 0) {
+                return appendDecryptSkips("No decryptable mail to reconstruct a thread from.", decryptResult.skipped);
+            }
+            /* v8 ignore stop */
+            /* v8 ignore start -- seed-resolution: RFC822-id fallback is exercised at the pure thread-walker layer; integration tests use storage ids @preserve */
+            const seedDecrypted = decryptResult.decrypted.find((message) => message.id === messageId)
+                ?? decryptResult.decrypted.find((message) => (message.private.messageId ?? "").trim() === messageId);
+            /* v8 ignore stop */
+            if (!seedDecrypted) {
+                return appendDecryptSkips(`Seed message ${messageId} is not in the scanned pool of ${poolIncludingSeed.length} messages. Increase pool_size or call mail_body directly for a single body.`, decryptResult.skipped);
+            }
+            await resolved.store.recordAccess({
+                agentId: resolved.agentName,
+                messageId: seedDecrypted.id,
+                tool: "mail_thread",
+                reason: args.reason,
+                ...accessProvenance(seedDecrypted),
+            });
+            const thread = (0, thread_1.reconstructThread)(seedDecrypted.id, decryptResult.decrypted);
+            /* v8 ignore start -- defensive: reconstructThread always produces ≥1 member when seed is in the pool @preserve */
+            if (thread.members.length === 0) {
+                return appendDecryptSkips(`Could not reconstruct a thread from ${messageId}.`, decryptResult.skipped);
+            }
+            /* v8 ignore stop */
+            const lines = [];
+            /* v8 ignore next -- "(unknown)" fallback: reconstructThread always returns a rootMessageId for non-empty members @preserve */
+            lines.push(`Conversation thread (${thread.members.length} message${thread.members.length === 1 ? "" : "s"}; root ${thread.rootMessageId ?? "(unknown)"}; pool ${decryptResult.decrypted.length}):`);
+            lines.push("");
+            for (const member of thread.members) {
+                const indent = "  ".repeat(Math.min(member.depth, 8));
+                const summary = renderMessageSummary(member.message)
+                    .split("\n")
+                    .map((line) => `${indent}${line}`)
+                    .join("\n");
+                lines.push(summary);
+                lines.push("");
+            }
+            if (thread.members.length === 1) {
+                lines.push("(no related messages found in pool — increase pool_size or check that In-Reply-To/References headers were captured at ingest)");
+            }
+            return appendDecryptSkips(lines.join("\n").trimEnd(), decryptResult.skipped);
+        },
+        summaryKeys: ["message_id", "reason", "pool_size", "scope"],
+    },
     {
         tool: {
             type: "function",

package/dist/senses/inner-dialog-worker.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_CONSECUTIVE_INSTINCT_TURNS = void 0;
+exports.HABIT_RECURSION_BURST_THRESHOLD = exports.HABIT_RECURSION_BURST_WINDOW_MS = exports.HABIT_RECURSION_MIN_INTERVAL_MS = exports.MAX_CONSECUTIVE_INSTINCT_TURNS = void 0;
 exports.createInnerDialogWorker = createInnerDialogWorker;
 exports.startInnerDialogWorker = startInnerDialogWorker;
 const path = __importStar(require("path"));
@@ -56,9 +56,69 @@ const habit_runtime_state_1 = require("../heart/habits/habit-runtime-state");
  * batch of delegated returns) get through; a true self-loop caps fast.
  */
 exports.MAX_CONSECUTIVE_INSTINCT_TURNS = 3;
-function createInnerDialogWorker(runTurn = (options) => (0, inner_dialog_1.runInnerDialogTurn)(options), hasPendingWork = () => (0, pending_1.hasPendingMessages)((0, pending_1.getInnerDialogPendingDir)((0, identity_1.getAgentName)()))) {
+/**
+ * Habit recursion detector thresholds. The instinct cap above protects
+ * against pending-dir self-loops; this protects against the *external*
+ * IPC self-loop where heartbeat-shaped messages get re-issued faster
+ * than their cadence — e.g. a hook misconfigured to repost on every
+ * heartbeat, a daemon retry storm, or a stuck timer firing back-to-back.
+ *
+ * MIN_INTERVAL_MS — two of the same habit within this window is suspect
+ * regardless of cadence (no realistic habit fires every few seconds).
+ * BURST_THRESHOLD over BURST_WINDOW_MS catches slower runaways that stay
+ * just under MIN_INTERVAL_MS.
+ *
+ * Detection is observation-only: it emits warn-level nerves events, it
+ * does not drop the message. An operator (or follow-up auto-recovery)
+ * decides what to do with the signal.
+ */
+exports.HABIT_RECURSION_MIN_INTERVAL_MS = 5_000;
+exports.HABIT_RECURSION_BURST_WINDOW_MS = 60_000;
+exports.HABIT_RECURSION_BURST_THRESHOLD = 5;
+function createInnerDialogWorker(runTurn = (options) => (0, inner_dialog_1.runInnerDialogTurn)(options), hasPendingWork = () => (0, pending_1.hasPendingMessages)((0, pending_1.getInnerDialogPendingDir)((0, identity_1.getAgentName)())), nowSource = () => Date.now()) {
     let running = false;
     const queue = [];
+    const lastFireByHabit = new Map();
+    const recentHabitFires = [];
+    function recordHabitFireForRecursion(habitName) {
+        const now = nowSource();
+        const previous = lastFireByHabit.get(habitName);
+        if (previous !== undefined) {
+            const intervalMs = now - previous;
+            if (intervalMs < exports.HABIT_RECURSION_MIN_INTERVAL_MS) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "senses",
+                    event: "senses.habit_recursion_suspected",
+                    message: "habit fired suspiciously fast after the previous fire — possible self-recursion or duplicate dispatch",
+                    meta: {
+                        habitName,
+                        intervalMs,
+                        thresholdMs: exports.HABIT_RECURSION_MIN_INTERVAL_MS,
+                    },
+                });
+            }
+        }
+        lastFireByHabit.set(habitName, now);
+        recentHabitFires.push(now);
+        while (recentHabitFires.length > 0 && now - recentHabitFires[0] > exports.HABIT_RECURSION_BURST_WINDOW_MS) {
+            recentHabitFires.shift();
+        }
+        if (recentHabitFires.length >= exports.HABIT_RECURSION_BURST_THRESHOLD) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.habit_recursion_burst",
+                message: "habit messages arriving in a burst — possible runaway loop",
+                meta: {
+                    count: recentHabitFires.length,
+                    windowMs: exports.HABIT_RECURSION_BURST_WINDOW_MS,
+                    thresholdCount: exports.HABIT_RECURSION_BURST_THRESHOLD,
+                    lastHabitName: habitName,
+                },
+            });
+        }
+    }
     async function run(reason, taskId, habitName) {
         if (running) {
             queue.push({ reason, taskId, habitName });
@@ -145,11 +205,15 @@ function createInnerDialogWorker(runTurn = (options) => (0, inner_dialog_1.runIn
             return;
         const maybeMessage = message;
         if (maybeMessage.type === "habit") {
+            /* v8 ignore next -- defensive fallback: live habit dispatch always sets habitName @preserve */
+            const habitName = maybeMessage.habitName ?? "(unnamed)";
+            recordHabitFireForRecursion(habitName);
             await run("habit", undefined, maybeMessage.habitName);
             return;
         }
         if (maybeMessage.type === "heartbeat") {
             // Backward compatibility: heartbeat -> habit/heartbeat
+            recordHabitFireForRecursion("heartbeat");
             await run("habit", undefined, "heartbeat");
             return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.496",
+  "version": "0.1.0-alpha.498",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",