@ouro.bot/cli 0.1.0-alpha.815 → 0.1.0-alpha.817

package/dist/heart/steward-policy.js

@@ -38,14 +38,119 @@ exports.updateStewardPolicy = updateStewardPolicy;
 exports.readRoutineActionReceipts = readRoutineActionReceipts;
 exports.inspectRoutineActionGrant = inspectRoutineActionGrant;
 exports.consumeRoutineActionGrant = consumeRoutineActionGrant;
+exports.withStewardPolicyLease = withStewardPolicyLease;
+exports.withRoutineActionAttempt = withRoutineActionAttempt;
 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 node_util_1 = require("node:util");
 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 };
+const MAX_POLICY_BYTES = 1024 * 1024;
+const MAX_AUDIT_ROW_BYTES = 16 * MAX_POLICY_BYTES;
+function sha256(bytes) {
+    return (0, node_crypto_1.createHash)("sha256").update(bytes, "utf8").digest("hex");
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function exactKeys(value, required, optional = []) {
+    return required.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => required.includes(key) || optional.includes(key));
+}
+function text(value) {
+    return typeof value === "string" && value.length > 0 && value.trim() === value;
+}
+function canonicalTime(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(Date.parse(value)).toISOString() === value;
+}
+function positiveInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function textArray(value) {
+    return Array.isArray(value) && value.every(text) && new Set(value).size === value.length;
+}
+function ownerAuthorization(value) {
+    return record(value) && exactKeys(value, ["profileId", "profileVersion", "requestId", "sessionKey", "receiptId"])
+        && value.profileId === "sanctuary-owner" && positiveInteger(value.profileVersion)
+        && text(value.requestId) && text(value.sessionKey) && text(value.receiptId);
+}
+function desiredEntry(value, version) {
+    return record(value) && exactKeys(value, ["value", "provenance", "version", "source"], ["expiresAt"])
+        && text(value.value) && text(value.source) && positiveInteger(value.version) && value.version <= version
+        && (value.provenance === "stated" || value.provenance === "observed" || value.provenance === "default")
+        && (value.expiresAt === undefined || canonicalTime(value.expiresAt));
+}
+function grantEntry(value, version) {
+    return record(value) && exactKeys(value, ["action", "targets", "maxCount", "windowMs", "verificationRequired", "exclusions", "provenance", "issuer", "authorizedAt", "authorizingSessionEvent", "version"], ["expiresAt"])
+        && text(value.action) && textArray(value.targets) && value.targets.length > 0 && textArray(value.exclusions)
+        && positiveInteger(value.maxCount) && positiveInteger(value.windowMs) && value.verificationRequired === true
+        && (value.provenance === "stated" || value.provenance === "installed_explicit_policy")
+        && text(value.issuer) && text(value.authorizingSessionEvent) && canonicalTime(value.authorizedAt)
+        && positiveInteger(value.version) && value.version <= version && (value.expiresAt === undefined || canonicalTime(value.expiresAt));
+}
+function policyRecord(value) {
+    if (!record(value) || !exactKeys(value, ["schemaVersion", "version", "desiredStates", "routineActionGrants", "updatedAt"])
+        || value.schemaVersion !== 1 || typeof value.version !== "number" || !Number.isSafeInteger(value.version) || value.version < 0
+        || !record(value.desiredStates) || !record(value.routineActionGrants)
+        || !(value.updatedAt === null ? value.version === 0 : canonicalTime(value.updatedAt)))
+        return false;
+    const version = value.version;
+    return Object.entries(value.desiredStates).every(([key, entry]) => text(key) && desiredEntry(entry, version))
+        && Object.entries(value.routineActionGrants).every(([key, entry]) => text(key) && grantEntry(entry, version));
+}
+function policyImage(bytes) {
+    if (Buffer.byteLength(bytes) > MAX_POLICY_BYTES)
+        throw new Error("steward policy audit image exceeds its bound");
+    if (bytes === "")
+        return structuredClone(EMPTY_POLICY);
+    let value;
+    try {
+        value = JSON.parse(bytes);
+    }
+    catch (cause) {
+        throw new Error("steward policy audit image is invalid", { cause });
+    }
+    if (!policyRecord(value))
+        throw new Error("steward policy audit image is invalid");
+    return value;
+}
+function mutationFingerprint(kind, key, result) {
+    const generated = ["version", "issuer", "authorizedAt", "authorizingSessionEvent"];
+    const input = Object.fromEntries(Object.entries(result).filter(([field]) => !generated.includes(field)).sort(([left], [right]) => left.localeCompare(right)));
+    return sha256(JSON.stringify([kind, key, input]));
+}
+function operationIdentity(issuer, event, requestId, kind, key) {
+    return JSON.stringify([issuer, event, requestId, kind, key]);
+}
+function auditRow(value) {
+    if (!record(value) || !exactKeys(value, ["schemaVersion", "transactionId", "precedingBytesSha256", "mutationKind", "key", "mutationFingerprint", "affectedKeyResult", "affectedKeyResultSha256", "issuer", "authorizingSessionEvent", "authorization", "preimage", "preimageVersion", "preimageSha256", "postimage", "postimageVersion", "postimageSha256", "at"])
+        || value.schemaVersion !== 2 || (value.mutationKind !== "set_desired_state" && value.mutationKind !== "grant_routine_action")
+        || !text(value.key) || !text(value.issuer) || !text(value.authorizingSessionEvent) || !ownerAuthorization(value.authorization)
+        || typeof value.preimage !== "string" || typeof value.postimage !== "string" || !canonicalTime(value.at))
+        return false;
+    const before = policyImage(value.preimage);
+    const after = policyImage(value.postimage);
+    const result = value.mutationKind === "set_desired_state" ? after.desiredStates[value.key] : after.routineActionGrants[value.key];
+    if (!result || value.preimageVersion !== before.version || value.postimageVersion !== after.version
+        || after.version !== before.version + 1 || result.version !== after.version || after.updatedAt !== value.at
+        || value.preimageSha256 !== sha256(value.preimage) || value.postimageSha256 !== sha256(value.postimage)
+        || value.postimage !== JSON.stringify(after, null, 2) || !(0, node_util_1.isDeepStrictEqual)(value.affectedKeyResult, result)
+        || value.affectedKeyResultSha256 !== sha256(JSON.stringify(result))
+        || value.mutationFingerprint !== mutationFingerprint(value.mutationKind, value.key, result)
+        || value.transactionId !== sha256(JSON.stringify([operationIdentity(value.issuer, value.authorizingSessionEvent, value.authorization.requestId, value.mutationKind, value.key), value.mutationFingerprint])))
+        return false;
+    if ("action" in result && (result.issuer !== value.issuer || result.authorizingSessionEvent !== value.authorizingSessionEvent || result.authorizedAt !== value.at))
+        return false;
+    const expected = {
+        ...before, version: after.version, updatedAt: value.at,
+        desiredStates: value.mutationKind === "set_desired_state" ? { ...before.desiredStates, [value.key]: result } : before.desiredStates,
+        routineActionGrants: value.mutationKind === "grant_routine_action" ? { ...before.routineActionGrants, [value.key]: result } : before.routineActionGrants,
+    };
+    return (0, node_util_1.isDeepStrictEqual)(after, expected);
+}
 function policyDir(agentRoot) {
     return path.join(agentRoot, "state", "policy");
 }
