@ouro.bot/cli 0.1.0-alpha.75 → 0.1.0-alpha.750

package/dist/heart/start-of-turn-packet.js

@@ -0,0 +1,368 @@
+"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.buildCapabilitiesSection = buildCapabilitiesSection;
+exports.buildStartOfTurnPacket = buildStartOfTurnPacket;
+exports.renderStartOfTurnPacket = renderStartOfTurnPacket;
+exports.renderCompactStartOfTurnPacket = renderCompactStartOfTurnPacket;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../nerves/runtime");
+const bundle_state_1 = require("./bundle-state");
+const tempo_1 = require("./tempo");
+const flight_recorder_1 = require("../arc/flight-recorder");
+const context_loss_sentinel_1 = require("./context-loss-sentinel");
+const orientation_frame_1 = require("./orientation-frame");
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+// --- Section builders (pure derivation from authored data, no embellishment) ---
+function buildPlotLine(episodes, tempo) {
+    if (episodes.length === 0)
+        return "";
+    const limit = tempo === "crisis" ? 3 : tempo === "brief" ? 2 : 5;
+    const selected = episodes.slice(0, limit);
+    const lines = selected.map((ep) => {
+        const parts = [`- ${ep.summary}`];
+        if (ep.whyItMattered && tempo !== "brief") {
+            parts[0] += ` (${ep.whyItMattered})`;
+        }
+        return parts[0];
+    });
+    return lines.join("\n");
+}
+function buildObligationsSection(obligations) {
+    if (obligations.length === 0)
+        return "";
+    return obligations
+        .map((ob) => {
+        const parts = [`- ${ob.content}`];
+        if (ob.meaning?.resumeHint) {
+            parts.push(` [hint: ${ob.meaning.resumeHint}]`);
+        }
+        if (ob.meaning?.stalenessClass && ob.meaning.stalenessClass !== "fresh") {
+            parts.push(` (${ob.meaning.stalenessClass})`);
+        }
+        if (ob.meaning?.waitingOn) {
+            parts.push(` waiting on ${ob.meaning.waitingOn.kind}: ${ob.meaning.waitingOn.target}`);
+        }
+        return parts.join("");
+    })
+        .join("\n");
+}
+function buildCaresSection(cares) {
+    if (cares.length === 0)
+        return "";
+    return cares
+        .map((c) => {
+        const parts = [`- ${c.label}`];
+        if (c.salience !== "low") {
+            parts.push(` [${c.salience}]`);
+        }
+        if (c.currentRisk) {
+            parts.push(` risk: ${c.currentRisk}`);
+        }
+        return parts.join("");
+    })
+        .join("\n");
+}
+function buildPresenceSection(peers) {
+    if (peers.length === 0)
+        return "";
+    return peers
+        .map((p) => `- ${p.agentName}: ${p.availability}/${p.lane}`)
+        .join("\n");
+}
+function buildResumeHint(view, obligations) {
+    // Compose from authored obligation resumeHints and top intentions
+    const hints = [];
+    const effectiveObligations = obligations ?? view.activeObligations;
+    for (const ob of effectiveObligations) {
+        if (ob.meaning?.resumeHint) {
+            hints.push(ob.meaning.resumeHint);
+        }
+    }
+    for (const intent of view.openIntentions.slice(0, 3)) {
+        hints.push(intent.content);
+    }
+    if (hints.length === 0) {
+        // Fall back to top obligation content
+        if (effectiveObligations.length > 0) {
+            hints.push(effectiveObligations[0].content);
+        }
+    }
+    if (hints.length === 0)
+        return "";
+    return hints.join("; ");
+}
+/**
+ * Build a compact summary of capability changes between runtime versions.
+ * Reads bundle-meta.json for version info and changelog.json for change descriptions.
+ * Returns undefined if no version change detected or files are missing/malformed.
+ */
+function buildCapabilitiesSection(bundleRoot) {
+    let meta;
+    try {
+        const raw = fs.readFileSync(path.join(bundleRoot, "bundle-meta.json"), "utf-8");
+        meta = JSON.parse(raw);
+    }
+    catch {
+        (0, runtime_1.emitNervesEvent)({
+            component: "heart",
+            event: "heart.capabilities_check",
+            message: "bundle-meta.json missing or malformed",
+            meta: { bundleRoot },
+        });
+        return undefined;
+    }
+    const currentVersion = meta.runtimeVersion;
+    const previousVersion = meta.previousRuntimeVersion;
+    if (typeof currentVersion !== "string" || typeof previousVersion !== "string") {
+        return undefined;
+    }
+    if (currentVersion === previousVersion) {
+        return undefined;
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.capabilities_version_change",
+        message: `runtime version changed from ${previousVersion} to ${currentVersion}`,
+        meta: { previousVersion, currentVersion },
+    });
+    let changelog;
+    try {
+        const raw = fs.readFileSync(path.join(bundleRoot, "changelog.json"), "utf-8");
+        changelog = JSON.parse(raw);
+    }
+    catch {
+        // changelog missing -- still report the version change
+    }
+    const parts = [`Updated from ${previousVersion} to ${currentVersion}`];
+    if (changelog && Array.isArray(changelog)) {
+        const relevantChanges = [];
+        for (const entry of changelog) {
+            if (entry.version === previousVersion)
+                break;
+            if (Array.isArray(entry.changes)) {
+                relevantChanges.push(...entry.changes);
+            }
+        }
+        if (relevantChanges.length > 0) {
+            parts.push(`: ${relevantChanges.join("; ")}`);
+        }
+    }
+    return parts.join("");
+}
+function buildStartOfTurnPacket(view, opts) {
+    const tempo = view.tempo;
+    const tokenBudget = tempo_1.TEMPO_BUDGETS[tempo];
+    const effectiveObligations = opts?.canonicalObligations ? opts.canonicalObligations.all : view.activeObligations;
+    const packet = {
+        plotLine: buildPlotLine(view.recentEpisodes, tempo),
+        obligations: buildObligationsSection(effectiveObligations),
+        cares: buildCaresSection(view.activeCares),
+        presence: buildPresenceSection(view.peerPresence),
+        arcResume: opts?.flightRecorderResume ? (0, flight_recorder_1.formatFlightRecorderResume)(opts.flightRecorderResume) : undefined,
+        recoverySentinel: opts?.recoverySentinel,
+        resumeHint: buildResumeHint(view, opts?.canonicalObligations ? effectiveObligations : undefined),
+        currentSessionTiming: opts?.currentSessionTiming,
+        friendContactTiming: opts?.friendContactTiming,
+        tempo,
+        tokenBudget,
+        assembledAt: new Date().toISOString(),
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.start_of_turn_packet_built",
+        message: `start-of-turn packet built: tempo=${tempo}`,
+        meta: {
+            tempo,
+            plotLineTokens: estimateTokens(packet.plotLine),
+            obligationsTokens: estimateTokens(packet.obligations),
+            caresTokens: estimateTokens(packet.cares),
+            presenceTokens: estimateTokens(packet.presence),
+            resumeHintTokens: estimateTokens(packet.resumeHint),
+        },
+    });
+    return packet;
+}
+/**
+ * Renders a start-of-turn packet to prompt text, respecting token budget.
+ * Truncation priority (last truncated first):
+ *   resumeHint (PROTECTED) > obligations > cares > plotLine > presence
+ * So presence is truncated first, then plotLine, then cares, then obligations.
+ * resumeHint is never truncated.
+ */
+function renderStartOfTurnPacket(packet, options = {}) {
+    const budget = packet.tokenBudget;
+    const resumePriorWork = options.resumePriorWork === true;
+    // Assemble sections in priority order (highest priority first for budget allocation)
+    // Each section is { label, content, priority } where lower priority number = truncated first
+    const sections = [
+        // bundleState and syncFailure share the top remediation tier — both
+        // are actionable "fix your git" signals. bundleState is preferred
+        // because it's structured (array of enum values) while syncFailure is
+        // a legacy free-form string; both render when populated.
+        { label: "provider", content: packet.providerSelection ?? "", priority: 8 },
+        { label: "bundleState", content: (0, bundle_state_1.renderBundleStateHint)(packet.bundleState ?? []), priority: 7 },
+        { label: "syncFailure", content: packet.syncFailure ?? "", priority: 7 },
+        { label: "arc", content: packet.arcResume ?? "", priority: 7 },
+        { label: "recoverySentinel", content: packet.recoverySentinel ? (0, context_loss_sentinel_1.formatContextLossSentinelText)(packet.recoverySentinel) : "", priority: 7 },
+        { label: "resume", content: packet.resumeHint, priority: 6 },
+        { label: "friendContact", content: packet.friendContactTiming ?? "", priority: 6 },
+        { label: "sessionTiming", content: packet.currentSessionTiming ?? "", priority: 5 },
+        { label: "obligations", content: packet.obligations, priority: 5 },
+        { label: "cares", content: packet.cares, priority: 4 },
+        { label: "plot", content: packet.plotLine, priority: 3 },
+        { label: "capabilities", content: packet.capabilities ?? "", priority: 2 },
+        { label: "presence", content: packet.presence, priority: 1 },
+    ].filter((s) => s.content.length > 0);
+    if (sections.length === 0) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "heart",
+            event: "heart.start_of_turn_packet_rendered",
+            message: "start-of-turn packet rendered: empty",
+            meta: { tokens: 0, tempo: packet.tempo },
+        });
+        return "";
+    }
+    // Build the rendered output, truncating lower-priority sections first
+    let rendered = formatSections(sections, resumePriorWork);
+    let tokens = estimateTokens(rendered);
+    // Truncate sections from lowest priority until we fit budget
+    const sortedByPriority = [...sections].sort((a, b) => a.priority - b.priority);
+    for (const section of sortedByPriority) {
+        if (tokens <= budget.max)
+            break;
+        // Skip continuity sections — they are protected.
+        if (section.label === "resume" || section.label === "arc" || section.label === "recoverySentinel" || section.label === "friendContact" || section.label === "sessionTiming")
+            continue;
+        // Remove this section entirely
+        const idx = sections.findIndex((s) => s.label === section.label);
+        sections.splice(idx, 1);
+        rendered = formatSections(sections, resumePriorWork);
+        tokens = estimateTokens(rendered);
+    }
+    // If still over budget after removing all non-protected sections, trim what's left
+    if (tokens > budget.max) {
+        const maxChars = budget.max * 4;
+        rendered = rendered.slice(0, maxChars);
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.start_of_turn_packet_rendered",
+        message: `start-of-turn packet rendered: ${tokens} tokens`,
+        meta: { tokens, tempo: packet.tempo, sectionCount: sections.length },
+    });
+    return rendered;
+}
+function formatSections(sections, resumePriorWork) {
+    const parts = [];
+    for (const section of sections) {
+        switch (section.label) {
+            case "resume":
+                parts.push((0, orientation_frame_1.labelPriorWorkSurface)(`**Next:**\n${section.content}`, resumePriorWork));
+                break;
+            case "arc":
+                parts.push((0, orientation_frame_1.labelPriorWorkSurface)(`**Arc:**\n${section.content}`, resumePriorWork));
+                break;
+            case "recoverySentinel":
+                parts.push((0, orientation_frame_1.labelPriorWorkSurface)(`**Recovery Sentinel:**\n${section.content}`, resumePriorWork));
+                break;
+            case "sessionTiming":
+                parts.push(`**Thread timing:** ${section.content}`);
+                break;
+            case "friendContact":
+                parts.push(`**Recent contact:** ${section.content}`);
+                break;
+            case "obligations":
+                parts.push((0, orientation_frame_1.labelPriorWorkSurface)(`**Owed:**\n${section.content}`, resumePriorWork));
+                break;
+            case "cares":
+                parts.push(`**Cares:**\n${section.content}`);
+                break;
+            case "plot":
+                parts.push(`**Recent:**\n${section.content}`);
+                break;
+            case "presence":
+                parts.push(`**Peers:**\n${section.content}`);
+                break;
+            case "capabilities":
+                parts.push(`**Capabilities:** ${section.content}`);
+                break;
+            case "syncFailure":
+                parts.push(`**Sync warning:** ${section.content}`);
+                break;
+            case "bundleState":
+                parts.push(`**Bundle:** ${section.content}`);
+                break;
+            case "provider":
+                parts.push(`**Provider:**\n${section.content}`);
+                break;
+        }
+    }
+    return parts.join("\n\n");
+}
+/**
+ * Ultra-compact version for coding context (max 200 tokens).
+ * Just resumeHint + top obligation + top care, single-line bullets.
+ */
+function renderCompactStartOfTurnPacket(packet, options = {}) {
+    const parts = [];
+    const instruction = (0, orientation_frame_1.priorWorkInstruction)(options.resumePriorWork === true);
+    if (packet.resumeHint) {
+        parts.push(`next:\n${instruction}\n${packet.resumeHint}`);
+    }
+    if (packet.obligations) {
+        // Just first line of obligations
+        const firstOb = packet.obligations.split("\n")[0];
+        parts.push(`owed:\n${instruction}\n${firstOb.replace(/^- /, "")}`);
+    }
+    if (packet.cares) {
+        const firstCare = packet.cares.split("\n")[0];
+        parts.push(`care: ${firstCare.replace(/^- /, "")}`);
+    }
+    const compact = parts.join(" | ");
+    // Hard cap at 200 tokens (800 chars)
+    const maxChars = 200 * 4;
+    const result = compact.length > maxChars ? compact.slice(0, maxChars) : compact;
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.start_of_turn_packet_compact_rendered",
+        message: `compact start-of-turn packet: ${estimateTokens(result)} tokens`,
+        meta: { tokens: estimateTokens(result) },
+    });
+    return result;
+}

