@ouro.bot/cli 0.1.0-alpha.74 → 0.1.0-alpha.740

package/dist/senses/private-runtime-worker.js

@@ -0,0 +1,741 @@
+"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.HEARTBEAT_OK_REST_SUPPRESSION_MS = 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.createPrivateRuntimeWorker = createPrivateRuntimeWorker;
+exports.startPrivateRuntimeWorker = startPrivateRuntimeWorker;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const private_runtime_1 = require("./private-runtime");
+const runtime_1 = require("../nerves/runtime");
+const identity_1 = require("../heart/identity");
+const pending_1 = require("../mind/pending");
+const habit_parser_1 = require("../heart/habits/habit-parser");
+const habit_runtime_state_1 = require("../heart/habits/habit-runtime-state");
+const habit_session_1 = require("../heart/habits/habit-session");
+const flight_recorder_1 = require("../arc/flight-recorder");
+const habit_session_summary_1 = require("../heart/habits/habit-session-summary");
+const friends_1 = require("@ouro.bot/friends");
+const tools_base_1 = require("../repertoire/tools-base");
+const tools_surface_1 = require("../repertoire/tools-surface");
+const tools_1 = require("../repertoire/tools");
+const habit_policy_1 = require("../rsvp/habit-policy");
+const spend_ledger_1 = require("../rsvp/spend-ledger");
+const run_ledger_1 = require("../heart/run-ledger");
+const autonomy_budget_1 = require("../heart/autonomy-budget");
+const habit_lifecycle_guard_1 = require("./habit-lifecycle-guard");
+function isUsageData(value) {
+    const usage = value;
+    return !!usage
+        && typeof usage.input_tokens === "number"
+        && typeof usage.output_tokens === "number"
+        && typeof usage.total_tokens === "number";
+}
+function extractUsageFromHabitResults(results) {
+    const aggregate = {
+        input_tokens: 0,
+        output_tokens: 0,
+        reasoning_tokens: 0,
+        total_tokens: 0,
+    };
+    let found = false;
+    for (const result of results) {
+        if (!result || typeof result !== "object")
+            continue;
+        const usage = result.usage;
+        if (!isUsageData(usage))
+            continue;
+        found = true;
+        aggregate.input_tokens += usage.input_tokens;
+        aggregate.output_tokens += usage.output_tokens;
+        aggregate.reasoning_tokens += typeof usage.reasoning_tokens === "number" ? usage.reasoning_tokens : 0;
+        aggregate.total_tokens += usage.total_tokens;
+    }
+    return found ? aggregate : undefined;
+}
+function habitRunLedgerBase(habitRun) {
+    const target = {
+        habitName: habitRun.habit.name,
+        runId: habitRun.runId,
+        trigger: habitRun.trigger,
+        operationId: habitRun.operationId,
+    };
+    return {
+        agent: (0, identity_1.getAgentName)(),
+        triggerType: "habit",
+        sourceKind: "private-runtime",
+        senseOrHabit: habitRun.habit.name,
+        startedAt: habitRun.startedAt,
+        target,
+        idempotencyScope: target,
+        provider: "unknown",
+        model: "unknown",
+        sessionRef: {
+            channel: "inner",
+            keyHash: (0, run_ledger_1.runLedgerHash)({ habitName: habitRun.habit.name, runId: habitRun.runId }),
+        },
+    };
+}
+function recordHabitRunLedger(habitRun, lifecycle, endedAt) {
+    const usage = extractUsageFromHabitResults(habitRun.results);
+    const record = (0, run_ledger_1.createRunLedgerRecord)({
+        ...habitRunLedgerBase(habitRun),
+        lifecycle,
+        ...(endedAt ? { endedAt } : {}),
+        ...(lifecycle === "completed" || lifecycle === "error"
+            ? { usage: (0, run_ledger_1.usageMetadataFromUsageData)(usage, usage ? "provider" : "none") }
+            : {}),
+    });
+    (0, run_ledger_1.appendRunLedgerRecordNonFatal)(habitRun.agentRoot, record);
+    if (habitRun.rsvpPolicy) {
+        try {
+            (0, spend_ledger_1.recordRsvpSpendLedgerRun)(habitRun.agentRoot, record);
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "rsvp",
+                event: "rsvp.spend_ledger_record_error",
+                message: "failed to record RSVP spend ledger row",
+                meta: { runId: record.runId, lifecycle, error: String(error) },
+            });
+        }
+    }
+}
+function reserveHabitAutonomyBudget(habitRun, nowIso) {
+    const target = {
+        habitName: habitRun.habit.name,
+        runId: habitRun.runId,
+        trigger: habitRun.trigger,
+        operationId: habitRun.operationId,
+    };
+    if (habitRun.rsvpPolicy) {
+        target.rsvpSnapshotRef = habitRun.rsvpPolicy.snapshotRef;
+        target.rsvpBudgetRef = habitRun.rsvpPolicy.budgetRef;
+        target.rsvpIdempotencyRef = habitRun.rsvpPolicy.idempotencyRef;
+    }
+    const agentName = (0, identity_1.getAgentName)();
+    return (0, autonomy_budget_1.reserveAutonomyBudget)(habitRun.agentRoot, {
+        agent: agentName,
+        triggerType: "habit",
+        sourceKind: "private-runtime",
+        senseOrHabit: habitRun.habit.name,
+        target,
+        idempotencyKey: `habit:${habitRun.habit.name}:${habitRun.runId}`,
+        now: nowIso,
+    }, (0, autonomy_budget_1.resolveAutonomyBudgetPolicy)(habitRun.agentRoot, agentName));
+}
+/**
+ * Cap on consecutive `instinct` follow-on turns triggered by `hasPendingWork()`
+ * with no externally-queued work in between. Without this cap, a turn that
+ * writes anything back into the private-runtime pending dir as a side effect of
+ * processing (e.g. a surface tool routing a response) puts the worker into
+ * a self-sustaining loop where the next turn's drain produces another write,
+ * and so on. Real workflows rarely chain more than 2–3 instinct turns; an
+ * external trigger (habit, poke, chat) resets the counter so legitimate
+ * follow-on work is unaffected.
+ *
+ * Three feels right: legitimate cascading follow-ups (e.g. processing a
+ * batch of delegated returns) get through; a true self-loop caps fast.
+ */
+exports.MAX_CONSECUTIVE_INSTINCT_TURNS = 3;
+/**
+ * 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;
+exports.HEARTBEAT_OK_REST_SUPPRESSION_MS = 20 * 60_000;
+function defaultHasPendingWork(pendingDir) {
+    if (pendingDir)
+        return (0, pending_1.hasPendingMessages)(pendingDir);
+    const agentArgIndex = process.argv.indexOf("--agent");
+    const agentName = agentArgIndex >= 0 ? process.argv[agentArgIndex + 1] : undefined;
+    return agentName ? (0, pending_1.hasPendingMessages)((0, pending_1.getPrivateRuntimePendingDir)(agentName)) : false;
+}
+function isHeartbeatOkRestResult(result) {
+    if (!result || typeof result !== "object")
+        return false;
+    const maybeResult = result;
+    return maybeResult.turnOutcome === "rested" && maybeResult.restStatus === "HEARTBEAT_OK";
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function contentToText(content) {
+    if (typeof content === "string")
+        return content.trim();
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => isRecord(part) && typeof part.text === "string" ? part.text : "")
+        .filter((text) => text.trim().length > 0)
+        .join("\n")
+        .trim();
+}
+function resultMessages(result) {
+    if (Array.isArray(result))
+        return result.flatMap((entry) => resultMessages(entry));
+    return isRecord(result) && Array.isArray(result.messages) ? result.messages : [];
+}
+function latestAssistantText(results) {
+    for (let resultIndex = results.length - 1; resultIndex >= 0; resultIndex--) {
+        const messages = resultMessages(results[resultIndex]);
+        for (let messageIndex = messages.length - 1; messageIndex >= 0; messageIndex--) {
+            const message = messages[messageIndex];
+            if (!isRecord(message) || message.role !== "assistant")
+                continue;
+            const text = contentToText(message.content);
+            if (text.length > 0)
+                return text.replace(/^checkpoint\s*:\s*/i, "").trim() || text;
+        }
+    }
+    return null;
+}
+function deriveHabitSummarySnapshot(habitRun) {
+    const assistant = latestAssistantText(habitRun.results);
+    if (assistant)
+        return { summary: assistant, decisions: [], nextLikelyStep: null };
+    if (habitRun.errors.length > 0) {
+        return {
+            summary: `Habit ${habitRun.habit.name} finished with errors: ${habitRun.errors.join("; ")}`,
+            decisions: [],
+            nextLikelyStep: null,
+        };
+    }
+    const surfaced = habitRun.surfaceAttempts.find((attempt) => attempt.result !== "blocked" && attempt.result !== "failed" && attempt.result !== "unavailable");
+    if (surfaced) {
+        return {
+            summary: `Habit ${habitRun.habit.name} surfaced via ${surfaced.recipient}/${surfaced.channel}.`,
+            decisions: [],
+            nextLikelyStep: null,
+        };
+    }
+    const produced = habitRun.producedRefs.find((ref) => ref.kind !== "none");
+    if (produced) {
+        return {
+            summary: `Habit ${habitRun.habit.name} produced ${produced.kind}: ${produced.locator}.`,
+            decisions: [],
+            nextLikelyStep: null,
+        };
+    }
+    if (habitRun.results.some(isHeartbeatOkRestResult)) {
+        return {
+            summary: `Habit ${habitRun.habit.name} rested with HEARTBEAT_OK.`,
+            decisions: [],
+            nextLikelyStep: null,
+        };
+    }
+    return {
+        summary: `Habit ${habitRun.habit.name} completed without additional surfaced output.`,
+        decisions: [],
+        nextLikelyStep: null,
+    };
+}
+function readHabitForRun(agentRoot, habitName, errors) {
+    const habitPath = path.join(agentRoot, "habits", `${habitName}.md`);
+    try {
+        return (0, habit_parser_1.parseHabitFile)(fs.readFileSync(habitPath, "utf-8"), habitPath);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        errors.push(`habit file could not be read: ${reason}`);
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.habit_file_read_error",
+            message: "habit file could not be read for habit session",
+            meta: { habitName, habitPath, reason },
+        });
+        return (0, habit_parser_1.createDegradedHabitFile)(habitPath, "read_error");
+    }
+}
+async function prepareHabitRun(habitName, trigger, startedAt) {
+    const agentRoot = (0, identity_1.getAgentRoot)();
+    const errors = [];
+    const habit = (0, habit_runtime_state_1.applyHabitRuntimeState)(agentRoot, readHabitForRun(agentRoot, habitName, errors));
+    if (habit.status === "degraded" && habit.degradedDetail !== null) {
+        errors.push(habit.degradedDetail);
+    }
+    const lifecycleBlockedReason = (0, habit_lifecycle_guard_1.privateRuntimeHabitRejectionReason)(habit, "private-runtime-worker");
+    const blockedReason = (0, habit_policy_1.isRsvpHabitName)(habitName) && !habit.rsvp
+        ? "RSVP habit metadata is required before private runtime execution"
+        : lifecycleBlockedReason;
+    if (blockedReason && !errors.includes(blockedReason))
+        errors.push(blockedReason);
+    const runId = (0, flight_recorder_1.createHabitRunId)(habitName, new Date(startedAt));
+    const operationId = habit.continuity.mode === "stateful" ? `habit:${habit.name}` : null;
+    const priorSessionSummary = readPriorSessionSummary(agentRoot, operationId);
+    const paths = (0, habit_session_1.createHabitSessionPaths)(agentRoot, runId, habit.name);
+    const friendStore = new friends_1.FileFriendStore(path.join(agentRoot, "friends"));
+    const permissionEnvelope = await (0, habit_session_1.normalizeHabitPermissionEnvelope)(habit, { agentRoot, friendStore });
+    const rsvpPolicy = habit.rsvp ? (0, habit_policy_1.rsvpHabitRuntimePolicy)(habit.rsvp) : undefined;
+    const requestedTools = blockedReason ? [] : habit.rsvp ? [...habit_policy_1.RSVP_HABIT_ALLOWED_TOOLS] : habit.tools ?? null;
+    const toolPolicy = (0, habit_session_1.filterHabitToolsForEnvelope)([...tools_base_1.baseToolDefinitions, tools_surface_1.surfaceToolDefinition], requestedTools, permissionEnvelope, riskProfileForHabitPolicy);
+    return {
+        agentRoot,
+        habit,
+        runId,
+        operationId,
+        trigger,
+        startedAt,
+        priorSessionSummary,
+        paths,
+        permissionEnvelope,
+        toolPolicy,
+        ...(rsvpPolicy ? { rsvpPolicy } : {}),
+        ...(blockedReason ? { blockedReason } : {}),
+        friendStore,
+        results: [],
+        errors,
+        producedRefs: [],
+        surfaceAttempts: [],
+    };
+}
+function riskProfileForHabitPolicy(definition, name) {
+    const probeArgs = name === "shell" ? { command: "touch /tmp/habit-policy-probe" } : {};
+    return (0, tools_1.riskProfileForTool)(definition, name, probeArgs);
+}
+function readPriorSessionSummary(agentRoot, operationId) {
+    if (operationId === null)
+        return undefined;
+    try {
+        const summary = (0, habit_session_summary_1.readHabitSessionSummary)(agentRoot, { operationId, which: "latest" });
+        if (!summary)
+            return { mode: "stateful", summary: null, sources: {}, warnings: [] };
+        return {
+            mode: "stateful",
+            summary: summary.summary,
+            sources: summary.sources,
+            warnings: summary.warnings,
+        };
+    }
+    catch (error) {
+        return {
+            mode: "stateful",
+            summary: null,
+            sources: {},
+            warnings: [`prior summary read failed: ${String(error)}`],
+        };
+    }
+}
+function createPrivateRuntimeWorker(runTurn = (options) => (0, private_runtime_1.runPrivateRuntimeTurn)(options), hasPendingWork = defaultHasPendingWork, nowSource = () => Date.now()) {
+    let running = false;
+    const queue = [];
+    const lastFireByHabit = new Map();
+    const recentHabitFires = [];
+    const startedHabitLedgerRunIds = new Set();
+    let heartbeatOkRestedAt = null;
+    function recordHabitStartIfNeeded(habitRun) {
+        if (startedHabitLedgerRunIds.has(habitRun.runId))
+            return;
+        recordHabitRunLedger(habitRun, "started");
+        startedHabitLedgerRunIds.add(habitRun.runId);
+    }
+    function recordHabitCompletion(habitRun, endedAt = habitRun.startedAt) {
+        recordHabitStartIfNeeded(habitRun);
+        recordHabitRunLedger(habitRun, habitRun.errors.length > 0 ? "error" : "completed", endedAt);
+        (0, habit_session_1.completeHabitRun)({
+            agentRoot: habitRun.agentRoot,
+            habit: habitRun.habit,
+            runId: habitRun.runId,
+            trigger: habitRun.trigger,
+            startedAt: habitRun.startedAt,
+            endedAt,
+            operationId: habitRun.operationId,
+            permissionEnvelope: habitRun.permissionEnvelope,
+            toolPolicy: habitRun.toolPolicy,
+            producedRefs: habitRun.producedRefs,
+            surfaceAttempts: habitRun.surfaceAttempts,
+            errors: habitRun.errors,
+            summarySnapshot: deriveHabitSummarySnapshot(habitRun),
+        });
+    }
+    function clearHeartbeatRestShield() {
+        heartbeatOkRestedAt = null;
+    }
+    function shouldReuseHeartbeatOkRest(habitName) {
+        if (habitName !== "heartbeat" || heartbeatOkRestedAt === null)
+            return false;
+        if (nowSource() - heartbeatOkRestedAt > exports.HEARTBEAT_OK_REST_SUPPRESSION_MS)
+            return false;
+        if (hasPendingWork()) {
+            clearHeartbeatRestShield();
+            return false;
+        }
+        return true;
+    }
+    async function reuseHeartbeatOkRest(habitName) {
+        const nowIso = new Date(nowSource()).toISOString();
+        const habitRun = await prepareHabitRun(habitName, "overdue", nowIso);
+        if (habitRun.blockedReason) {
+            clearHeartbeatRestShield();
+            recordHabitCompletion(habitRun, nowIso);
+            return;
+        }
+        habitRun.results.push({ turnOutcome: "rested", restStatus: "HEARTBEAT_OK" });
+        recordHabitCompletion(habitRun, nowIso);
+        (0, runtime_1.emitNervesEvent)({
+            level: "info",
+            component: "senses",
+            event: "senses.heartbeat_ok_rest_reused",
+            message: "heartbeat skipped because previous HEARTBEAT_OK rest is still valid and no pending work exists",
+            meta: {
+                habitName,
+                quietWindowMs: exports.HEARTBEAT_OK_REST_SUPPRESSION_MS,
+                restedAgoMs: nowSource() - heartbeatOkRestedAt,
+            },
+        });
+    }
+    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, awaitName, trigger, privateTurnDecision, noSend) {
+        if (running) {
+            queue.push({ reason, taskId, habitName, awaitName, trigger, privateTurnDecision, noSend });
+            return;
+        }
+        running = true;
+        try {
+            let nextReason = reason;
+            let nextTaskId = taskId;
+            let nextHabitName = habitName;
+            let nextAwaitName = awaitName;
+            let nextTrigger = trigger;
+            let nextPrivateTurnDecision = privateTurnDecision;
+            let nextNoSend = reason === "habit" ? noSend : undefined;
+            let nextHabitRun = null;
+            let consecutiveInstinctTurns = reason === "instinct" ? 1 : 0;
+            runLoop: do {
+                const currentReason = nextReason;
+                const currentHabitName = nextHabitName;
+                const currentTrigger = nextTrigger ?? "overdue";
+                const currentNoSend = nextNoSend;
+                const currentHabitRun = currentReason === "habit" && currentHabitName
+                    ? nextHabitRun && nextHabitRun.habit.name === currentHabitName
+                        ? nextHabitRun
+                        : await prepareHabitRun(currentHabitName, currentTrigger, new Date(nowSource()).toISOString())
+                    : null;
+                nextHabitRun = null;
+                let currentHabitRunFinalized = false;
+                const finalizeCurrentHabitRun = () => {
+                    if (!currentHabitRun || currentHabitRunFinalized)
+                        return;
+                    recordHabitCompletion(currentHabitRun, new Date(nowSource()).toISOString());
+                    currentHabitRunFinalized = true;
+                };
+                const turnErrors = [];
+                if (!(currentReason === "habit" && currentHabitName === "heartbeat")) {
+                    clearHeartbeatRestShield();
+                }
+                let turnResult;
+                let blockedAutonomyTurn = false;
+                try {
+                    const turnStartedAt = new Date(nowSource()).toISOString();
+                    const autonomyDecision = currentHabitRun && !currentHabitRun.blockedReason
+                        ? reserveHabitAutonomyBudget(currentHabitRun, turnStartedAt)
+                        : null;
+                    if (currentHabitRun)
+                        recordHabitStartIfNeeded(currentHabitRun);
+                    if (currentHabitRun?.blockedReason) {
+                        blockedAutonomyTurn = true;
+                        turnResult = {
+                            turnOutcome: "blocked",
+                            reason: currentHabitRun.blockedReason,
+                        };
+                        clearHeartbeatRestShield();
+                    }
+                    else if (autonomyDecision && !autonomyDecision.allowed) {
+                        blockedAutonomyTurn = true;
+                        const reason = `autonomy budget blocked: ${autonomyDecision.reason}`;
+                        turnErrors.push(reason);
+                        turnResult = {
+                            turnOutcome: "blocked",
+                            reason,
+                            autonomyReceiptId: autonomyDecision.receiptId,
+                        };
+                        clearHeartbeatRestShield();
+                    }
+                    else {
+                        const turnOptions = {
+                            reason: nextReason,
+                            taskId: nextTaskId,
+                            habitName: nextHabitName,
+                            awaitName: nextAwaitName,
+                            ...(currentNoSend ? { noSend: true } : {}),
+                            ...(nextPrivateTurnDecision ? { privateTurnDecision: nextPrivateTurnDecision } : {}),
+                            ...(currentHabitRun
+                                ? {
+                                    trigger: currentHabitRun.trigger,
+                                    preparedHabit: {
+                                        runId: currentHabitRun.runId,
+                                        trigger: currentHabitRun.trigger,
+                                        operationId: currentHabitRun.operationId,
+                                        habit: currentHabitRun.habit,
+                                        priorSessionSummary: currentHabitRun.priorSessionSummary,
+                                    },
+                                    habitSession: {
+                                        runId: currentHabitRun.runId,
+                                        sessionPath: currentHabitRun.paths.sessionPath,
+                                        pendingDir: currentHabitRun.paths.pendingDir,
+                                        permissionEnvelope: currentHabitRun.permissionEnvelope,
+                                        toolPolicy: currentHabitRun.toolPolicy,
+                                        ...(currentHabitRun.rsvpPolicy ? { rsvpPolicy: currentHabitRun.rsvpPolicy } : {}),
+                                        friendStore: currentHabitRun.friendStore,
+                                        recordProducedRef: (ref) => { currentHabitRun.producedRefs.push(ref); },
+                                        recordSurfaceAttempt: (attempt) => { currentHabitRun.surfaceAttempts.push(attempt); },
+                                        recordError: (error) => { currentHabitRun.errors.push(error); },
+                                    },
+                                }
+                                : {}),
+                        };
+                        turnResult = await runTurn(turnOptions);
+                    }
+                }
+                catch (error) {
+                    clearHeartbeatRestShield();
+                    turnErrors.push(error instanceof Error ? error.message : String(error));
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "error",
+                        component: "senses",
+                        event: "senses.private_runtime_worker_error",
+                        message: "private-runtime worker turn failed",
+                        meta: {
+                            reason: nextReason,
+                            error: error instanceof Error ? error.message : String(error),
+                        },
+                    });
+                }
+                if (currentReason === "habit" && currentHabitName === "heartbeat") {
+                    heartbeatOkRestedAt = isHeartbeatOkRestResult(turnResult) ? nowSource() : null;
+                }
+                if (currentHabitRun) {
+                    currentHabitRun.results.push(turnResult);
+                    currentHabitRun.errors.push(...turnErrors);
+                }
+                // Drain queue first. Externally-queued work resets the instinct cap
+                // because a real outside trigger arrived between turns.
+                while (queue.length > 0) {
+                    const next = queue.shift();
+                    if (next.reason === "habit" && next.habitName === "heartbeat" && shouldReuseHeartbeatOkRest(next.habitName)) {
+                        finalizeCurrentHabitRun();
+                        await reuseHeartbeatOkRest(next.habitName);
+                        continue;
+                    }
+                    if (!(next.reason === "habit" && next.habitName === "heartbeat")) {
+                        clearHeartbeatRestShield();
+                    }
+                    finalizeCurrentHabitRun();
+                    nextReason = next.reason;
+                    nextTaskId = next.taskId;
+                    nextHabitName = next.habitName;
+                    nextAwaitName = next.awaitName;
+                    nextTrigger = next.trigger;
+                    nextPrivateTurnDecision = next.privateTurnDecision;
+                    nextNoSend = next.reason === "habit" ? next.noSend : undefined;
+                    consecutiveInstinctTurns = nextReason === "instinct" ? consecutiveInstinctTurns + 1 : 0;
+                    continue runLoop;
+                }
+                if (blockedAutonomyTurn) {
+                    finalizeCurrentHabitRun();
+                    break;
+                }
+                // Then check hasPendingWork fallback. This is the loop site: any
+                // tool that writes to the private-runtime pending dir during a turn
+                // would cause hasPendingWork() to be true here, producing a
+                // self-sustaining "instinct" loop with no external input. Cap it.
+                if (hasPendingWork(currentHabitRun?.paths.pendingDir)) {
+                    clearHeartbeatRestShield();
+                    if (consecutiveInstinctTurns >= exports.MAX_CONSECUTIVE_INSTINCT_TURNS) {
+                        (0, runtime_1.emitNervesEvent)({
+                            level: "warn",
+                            component: "senses",
+                            event: "senses.private_runtime_worker_instinct_loop_capped",
+                            message: "private-runtime worker stopped chaining instinct turns; pending work remains for next external trigger",
+                            meta: {
+                                consecutiveInstinctTurns,
+                                cap: exports.MAX_CONSECUTIVE_INSTINCT_TURNS,
+                                lastReason: nextReason,
+                            },
+                        });
+                        finalizeCurrentHabitRun();
+                        break;
+                    }
+                    if (currentReason === "habit" && currentHabitName && currentHabitRun) {
+                        consecutiveInstinctTurns += 1;
+                        nextReason = "habit";
+                        nextTaskId = undefined;
+                        nextHabitName = currentHabitName;
+                        nextAwaitName = undefined;
+                        nextTrigger = currentTrigger;
+                        nextPrivateTurnDecision = undefined;
+                        nextNoSend = currentNoSend;
+                        nextHabitRun = currentHabitRun;
+                    }
+                    else {
+                        finalizeCurrentHabitRun();
+                        consecutiveInstinctTurns += 1;
+                        nextReason = "instinct";
+                        nextTaskId = undefined;
+                        nextHabitName = undefined;
+                        nextAwaitName = undefined;
+                        nextTrigger = undefined;
+                        nextPrivateTurnDecision = undefined;
+                        nextNoSend = undefined;
+                    }
+                    continue;
+                }
+                finalizeCurrentHabitRun();
+                break;
+            } while (true);
+        }
+        finally {
+            running = false;
+        }
+    }
+    async function handleMessage(message) {
+        if (!message || typeof message !== "object")
+            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)";
+            if (shouldReuseHeartbeatOkRest(habitName)) {
+                await reuseHeartbeatOkRest(habitName);
+                return;
+            }
+            recordHabitFireForRecursion(habitName);
+            await run("habit", undefined, maybeMessage.habitName, undefined, maybeMessage.trigger ?? "overdue", maybeMessage.privateTurnDecision, maybeMessage.noSend);
+            return;
+        }
+        if (maybeMessage.type === "await") {
+            clearHeartbeatRestShield();
+            /* v8 ignore next -- defensive fallback: live await dispatch always sets awaitName @preserve */
+            const awaitName = maybeMessage.awaitName ?? "(unnamed)";
+            recordHabitFireForRecursion(`await:${awaitName}`);
+            await run("await", undefined, undefined, maybeMessage.awaitName, undefined, maybeMessage.privateTurnDecision);
+            return;
+        }
+        if (maybeMessage.type === "heartbeat") {
+            // Backward compatibility: heartbeat -> habit/heartbeat
+            if (shouldReuseHeartbeatOkRest("heartbeat")) {
+                await reuseHeartbeatOkRest("heartbeat");
+                return;
+            }
+            recordHabitFireForRecursion("heartbeat");
+            await run("habit", undefined, "heartbeat", undefined, "overdue", maybeMessage.privateTurnDecision);
+            return;
+        }
+        if (maybeMessage.type === "poke") {
+            clearHeartbeatRestShield();
+            await run("instinct", maybeMessage.taskId, undefined, undefined, undefined, maybeMessage.privateTurnDecision);
+            return;
+        }
+        if (maybeMessage.type === "chat" ||
+            maybeMessage.type === "message") {
+            clearHeartbeatRestShield();
+            await run("instinct", undefined, undefined, undefined, undefined, maybeMessage.privateTurnDecision);
+            return;
+        }
+        if (maybeMessage.type === "shutdown") {
+            process.exit(0);
+        }
+    }
+    return { run, handleMessage };
+}
+async function startPrivateRuntimeWorker(options = {}) {
+    const worker = createPrivateRuntimeWorker();
+    if (options.attachProcessListeners ?? true) {
+        process.on("message", (message) => {
+            void worker.handleMessage(message);
+        });
+        process.on("disconnect", () => {
+            process.exit(0);
+        });
+    }
+    for (const message of options.bufferedMessages ?? []) {
+        void worker.handleMessage(message);
+    }
+    return worker;
+}