@@ -62,6 +167,15 @@ function ensureDirectory(agentRoot) {
     fs.mkdirSync(policyDir(agentRoot), { recursive: true, mode: 0o700 });
     fs.chmodSync(policyDir(agentRoot), 0o700);
 }
+function syncParentDirectory(filePath) {
+    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 appendReceipt(filePath, value) {
     const creating = !fs.existsSync(filePath);
     const fd = fs.openSync(filePath, "a", 0o600);
@@ -73,18 +187,11 @@ function appendReceipt(filePath, value) {
         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);
-        }
-    }
+    if (creating)
+        syncParentDirectory(filePath);
 }
 function requireText(value, label) {
-    const result = value.trim();
+    const result = typeof value === "string" ? value.trim() : "";
     if (!result)
         throw new Error(`${label} must be nonempty`);
     return result;
@@ -93,67 +200,198 @@ 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))
+    if (!Number.isFinite(epoch) || new Date(epoch).toISOString() !== value || (now !== undefined && 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) {
+    if (!policyRecord(value))
         throw new Error("steward policy is invalid");
+    return value;
+}
+function readAuditBytes(agentRoot) {
+    try {
+        const bytes = fs.readFileSync(auditPath(agentRoot));
+        const decoded = bytes.toString("utf8");
+        if (!Buffer.from(decoded, "utf8").equals(bytes))
+            throw new Error("steward policy audit encoding is invalid");
+        return decoded;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return "";
+        throw error;
     }
-    return candidate;
 }
-function readStewardPolicy(agentRoot) {
+function readPolicyTransaction(filePath, lease) {
+    const exists = fs.existsSync(filePath);
+    if (exists && fs.statSync(filePath).size > MAX_POLICY_BYTES)
+        throw new Error("steward policy exceeds its bound");
+    const snapshot = (0, session_transaction_1.readSessionTransaction)(filePath, lease);
+    const raw = exists ? fs.readFileSync(filePath) : Buffer.alloc(0);
+    if (!Buffer.from(snapshot.bytes, "utf8").equals(raw))
+        throw new Error("steward policy encoding or bytes changed");
+    return { ...snapshot, exists };
+}
+function readAuditedPolicy(agentRoot, lease) {
     const filePath = policyPath(agentRoot);
-    if (!fs.existsSync(filePath))
-        return structuredClone(EMPTY_POLICY);
-    return validateStewardPolicy(JSON.parse(fs.readFileSync(filePath, "utf8")));
+    let snapshot = readPolicyTransaction(filePath, lease);
+    let policy = !snapshot.exists && snapshot.bytes === "" ? structuredClone(EMPTY_POLICY) : validateStewardPolicy(snapshot.value);
+    const auditBytes = readAuditBytes(agentRoot);
+    const rows = [];
+    const seen = new Set();
+    const preceding = (0, node_crypto_1.createHash)("sha256");
+    let legacyVersion = 0;
+    if (auditBytes && !auditBytes.endsWith("\n"))
+        throw new Error("steward policy audit has a partial final row");
+    for (const line of auditBytes ? auditBytes.slice(0, -1).split("\n") : []) {
+        if (Buffer.byteLength(line) > MAX_AUDIT_ROW_BYTES)
+            throw new Error("steward policy audit row exceeds its bound");
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch (cause) {
+            throw new Error("steward policy audit row is invalid", { cause });
+        }
+        if (record(row) && row.schemaVersion === 1) {
+            if (rows.length || !positiveInteger(row.policyVersion) || row.policyVersion <= legacyVersion)
+                throw new Error("steward policy audit legacy prefix is invalid");
+            legacyVersion = row.policyVersion;
+        }
+        else {
+            if (!auditRow(row) || row.precedingBytesSha256 !== preceding.copy().digest("hex"))
+                throw new Error("steward policy audit row is invalid");
+            const prior = rows.at(-1);
+            if (prior ? row.preimage !== prior.postimage || row.preimageVersion !== prior.postimageVersion : row.preimageVersion !== legacyVersion)
+                throw new Error("steward policy audit chain is invalid");
+            const identity = operationIdentity(row.issuer, row.authorizingSessionEvent, row.authorization.requestId, row.mutationKind, row.key);
+            if (seen.has(identity))
+                throw new Error("steward policy audit contains a duplicate transaction");
+            seen.add(identity);
+            rows.push(row);
+        }
+        preceding.update(`${line}\n`, "utf8");
+    }
+    const last = rows.at(-1);
+    if (!last) {
+        if (policy.version !== legacyVersion)
+            throw new Error("steward policy audit does not match the policy head");
+    }
+    else if (snapshot.bytes !== last.postimage) {
+        if (snapshot.bytes !== last.preimage)
+            throw new Error("steward policy audit does not match the policy head");
+        const fd = fs.openSync(auditPath(agentRoot), "r");
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        syncParentDirectory(auditPath(agentRoot));
+        (0, session_transaction_1.writeSessionTransaction)(filePath, policyImage(last.postimage), { lease, expectedRevision: snapshot.revision });
+        snapshot = readPolicyTransaction(filePath, lease);
+        if (snapshot.bytes !== last.postimage)
+            throw new Error("steward policy audit recovery readback differs");
+        policy = validateStewardPolicy(snapshot.value);
+        (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.steward_policy_recovered", message: "recovered an authorized steward policy write", meta: { version: policy.version } });
+    }
+    return { ...snapshot, policy, rows, auditBytes };
+}
+function readPolicyState(agentRoot) {
+    if (!fs.existsSync(policyPath(agentRoot)) && !fs.existsSync(auditPath(agentRoot))) {
+        return { policy: structuredClone(EMPTY_POLICY), rows: [] };
+    }
+    return (0, session_transaction_1.withImmediateSessionTurnLease)(policyPath(agentRoot), (lease) => readAuditedPolicy(agentRoot, lease));
+}
+function readStewardPolicy(agentRoot) {
+    return readPolicyState(agentRoot).policy;
 }
 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");
+    const authorization = input.actor.authorization;
+    if (!ownerAuthorization(authorization))
+        throw new Error("steward policy mutation requires current owner authorization");
+    if (input.mutation.kind !== "set_desired_state" && input.mutation.kind !== "grant_routine_action")
+        throw new Error("steward policy mutation kind is invalid");
     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 snapshot = readAuditedPolicy(agentRoot, lease);
+        const current = snapshot.policy;
         const now = input.now ?? new Date().toISOString();
-        const expiresAt = optionalExpiry(input.mutation.expiresAt, now);
+        if (!canonicalTime(now))
+            throw new Error("policy update time must be canonical");
+        const expiresAt = optionalExpiry(input.mutation.expiresAt);
         const version = current.version + 1;
+        if (!positiveInteger(version))
+            throw new Error("steward policy version is exhausted");
         const next = { ...current, version, desiredStates: { ...current.desiredStates }, routineActionGrants: { ...current.routineActionGrants }, updatedAt: now };
+        const key = requireText(input.mutation.key, input.mutation.kind === "set_desired_state" ? "desired state key" : "routine action key");
+        let affectedKeyResult;
         if (input.mutation.kind === "set_desired_state") {
-            next.desiredStates[requireText(input.mutation.key, "desired state key")] = {
+            if (input.mutation.provenance !== "stated" && input.mutation.provenance !== "observed" && input.mutation.provenance !== "default")
+                throw new Error("desired state provenance is invalid");
+            affectedKeyResult = {
                 value: requireText(input.mutation.value, "desired state value"),
                 provenance: input.mutation.provenance,
                 version,
                 source: requireText(input.mutation.source, "desired state source"),
                 ...(expiresAt ? { expiresAt } : {}),
             };
+            next.desiredStates = { ...current.desiredStates, [key]: affectedKeyResult };
         }
         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)
+            if (!positiveInteger(input.mutation.maxCount) || !positiveInteger(input.mutation.windowMs))
                 throw new Error("routine action grant bounds are invalid");
-            if (!input.mutation.verificationRequired)
+            if (input.mutation.verificationRequired !== true)
                 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 (!Array.isArray(input.mutation.targets) || !Array.isArray(input.mutation.exclusions))
+                throw new Error("routine action targets and exclusions must be arrays");
+            const targets = [...new Set(input.mutation.targets.map((value) => requireText(value, "routine action target")))].sort();
             if (targets.length === 0)
                 throw new Error("routine action grant requires a target");
-            next.routineActionGrants[requireText(input.mutation.key, "routine action key")] = {
+            affectedKeyResult = {
                 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,
+                verificationRequired: input.mutation.verificationRequired, exclusions: [...new Set(input.mutation.exclusions.map((value) => requireText(value, "routine action exclusion")))].sort(), provenance: input.mutation.provenance,
                 issuer, authorizedAt: now, authorizingSessionEvent, version, ...(expiresAt ? { expiresAt } : {}),
             };
+            next.routineActionGrants = { ...current.routineActionGrants, [key]: affectedKeyResult };
+        }
+        const fingerprint = mutationFingerprint(input.mutation.kind, key, affectedKeyResult);
+        const identity = operationIdentity(issuer, authorizingSessionEvent, authorization.requestId, input.mutation.kind, key);
+        const previousIndex = snapshot.rows.findIndex((row) => operationIdentity(row.issuer, row.authorizingSessionEvent, row.authorization.requestId, row.mutationKind, row.key) === identity);
+        if (previousIndex >= 0) {
+            const previous = snapshot.rows[previousIndex];
+            const currentResult = previous.mutationKind === "set_desired_state" ? current.desiredStates[key] : current.routineActionGrants[key];
+            if (previous.mutationFingerprint !== fingerprint || snapshot.rows.slice(previousIndex + 1).some((row) => row.mutationKind === previous.mutationKind && row.key === key)
+                || !(0, node_util_1.isDeepStrictEqual)(currentResult, previous.affectedKeyResult))
+                throw new Error("steward policy transaction replay changed");
+            return current;
         }
+        if (current.version !== input.expectedVersion)
+            throw new Error(`steward policy version changed: expected ${input.expectedVersion}, got ${current.version}`);
+        optionalExpiry(expiresAt, now);
+        const postimage = JSON.stringify(next, null, 2);
+        if (Buffer.byteLength(postimage) > MAX_POLICY_BYTES)
+            throw new Error("steward policy exceeds its bound");
+        const row = {
+            schemaVersion: 2, transactionId: sha256(JSON.stringify([identity, fingerprint])), precedingBytesSha256: sha256(snapshot.auditBytes),
+            mutationKind: input.mutation.kind, key, mutationFingerprint: fingerprint, affectedKeyResult, affectedKeyResultSha256: sha256(JSON.stringify(affectedKeyResult)),
+            issuer, authorizingSessionEvent, authorization: { ...authorization },
+            preimage: snapshot.bytes, preimageVersion: current.version, preimageSha256: snapshot.revision,
+            postimage, postimageVersion: version, postimageSha256: sha256(postimage), at: now,
+        };
+        if (Buffer.byteLength(JSON.stringify(row)) > MAX_AUDIT_ROW_BYTES)
+            throw new Error("steward policy audit row exceeds its bound");
         ensureDirectory(agentRoot);
+        appendReceipt(auditPath(agentRoot), row);
         (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 });
+        if (readPolicyTransaction(policyPath(agentRoot), lease).bytes !== postimage)
+            throw new Error("steward policy publication readback differs");
         (0, runtime_1.emitNervesEvent)({ component: "heart", event: "heart.steward_policy_updated", message: "updated steward policy", meta: { version, mutationKind: input.mutation.kind, issuer } });
         return next;
     });