package/dist/heart/steward-policy.js

@@ -0,0 +1,302 @@
+"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.readStewardPolicy = readStewardPolicy;
+exports.updateStewardPolicy = updateStewardPolicy;
+exports.readRoutineActionReceipts = readRoutineActionReceipts;
+exports.inspectRoutineActionGrant = inspectRoutineActionGrant;
+exports.consumeRoutineActionGrant = consumeRoutineActionGrant;
+exports.transitionRoutineActionReceipt = transitionRoutineActionReceipt;
+exports.recoverRoutineActionReceipts = recoverRoutineActionReceipts;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+const session_transaction_1 = require("../mind/session-transaction");
+const EMPTY_POLICY = { schemaVersion: 1, version: 0, desiredStates: {}, routineActionGrants: {}, updatedAt: null };
+function policyDir(agentRoot) {
+    return path.join(agentRoot, "state", "policy");
+}
+function policyPath(agentRoot) {
+    return path.join(policyDir(agentRoot), "steward.json");
+}
+function receiptsPath(agentRoot) {
+    return path.join(policyDir(agentRoot), "action-receipts.ndjson");
+}
+function auditPath(agentRoot) {
+    return path.join(policyDir(agentRoot), "policy-audit.ndjson");
+}
+function ensureDirectory(agentRoot) {
+    fs.mkdirSync(policyDir(agentRoot), { recursive: true, mode: 0o700 });
+    fs.chmodSync(policyDir(agentRoot), 0o700);
+}
+function appendReceipt(filePath, value) {
+    const creating = !fs.existsSync(filePath);
+    const fd = fs.openSync(filePath, "a", 0o600);
+    try {
+        fs.writeFileSync(fd, `${JSON.stringify(value)}\n`, "utf8");
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.chmodSync(filePath, 0o600);
+    if (creating) {
+        const directory = fs.openSync(path.dirname(filePath), fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+        try {
+            fs.fsyncSync(directory);
+        }
+        finally {
+            fs.closeSync(directory);
+        }
+    }
+}
+function requireText(value, label) {
+    const result = value.trim();
+    if (!result)
+        throw new Error(`${label} must be nonempty`);
+    return result;
+}
+function optionalExpiry(value, now) {
+    if (!value)
+        return undefined;
+    const epoch = Date.parse(value);
+    if (!Number.isFinite(epoch) || new Date(epoch).toISOString() !== value || epoch <= Date.parse(now))
+        throw new Error("policy expiry must be a future canonical timestamp");
+    return value;
+}
+function validateStewardPolicy(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("steward policy is invalid");
+    const candidate = value;
+    if (candidate.schemaVersion !== 1 || !Number.isInteger(candidate.version) || candidate.version < 0 || typeof candidate.desiredStates !== "object" || !candidate.desiredStates || typeof candidate.routineActionGrants !== "object" || !candidate.routineActionGrants) {
+        throw new Error("steward policy is invalid");
+    }
+    return candidate;
+}
+function readStewardPolicy(agentRoot) {
+    const filePath = policyPath(agentRoot);
+    if (!fs.existsSync(filePath))
+        return structuredClone(EMPTY_POLICY);
+    return validateStewardPolicy(JSON.parse(fs.readFileSync(filePath, "utf8")));
+}
+function updateStewardPolicy(agentRoot, input) {
+    if (input.actor.trustLevel !== "family")
+        throw new Error("steward policy mutation requires family authority");
+    const authorizingSessionEvent = requireText(input.actor.sessionEventId, "authorizing session event");
+    const issuer = requireText(input.actor.friendId, "issuer");
+    return (0, session_transaction_1.withImmediateSessionTurnLease)(policyPath(agentRoot), (lease) => {
+        const snapshot = (0, session_transaction_1.readSessionTransaction)(policyPath(agentRoot), lease);
+        const current = snapshot.value === null ? structuredClone(EMPTY_POLICY) : validateStewardPolicy(snapshot.value);
+        if (current.version !== input.expectedVersion)
+            throw new Error(`steward policy version changed: expected ${input.expectedVersion}, got ${current.version}`);
+        const now = input.now ?? new Date().toISOString();
+        const expiresAt = optionalExpiry(input.mutation.expiresAt, now);
+        const version = current.version + 1;
+        const next = { ...current, version, desiredStates: { ...current.desiredStates }, routineActionGrants: { ...current.routineActionGrants }, updatedAt: now };
+        if (input.mutation.kind === "set_desired_state") {
+            next.desiredStates[requireText(input.mutation.key, "desired state key")] = {
+                value: requireText(input.mutation.value, "desired state value"),
+                provenance: input.mutation.provenance,
+                version,
+                source: requireText(input.mutation.source, "desired state source"),
+                ...(expiresAt ? { expiresAt } : {}),
+            };
+        }
+        else {
+            if (input.mutation.provenance !== "stated" && input.mutation.provenance !== "installed_explicit_policy")
+                throw new Error("routine action grants require explicit authority");
+            if (!Number.isInteger(input.mutation.maxCount) || input.mutation.maxCount < 1 || !Number.isFinite(input.mutation.windowMs) || input.mutation.windowMs <= 0)
+                throw new Error("routine action grant bounds are invalid");
+            if (!input.mutation.verificationRequired)
+                throw new Error("routine action grants require post-action verification");
+            const targets = [...new Set(input.mutation.targets.map((value) => requireText(value, "routine action target")))];
+            if (targets.length === 0)
+                throw new Error("routine action grant requires a target");
+            next.routineActionGrants[requireText(input.mutation.key, "routine action key")] = {
+                action: requireText(input.mutation.action, "routine action"), targets, maxCount: input.mutation.maxCount, windowMs: input.mutation.windowMs,
+                verificationRequired: input.mutation.verificationRequired, exclusions: [...new Set(input.mutation.exclusions)], provenance: input.mutation.provenance,
+                issuer, authorizedAt: now, authorizingSessionEvent, version, ...(expiresAt ? { expiresAt } : {}),
+            };
+        }
+        ensureDirectory(agentRoot);
+        (0, session_transaction_1.writeSessionTransaction)(policyPath(agentRoot), next, { lease, expectedRevision: snapshot.revision });
+        appendReceipt(auditPath(agentRoot), { schemaVersion: 1, policyVersion: version, issuer, authorizingSessionEvent, mutationKind: input.mutation.kind, at: now });
+        (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.steward_policy_updated", message: "updated steward policy", meta: { version, mutationKind: input.mutation.kind, issuer } });
+        return next;
+    });
+}
+function readActionReceiptHistory(agentRoot) {
+    const filePath = receiptsPath(agentRoot);
+    if (!fs.existsSync(filePath))
+        return [];
+    return fs.readFileSync(filePath, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line));
+}
+function readRoutineActionReceipts(agentRoot) {
+    const latest = new Map();
+    for (const receipt of readActionReceiptHistory(agentRoot))
+        latest.set(receipt.id, receipt);
+    return [...latest.values()];
+}
+function expectedOff(policy, target, now) {
+    const desired = policy.desiredStates[`container:${target}`];
+    if (!desired || (desired.expiresAt && Date.parse(desired.expiresAt) <= Date.parse(now)))
+        return false;
+    return /^(?:off|disabled|paused|intentionally_off|intentionally_paused)$/u.test(desired.value.trim().toLowerCase());
+}
+const UNRESOLVED_ACTION_STATES = new Set(["reserved", "attempting", "effect_acknowledged", "recovery_pending", "indeterminate"]);
+function inspectRoutineActionGrantSnapshot(policy, receipts, input) {
+    if (input.expectedPolicyVersion !== undefined && policy.version !== input.expectedPolicyVersion)
+        return { allowed: false, reason: "routine action policy version changed" };
+    const grant = policy.routineActionGrants[input.key];
+    if (!grant)
+        return { allowed: false, reason: "routine action grant is missing" };
+    if (grant.action !== input.action)
+        return { allowed: false, reason: "routine action does not match the grant" };
+    if (!grant.targets.includes(input.target) || grant.exclusions.includes(input.target))
+        return { allowed: false, reason: "routine action target is not authorized" };
+    const now = input.now ?? new Date().toISOString();
+    if (grant.expiresAt && Date.parse(grant.expiresAt) <= Date.parse(now))
+        return { allowed: false, reason: "routine action grant expired" };
+    if (expectedOff(policy, input.target, now))
+        return { allowed: false, reason: "container is expected off" };
+    if (receipts.some((receipt) => receipt.action === input.action && receipt.target === input.target && UNRESOLVED_ACTION_STATES.has(receipt.state))) {
+        return { allowed: false, reason: "routine action has an unresolved receipt for this target" };
+    }
+    return { allowed: true, policyVersion: policy.version, grantVersion: grant.version, key: input.key, action: grant.action, target: input.target };
+}
+function inspectRoutineActionGrant(agentRoot, input) {
+    try {
+        const policy = readStewardPolicy(agentRoot);
+        return inspectRoutineActionGrantSnapshot(policy, readRoutineActionReceipts(agentRoot), input);
+    }
+    catch (error) {
+        return { allowed: false, reason: error instanceof Error ? error.message : "routine action policy is unavailable" };
+    }
+}
+function consumeRoutineActionGrant(agentRoot, input) {
+    return (0, session_transaction_1.withImmediateSessionTurnLease)(policyPath(agentRoot), (lease) => {
+        const snapshot = (0, session_transaction_1.readSessionTransaction)(policyPath(agentRoot), lease);
+        const policy = snapshot.value === null ? structuredClone(EMPTY_POLICY) : validateStewardPolicy(snapshot.value);
+        const grant = policy.routineActionGrants[input.key];
+        const now = input.now ?? new Date().toISOString();
+        const action = input.action ?? grant?.action ?? "";
+        const receipts = readRoutineActionReceipts(agentRoot);
+        const decision = inspectRoutineActionGrantSnapshot(policy, receipts, { key: input.key, action, target: input.target, expectedPolicyVersion: input.expectedPolicyVersion, now });
+        if (!decision.allowed)
+            throw new Error(decision.reason);
+        ensureDirectory(agentRoot);
+        const windowStart = Date.parse(now) - grant.windowMs;
+        const used = receipts.filter((receipt) => receipt.key === input.key && Date.parse(receipt.reservedAt) > windowStart).length;
+        if (used >= grant.maxCount)
+            throw new Error("routine action rate limit reached");
+        const id = `action-${(0, node_crypto_1.randomUUID)()}`;
+        const receipt = {
+            schemaVersion: 2,
+            id,
+            state: "reserved",
+            key: input.key,
+            action,
+            target: input.target,
+            policyVersion: policy.version,
+            grantVersion: grant.version,
+            reservedAt: now,
+            updatedAt: now,
+            authorizationReceiptId: input.authorizationReceiptId ?? `policy-${grant.issuer}-${grant.authorizingSessionEvent}`,
+            authorizationVersion: input.authorizationVersion ?? grant.version,
+            attemptId: input.attemptId ?? `attempt-${(0, node_crypto_1.randomUUID)()}`,
+            attempt: 1,
+            expectedBeforeState: input.expectedBeforeState ?? null,
+            resolvedTarget: input.resolvedTarget ?? { id: "unresolved", name: input.target },
+            effect: input.effect ?? { operation: action, targetId: input.resolvedTarget?.id ?? "unresolved" },
+            effectReceipt: null,
+            verifiedAfterState: null,
+            recoveryState: { state: "not_needed", compensation: "none" },
+        };
+        appendReceipt(receiptsPath(agentRoot), receipt);
+        (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.routine_action_reserved", message: "reserved routine action grant", meta: { key: input.key, target: input.target, policyVersion: policy.version } });
+        return receipt;
+    });
+}
+function transitionRoutineActionReceipt(agentRoot, input) {
+    return (0, session_transaction_1.withImmediateSessionTurnLease)(policyPath(agentRoot), () => {
+        const current = readRoutineActionReceipts(agentRoot).find((receipt) => receipt.id === input.id);
+        if (!current)
+            throw new Error("routine action receipt is missing");
+        if (current.state !== input.expectedState)
+            throw new Error(`routine action receipt state changed: expected ${input.expectedState}, got ${current.state}`);
+        const now = input.at ?? new Date().toISOString();
+        const recoveryState = input.recoveryState ?? current.recoveryState;
+        const next = {
+            ...current,
+            state: input.state,
+            updatedAt: now,
+            ...(input.effectReceipt !== undefined ? { effectReceipt: input.effectReceipt } : {}),
+            ...(input.verifiedAfterState !== undefined ? { verifiedAfterState: input.verifiedAfterState } : {}),
+            recoveryState,
+        };
+        appendReceipt(receiptsPath(agentRoot), next);
+        (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.routine_action_transitioned", message: "transitioned routine action receipt", meta: { id: next.id, state: next.state, target: next.target } });
+        return next;
+    });
+}
+async function recoverRoutineActionReceipts(agentRoot, options) {
+    const recovered = [];
+    for (const receipt of readRoutineActionReceipts(agentRoot)) {
+        if (receipt.state === "reserved") {
+            recovered.push(transitionRoutineActionReceipt(agentRoot, { id: receipt.id, expectedState: "reserved", state: "recovered_no_effect", recoveryState: { state: "completed", compensation: "none" } }));
+            continue;
+        }
+        if (receipt.state === "attempting") {
+            recovered.push(transitionRoutineActionReceipt(agentRoot, { id: receipt.id, expectedState: "attempting", state: "indeterminate", recoveryState: { state: "manual_inspection_required", compensation: "none" } }));
+            continue;
+        }
+        if (receipt.state !== "effect_acknowledged" && receipt.state !== "recovery_pending")
+            continue;
+        const pending = receipt.state === "effect_acknowledged"
+            ? transitionRoutineActionReceipt(agentRoot, { id: receipt.id, expectedState: "effect_acknowledged", state: "recovery_pending", recoveryState: { state: "pending", compensation: "none" } })
+            : receipt;
+        options.afterRecoveryClaim?.(pending);
+        const observed = await options.observeTarget(pending.resolvedTarget);
+        if (observed.id === pending.resolvedTarget.id && observed.name === pending.resolvedTarget.name && observed.state === "running") {
+            recovered.push(transitionRoutineActionReceipt(agentRoot, { id: pending.id, expectedState: "recovery_pending", state: "verified", verifiedAfterState: observed.state, recoveryState: { state: "completed", compensation: "none" } }));
+        }
+        else {
+            recovered.push(transitionRoutineActionReceipt(agentRoot, { id: pending.id, expectedState: "recovery_pending", state: "indeterminate", recoveryState: { state: "manual_inspection_required", compensation: "none" } }));
+        }
+    }
+    (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.routine_action_recovery", message: "reconciled interrupted routine action receipts", meta: { recoveredCount: recovered.length } });
+    return recovered;
+}