@@ -170,58 +408,106 @@ function readRoutineActionReceipts(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)))
+function currentRequester(value, target) {
+    if (!record(value) || !text(value.friendId))
         return false;
-    return /^(?:off|disabled|paused|intentionally_off|intentionally_paused)$/u.test(desired.value.trim().toLowerCase());
+    if (value.kind === "owner" || value.kind === "household_request") {
+        return exactKeys(value, ["kind", "friendId", "profileId", "requestId", "sessionEventId", "origin"])
+            && value.profileId === (value.kind === "owner" ? "sanctuary-owner" : "sanctuary-household")
+            && text(value.requestId) && text(value.sessionEventId) && record(value.origin)
+            && exactKeys(value.origin, ["friendId", "channel", "key"])
+            && value.origin.friendId === value.friendId && value.origin.channel === "telegram" && text(value.origin.key);
+    }
+    return value.kind === "owner_event" && exactKeys(value, ["kind", "friendId", "profileId", "event", "target"])
+        && value.profileId === "sanctuary-event" && record(value.target) && exactKeys(value.target, ["id", "name"])
+        && text(value.target.id) && value.target.name === target && record(value.event)
+        && exactKeys(value.event, ["schemaVersion", "recordPath", "agent", "source", "eventId", "generation", "observationRevision", "claimOwner"])
+        && value.event.schemaVersion === 1 && value.event.source === "sanctuary-health"
+        && value.event.eventId === `container:${value.target.id}:availability`
+        && text(value.event.recordPath) && text(value.event.agent) && positiveInteger(value.event.generation)
+        && text(value.event.observationRevision) && text(value.event.claimOwner);
+}
+function appliedEntry(rows, kind, key, entry) {
+    return rows.some((row) => row.mutationKind === kind && row.key === key && row.postimageVersion === entry.version && (0, node_util_1.isDeepStrictEqual)(row.affectedKeyResult, entry));
 }
 const UNRESOLVED_ACTION_STATES = new Set(["reserved", "attempting", "effect_acknowledged", "recovery_pending", "indeterminate"]);
-function inspectRoutineActionGrantSnapshot(policy, receipts, input) {
+function inspectRoutineActionGrantSnapshot(policy, rows, receipts, input) {
+    const now = input.now === undefined ? new Date().toISOString() : input.now;
+    if (!canonicalTime(now))
+        return { allowed: false, reason: "routine action time must be canonical" };
+    if (!text(input.key) || !text(input.action) || !text(input.target))
+        return { allowed: false, reason: "routine action requires an exact key, action, and target" };
     if (input.expectedPolicyVersion !== undefined && policy.version !== input.expectedPolicyVersion)
         return { allowed: false, reason: "routine action policy version changed" };
+    if (!currentRequester(input.requester, input.target) || !positiveInteger(input.authorizationVersion))
+        return { allowed: false, reason: "routine action requires a current versioned requester" };
+    const desiredKey = `container:${input.target}`;
+    const desired = policy.desiredStates[desiredKey];
+    if (input.expectedDesiredStateVersion !== undefined && desired?.version !== input.expectedDesiredStateVersion)
+        return { allowed: false, reason: "routine action desired state version changed" };
+    const activeDesired = desired && (desired.expiresAt === undefined || Date.parse(desired.expiresAt) > Date.parse(now));
+    const desiredValue = desired?.value.toLowerCase();
+    if (activeDesired && /^(?:off|disabled|paused|intentionally_off|intentionally_paused)$/u.test(desiredValue))
+        return { allowed: false, reason: "container is expected off" };
     const grant = policy.routineActionGrants[input.key];
+    if (input.expectedGrantVersion !== undefined && grant?.version !== input.expectedGrantVersion)
+        return { allowed: false, reason: "routine action grant version changed" };
+    const fallback = input.requester.kind === "owner" ? { approvalFallback: true } : {};
     if (!grant)
-        return { allowed: false, reason: "routine action grant is missing" };
+        return { allowed: false, reason: "routine action grant is missing", ...fallback };
+    if (grant.provenance !== "stated")
+        return { allowed: false, reason: "routine action grant must be owner-stated" };
+    if (!appliedEntry(rows, "grant_routine_action", input.key, grant))
+        return { allowed: false, reason: "routine action grant has no applied owner authorization" };
     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" };
+        return { allowed: false, reason: "routine action grant expired", ...fallback };
+    if (!activeDesired || desired.provenance !== "stated" || !appliedEntry(rows, "set_desired_state", desiredKey, desired))
+        return { allowed: false, reason: "container has no active applied owner-stated desired state" };
+    if (!["on", "always_on", "expected_on"].includes(desiredValue) && !(desiredValue === "on_demand" && input.requester.kind !== "owner_event"))
+        return { allowed: false, reason: "container desired state does not authorize this request" };
     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 };
+    const windowStart = Date.parse(now) - grant.windowMs;
+    if (receipts.filter((receipt) => receipt.key === input.key && Date.parse(receipt.reservedAt) > windowStart).length >= grant.maxCount)
+        return { allowed: false, reason: "routine action rate limit reached" };
+    return { allowed: true, policyVersion: policy.version, desiredStateVersion: desired.version, grantVersion: grant.version, key: input.key, action: grant.action, target: input.target, requester: input.requester, authorizationVersion: input.authorizationVersion };
 }
 function inspectRoutineActionGrant(agentRoot, input) {
     try {
-        const policy = readStewardPolicy(agentRoot);
-        return inspectRoutineActionGrantSnapshot(policy, readRoutineActionReceipts(agentRoot), input);
+        const { policy, rows } = readPolicyState(agentRoot);
+        return inspectRoutineActionGrantSnapshot(policy, rows, readRoutineActionReceipts(agentRoot), input);
     }
     catch (error) {
         return { allowed: false, reason: error instanceof Error ? error.message : "routine action policy is unavailable" };
     }
 }
 function consumeRoutineActionGrant(agentRoot, input) {
+    if (!text(input.authorizationReceiptId))
+        throw new Error("routine action requires a current authorization receipt");
+    const authorizationReceiptId = input.authorizationReceiptId;
     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 snapshot = readAuditedPolicy(agentRoot, lease);
+        const policy = snapshot.policy;
         const grant = policy.routineActionGrants[input.key];
-        const now = input.now ?? new Date().toISOString();
-        const action = input.action ?? grant?.action ?? "";
+        const now = input.now === undefined ? new Date().toISOString() : input.now;
+        const action = input.action === undefined ? grant?.action ?? "" : input.action;
         const receipts = readRoutineActionReceipts(agentRoot);
-        const decision = inspectRoutineActionGrantSnapshot(policy, receipts, { key: input.key, action, target: input.target, expectedPolicyVersion: input.expectedPolicyVersion, now });
+        const decision = inspectRoutineActionGrantSnapshot(policy, snapshot.rows, receipts, { ...input, action, now });
         if (!decision.allowed)
             throw new Error(decision.reason);
+        const resolvedTarget = input.resolvedTarget === undefined
+            ? decision.requester.kind === "owner_event" ? decision.requester.target : { id: "unresolved", name: input.target }
+            : input.resolvedTarget;
+        if (!record(resolvedTarget) || !text(resolvedTarget.id) || resolvedTarget.name !== input.target)
+            throw new Error("routine action resolved target is invalid");
+        if (decision.requester.kind === "owner_event" && resolvedTarget.id !== decision.requester.target.id)
+            throw new Error("routine action event target binding changed");
         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,
@@ -232,15 +518,17 @@ function consumeRoutineActionGrant(agentRoot, input) {
             target: input.target,
             policyVersion: policy.version,
             grantVersion: grant.version,
+            desiredStateVersion: decision.desiredStateVersion,
+            requester: structuredClone(decision.requester),
             reservedAt: now,
             updatedAt: now,
-            authorizationReceiptId: input.authorizationReceiptId ?? `policy-${grant.issuer}-${grant.authorizingSessionEvent}`,
-            authorizationVersion: input.authorizationVersion ?? grant.version,
+            authorizationReceiptId,
+            authorizationVersion: decision.authorizationVersion,
             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" },
+            resolvedTarget: { id: resolvedTarget.id, name: resolvedTarget.name },
+            effect: input.effect ?? { operation: action, targetId: resolvedTarget.id },
             effectReceipt: null,
             verifiedAfterState: null,
             recoveryState: { state: "not_needed", compensation: "none" },
@@ -250,6 +538,34 @@ function consumeRoutineActionGrant(agentRoot, input) {
         return receipt;
     });
 }
+function withStewardPolicyLease(agentRoot, operation) {
+    return (0, session_transaction_1.withSessionTurnLease)(policyPath(agentRoot), operation);
+}
+async function withRoutineActionAttempt(agentRoot, reservation, validate, attempt) {
+    await withStewardPolicyLease(agentRoot, async (lease) => {
+        await validate();
+        const snapshot = readAuditedPolicy(agentRoot, lease);
+        const receipts = readRoutineActionReceipts(agentRoot);
+        const current = receipts.find((receipt) => receipt.id === reservation.id);
+        if (!current || current.state !== "reserved" || !(0, node_util_1.isDeepStrictEqual)(current, reservation))
+            throw new Error("routine action reservation changed");
+        if (!reservation.requester || reservation.desiredStateVersion === undefined)
+            throw new Error("routine action reservation has no current requester binding");
+        const now = new Date().toISOString();
+        const decision = inspectRoutineActionGrantSnapshot(snapshot.policy, snapshot.rows, receipts.filter((receipt) => receipt.id !== reservation.id), {
+            key: reservation.key, action: reservation.action, target: reservation.target, requester: reservation.requester,
+            authorizationVersion: reservation.authorizationVersion, expectedPolicyVersion: reservation.policyVersion,
+            expectedDesiredStateVersion: reservation.desiredStateVersion, expectedGrantVersion: reservation.grantVersion, now,
+        });
+        if (!decision.allowed)
+            throw new Error(decision.reason);
+        const reservedAt = Date.parse(reservation.reservedAt);
+        const windowStart = Date.parse(now) - snapshot.policy.routineActionGrants[reservation.key].windowMs;
+        if (!(reservedAt > windowStart && reservedAt <= Date.parse(now)))
+            throw new Error("routine action reservation is outside its rate window");
+        await attempt();
+    });
+}
 function transitionRoutineActionReceipt(agentRoot, input) {
     return (0, session_transaction_1.withImmediateSessionTurnLease)(policyPath(agentRoot), () => {
         const current = readRoutineActionReceipts(agentRoot).find((receipt) => receipt.id === input.id);

package/dist/heart/tool-approval.js

@@ -283,7 +283,14 @@ async function executeApprovalDecision(options) {
     if (decided.state !== "claimed")
         return decided;
     await options.hooks?.afterClaim?.();
-    if (options.currentSessionRevision !== decided.suspendedSessionRevision) {
+    let currentSessionRevision;
+    try {
+        currentSessionRevision = typeof options.currentSessionRevision === "function" ? options.currentSessionRevision() : options.currentSessionRevision;
+    }
+    catch {
+        return terminalizeClaimed(options.approvalStore, decided, "drifted", "current session revision is unavailable");
+    }
+    if (currentSessionRevision !== decided.suspendedSessionRevision) {
         return terminalizeClaimed(options.approvalStore, decided, "session_head_changed", "suspended session revision changed");
     }
     const checkpoint = options.checkpointStore.read(decided.approvalId);