@decidio/sdk 0.6.4 → 0.8.0

package/dist/resume.js

@@ -3,11 +3,11 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync
 import { join } from "node:path";
 import { userInfo } from "node:os";
 import { execFileSync } from "node:child_process";
-import { signConfirm, canonicalize as jcs, assertSafeTransport, carriesCredential } from "./signing.js";
+import { signConfirm, canonicalize as jcs, assertSafeTransport, carriesCredential, bindingMaterial, requestCommitment } from "./signing.js";
 import { canonicalize as toCanonical, DecidioUnsafeArgumentsError } from "./canonical.js";
 import { readConfirmResponse, buildConfirmBody, tierConfirms, tombstoneTier } from "./evidence.js";
 import { DecidioHttpError, decisionIdProblem } from "./errors.js";
-const argsBindingBytes = (p) => Buffer.from(jcs({ decisionId: p.decisionId, action: p.action, amount: p.amount, ...(p.scope !== undefined ? { scope: p.scope } : {}), args: p.args }), "utf8");
+const argsBindingBytes = (p) => Buffer.from(jcs({ decisionId: p.decisionId, action: p.action, amount: p.amount, ...(p.scope !== undefined ? { scope: p.scope } : {}), args: p.args, ...(p.requestCommitment !== undefined ? { requestCommitment: p.requestCommitment } : {}) }), "utf8");
 function signArgs(p, agentKey, webhookSecret) {
     const bytes = argsBindingBytes(p);
     if (agentKey) {
@@ -826,6 +826,62 @@ async function statusOf(cfg, decisionId) {
         throw new DecidioHttpError(r.status, `/agent/status/${decisionId}`);
     return r.json();
 }
+export async function checkApproval(cfg, decisionId, request, opts = {}) {
+    const st = opts.status ?? await statusOf(cfg, decisionId);
+    const state = typeof st?.state === "string" ? st.state : "";
+    const serverReason = typeof st?.reason === "string" && st.reason ? st.reason : undefined;
+    const no = (code, reason) => ({ ok: false, decisionId, state, code, ...(reason ? { reason } : {}) });
+    if (state === "rejected")
+        return no("rejected", serverReason);
+    if (state === "blocked")
+        return no("blocked", serverReason);
+    if (state === "pending")
+        return no("pending", `Decidio records decision ${decisionId} as pending - no human has approved it`);
+    if (state !== "approved" && state !== "auto_approved")
+        return no("unrecognized_state", `Decidio answered state ${JSON.stringify(st?.state ?? null)} for decision ${decisionId}, which is not an approval this SDK recognises (an answer it does not understand is never permission)`);
+    if (st?.spent === true)
+        return no("spent", `decision ${decisionId} was approved once and that approval is already spent (an execution is recorded on it) - ask again for a fresh approval; nothing was executed`);
+    if (typeof st?.grantExpiresAt === "string") {
+        const until = Date.parse(st.grantExpiresAt);
+        if (!Number.isFinite(until))
+            return no("unverifiable", `Decidio answered a malformed grant expiry for decision ${decisionId} (${JSON.stringify(st.grantExpiresAt)}), so the approval cannot be known to be in force`);
+        if (until <= Date.now())
+            return no("expired", `decision ${decisionId}'s approval expired at ${st.grantExpiresAt} before anything ran - ask again for a fresh approval; nothing was executed`);
+    }
+    else if (typeof st?.spent === "boolean" && st?.grantExpiresAt === null) {
+        return no("expired", `decision ${decisionId} is approved but Decidio names no expiry for its grant (its age is unknown) - ask again for a fresh approval; nothing was executed`);
+    }
+    const server = st?.requestCommitment;
+    if (server !== undefined && server !== null) {
+        if (typeof server !== "string" || !/^[0-9a-f]{64}$/.test(server))
+            return no("unverifiable", `Decidio answered a malformed request commitment for decision ${decisionId}, so the approval cannot be tied to this request`);
+        let material;
+        try {
+            material = bindingMaterial(cfg);
+        }
+        catch (e) {
+            return no("unverifiable", String(e?.message ?? e));
+        }
+        if (!material)
+            return no("unverifiable", `Decidio bound decision ${decisionId} to a request commitment, but this process has no key material to recompute it (DECIDIO_AGENT_KEY + DECIDIO_AGENT_DID, or DECIDIO_API_TOKEN) - restore the agent's environment`);
+        let fresh;
+        try {
+            fresh = requestCommitment(material, request);
+        }
+        catch (e) {
+            return no("unverifiable", `the request about to run could not be canonicalized for the commitment check (${e?.message ?? e})`);
+        }
+        const a = Buffer.from(fresh), b = Buffer.from(server);
+        if (a.length !== b.length || !timingSafeEqual(a, b)) {
+            return no("request_changed", `the request changed after approval: decision ${decisionId} was approved for a different request than the one about to run (or this agent's key material changed since it asked)`);
+        }
+        return { ok: true, decisionId, state };
+    }
+    if (opts.sent ?? !!((cfg.agentKey && cfg.agentDid) || cfg.apiToken)) {
+        return no("commitment_missing", `Decidio answered for decision ${decisionId} without the request commitment this SDK sent, so it cannot confirm the approval covers THIS request - the gate predates request binding (upgrade the Decidio gate; nothing was executed)`);
+    }
+    return { ok: true, decisionId, state };
+}
 const V2_STORE_METHODS = [
     "put", "get", "delete", "list",
     "claim", "markInvoking", "recordExecuted", "markIndeterminate", "markReported",
@@ -842,6 +898,8 @@ function assertStoreV2(store) {
         `  Fix: implement the missing methods (see the PendingStore docs), or use the shipped FilePendingStore / MemoryPendingStore. Nothing was started.`);
 }
 let reportDirWarned = false;
+export const WEBHOOK_SECRET_REMEDY = "Set webhookSecret (DECIDIO_WEBHOOK_SECRET) to the dedicated secret your Decidio deployment signs resume webhooks with - never the server's API_AUTH_TOKEN (its admin bearer, which must not be copied onto an agent host) - or use the poll worker (guard.worker()), which needs no inbound secret.";
+const NO_WEBHOOK_SECRET = `resume webhook refused: no webhookSecret is configured (and allowUnsigned is off). Since 0.7.0 the API token is no longer accepted as the webhook key. ${WEBHOOK_SECRET_REMEDY}`;
 function webhookBody(o) {
     return {
         ok: true,
@@ -863,7 +921,15 @@ function webhookBody(o) {
 export function createDecidioResume(opts) {
     assertStoreV2(opts.store);
     const registry = new Map();
-    const secret = opts.webhookSecret ?? opts.apiToken ?? "";
+    const secret = opts.webhookSecret ?? "";
+    const integrityKey = () => ctrl.webhookSecret ?? ctrl.apiToken ?? "";
+    let unsignedHandlerWarned = false;
+    const warnIfNoWebhookKey = () => {
+        if (secret || opts.allowUnsigned || unsignedHandlerWarned)
+            return;
+        unsignedHandlerWarned = true;
+        console.warn(`[decidio] this resume webhook handler has no webhookSecret, so it will REFUSE every webhook (401).${opts.apiToken ? " Since 0.7.0 the API token is no longer accepted as the webhook key — a leaked agent token must not be able to sign an approval signal." : ""} ${WEBHOOK_SECRET_REMEDY}`);
+    };
     if (opts.reportDir && !reportDirWarned) {
         reportDirWarned = true;
         console.warn(`[decidio] reportDir is ignored since 0.2.0 — execution evidence now lives in the PendingStore's own execution ledger, beside the state that makes a decision non-replayable. Reports written by 0.1.x under <pendingDir>/reports are migrated into that ledger on first use of a FilePendingStore, so nothing is lost; remove the option when convenient.`);
@@ -888,7 +954,7 @@ export function createDecidioResume(opts) {
         let journalled = false;
         if (haveReported) {
             try {
-                await ctrl.store.recordExecuted(decisionId, attemptId, reported, signEvidence(decisionId, attemptId, reported, ctrl.agentKey, ctrl.webhookSecret), buildProblem);
+                await ctrl.store.recordExecuted(decisionId, attemptId, reported, signEvidence(decisionId, attemptId, reported, ctrl.agentKey, integrityKey()), buildProblem);
                 journalled = true;
             }
             catch (e) {
@@ -969,13 +1035,146 @@ export function createDecidioResume(opts) {
         refusalWarned.add(decisionId);
         console.error(msg + (tail ?? " (This prints once per worker process — the entry stays parked until you act.)"));
     };
+    async function resolveCore({ decisionId, verdict, reason }, prefetched) {
+        const finish = (o) => { if (o.status !== "unknown")
+            opts.onResolved?.(o); return o; };
+        const idProblem = decisionIdProblem(decisionId);
+        if (idProblem)
+            return { status: "unknown", decisionId: String(decisionId ?? ""), reason: `not a decision id this SDK will act on (${idProblem})` };
+        const pending = await ctrl.store.get(decisionId);
+        if (!pending) {
+            const mapped = outcomeFromHead(await ctrl.store.getExecution(decisionId), decisionId);
+            if (mapped)
+                return finish(mapped);
+            return { status: "unknown", decisionId };
+        }
+        if (verdict === "rejected" || verdict === "blocked") {
+            await ctrl.store.markDiscarded(decisionId, verdict, reason);
+            await ctrl.store.delete(decisionId);
+            return finish({ status: verdict, decisionId, action: pending.action, reason });
+        }
+        if (verdict !== "approved" && verdict !== "auto_approved")
+            return { status: "unknown", decisionId };
+        if (pending.decisionId !== decisionId) {
+            refuseOnce(decisionId, `[decidio] REFUSING to execute ${decisionId}: the parked entry in this slot belongs to a DIFFERENT decision (${pending.decisionId}) — the pending file was moved or swapped. Delete it and re-run the action.`);
+            return finish({ status: "no_handler", decisionId, action: pending.action, reason: "parked payload decision-id mismatch" });
+        }
+        const strictBinding = !!ctrl.agentKey;
+        const integrity = verifyArgs(pending, ctrl.agentKey, integrityKey());
+        if (integrity === "mismatch") {
+            refuseOnce(decisionId, `[decidio] REFUSING to execute ${decisionId}: the parked payload FAILED its integrity check — the arguments on disk are not the arguments that were routed for approval. The pending file is untouched for inspection; delete it and re-run the action to request a fresh approval.`);
+            return finish({ status: "no_handler", decisionId, action: pending.action, reason: "parked payload integrity check failed" });
+        }
+        if (integrity === "unverifiable") {
+            refuseOnce(decisionId, `[decidio] REFUSING to execute ${decisionId}: the parked payload is signed but this process lacks the key material to verify it (DECIDIO_AGENT_KEY / DECIDIO_WEBHOOK_SECRET). Restore the agent's env and retry.`);
+            return finish({ status: "no_handler", decisionId, action: pending.action, reason: "parked payload unverifiable" });
+        }
+        if (integrity === "unbound" && strictBinding) {
+            refuseOnce(decisionId, `[decidio] REFUSING to execute ${decisionId}: the parked payload has NO integrity signature, but this agent has keys and would have signed it — a missing signature means the file was tampered with. Delete it and re-run the action.`);
+            return finish({ status: "no_handler", decisionId, action: pending.action, reason: "parked payload unsigned (expected a signature)" });
+        }
+        if (integrity === "unbound")
+            console.warn(`[decidio] executing ${decisionId} from an UNBOUND parked entry (this agent has no key material to bind or verify payloads) — its arguments cannot be integrity-checked. Run \`npx @decidio/sdk init\` to enable binding.`);
+        const fn = registry.get(pending.action)?.fn;
+        if (!fn) {
+            console.error(`[decidio] cannot resume ${decisionId}: no function is registered for action "${pending.action}" in THIS process.`);
+            console.error(`  A worker only re-executes actions registered where it runs. At startup, either declare the action on the wrapper:`);
+            console.error(`      const doIt = guard.protect(doItRaw, describe, { action: "${pending.action}" });`);
+            console.error(`  or register the raw function directly:`);
+            console.error(`      guard.register("${pending.action}", doItRaw);`);
+            console.error(`  then start the worker. The approved action stays parked until then — nothing is lost.`);
+            return finish({ status: "no_handler", decisionId, action: pending.action, reason: `no fn registered for action "${pending.action}" in this process — declare { action } on protect(), or call guard.register("${pending.action}", fn) at startup` });
+        }
+        const attemptId = randomUUID();
+        const claim = await ctrl.store.claim(decisionId, attemptId);
+        if (!claim.ok) {
+            if (claim.state && NON_REPLAYABLE.includes(claim.state)) {
+                refuseOnce(decisionId, claim.state === "discarded"
+                    ? `[decidio] REFUSING to execute ${decisionId}: it was DENIED (${(await ctrl.store.getExecution(decisionId))?.verdict ?? "rejected"}) and that answer is final. Nothing ran. A denial cannot be reconciled or retried — if this action should now proceed, it needs a NEW request and a new approval.`
+                    : `[decidio] REFUSING to execute ${decisionId}: its durable state is ${claim.state} — invocation already began, so re-running it could duplicate a committed effect. Inspect it with guard.resume.recover(); settle it with guard.resume.reconcile("${decisionId}", …).`, claim.state === "discarded" ? " (This prints once per worker process. The decision is closed — no action is needed.)" : undefined);
+                if (claim.state === "invoking" || claim.state === "indeterminate") {
+                    return finish({ status: "indeterminate", decisionId, action: pending.action, reason: claim.state === "invoking"
+                            ? `this decision is in durable state invoking: its action may still be running, may have crashed before any effect, or may have finished without reporting - it may or may not have run. Nothing will retry it; check the worker and the downstream system, then settle it with reconcile("${decisionId}", …).`
+                            : claim.reason });
+                }
+                return finish({ status: "already_resolved", decisionId, action: pending.action, reason: claim.state === "discarded" ? `this decision was already DENIED (${(await ctrl.store.getExecution(decisionId))?.verdict ?? "rejected"}); that answer is final and this signal lost the race to it` : `this decision already ran (durable state ${claim.state}); this signal lost the race to it` });
+            }
+            const mapped = outcomeFromHead(await ctrl.store.getExecution(decisionId), decisionId, pending.action);
+            if (mapped)
+                return finish(mapped);
+            return finish({ status: "lost_race", decisionId, action: pending.action, reason: `another attempt holds the pre-invocation claim on this decision${claim.state ? ` (durable state ${claim.state})` : ""}; this signal lost the race and did nothing. If that attempt is alive it will report; if it died, recover() lists the decision and reconcile() can settle it` });
+        }
+        let check;
+        try {
+            check = await checkApproval(ctrl, decisionId, { action: pending.action, amount: pending.amount, ...(pending.scope !== undefined ? { scope: pending.scope } : {}), args: pending.args }, { sent: !!pending.requestCommitment, ...(prefetched ? { status: prefetched } : {}) });
+        }
+        catch (e) {
+            await ctrl.store.releasePreinvoke(decisionId, attemptId).catch(() => { });
+            throw e;
+        }
+        if (!check.ok) {
+            if (check.code === "rejected" || check.code === "blocked") {
+                await ctrl.store.markDiscarded(decisionId, check.code, check.reason);
+                await ctrl.store.delete(decisionId);
+                return finish({ status: check.code, decisionId, action: pending.action, ...(check.reason ? { reason: check.reason } : {}) });
+            }
+            await ctrl.store.releasePreinvoke(decisionId, attemptId).catch(() => { });
+            if (check.code === "pending" || check.code === "unrecognized_state") {
+                return { status: "not_approved", decisionId, action: pending.action, reason: `${check.reason}. This signal was a wake-up, not an approval: nothing ran, and the entry stays parked for the real answer.` };
+            }
+            refuseOnce(decisionId, `[decidio] REFUSING to execute ${decisionId}: ${check.reason}. Nothing ran; the parked entry is untouched for inspection. If the request really changed, reject this decision and re-run the action to request a fresh approval.`);
+            return finish({ status: "request_unverified", decisionId, action: pending.action, reason: check.reason });
+        }
+        try {
+            await ctrl.store.markInvoking(decisionId, attemptId);
+        }
+        catch (e) {
+            await ctrl.store.releasePreinvoke(decisionId, attemptId).catch(() => { });
+            console.error(`[decidio] ${decisionId}: could not record the invocation boundary (${e?.message ?? e}) — refusing to run the action rather than run it unrecorded.`);
+            const mapped = outcomeFromHead(await ctrl.store.getExecution(decisionId), decisionId, pending.action);
+            if (mapped)
+                return finish(mapped);
+            return finish({ status: "lost_race", decisionId, action: pending.action, reason: `could not durably record the invocation boundary (${e?.message ?? e}); nothing ran, the entry stays parked, and a later signal may retry` });
+        }
+        let result;
+        try {
+            const entry = registry.get(pending.action);
+            result = entry?.withContext
+                ? await fn({ decisionId, attemptId, idempotencyKey: decisionId }, ...pending.args)
+                : await fn(...pending.args);
+        }
+        catch (e) {
+            const why = String(e?.message ?? e);
+            await ctrl.store.markIndeterminate(decisionId, attemptId, why).catch((se) => console.error(`[decidio] ${decisionId}: could not record INDETERMINATE (${se?.message ?? se}) — treat this decision as possibly executed.`));
+            console.error(`[decidio] ${decisionId}: "${pending.action}" was INVOKED and then threw (${why}). Whether the downstream effect committed is not knowable from here, so it will NOT be retried automatically. Check the downstream system, then: guard.resume.reconcile("${decisionId}", { outcome: "committed", evidence: … }) or { outcome: "not_committed", reason: … }.`);
+            return finish({ status: "indeterminate", decisionId, action: pending.action, reason: why });
+        }
+        return finish(await reportAfterExecution(pending, decisionId, result, attemptId));
+    }
+    async function wake(decisionId) {
+        const idProblem = decisionIdProblem(decisionId);
+        if (idProblem)
+            return { status: "unknown", decisionId: String(decisionId ?? ""), reason: `not a decision id this SDK will act on (${idProblem})` };
+        const id = decisionId;
+        const pending = await ctrl.store.get(id);
+        if (!pending)
+            return resolveCore({ decisionId: id, verdict: "approved" });
+        const st = await statusOf(ctrl, id);
+        const state = typeof st?.state === "string" ? st.state : "";
+        const reason = typeof st?.reason === "string" && st.reason ? st.reason : undefined;
+        if (state === "approved" || state === "auto_approved")
+            return resolveCore({ decisionId: id, verdict: "approved" }, st);
+        if (state === "rejected" || state === "blocked")
+            return resolveCore({ decisionId: id, verdict: state, ...(reason ? { reason } : {}) });
+        return { status: "not_approved", decisionId: id, action: pending.action, reason: `Decidio records decision ${id} as ${JSON.stringify(state || null)}; a webhook is a wake-up, not an approval, so nothing ran and the entry stays parked` };
+    }
     const ctrl = {
         ...opts,
         agentId: opts.agentId ?? process.env.DECIDIO_AGENT_ID,
         agentKey: opts.agentKey ?? process.env.DECIDIO_AGENT_KEY,
         agentDid: opts.agentDid ?? process.env.DECIDIO_AGENT_DID,
         workspaceId: opts.workspaceId ?? process.env.DECIDIO_WORKSPACE_ID,
-        webhookSecret: secret,
+        webhookSecret: opts.webhookSecret,
         store: opts.store,
         register(action, fn, evidence, withContext) {
             const prev = registry.get(action);
@@ -995,107 +1194,14 @@ export function createDecidioResume(opts) {
             catch (e) {
                 throw new DecidioUnsafeArgumentsError(`${e?.message ?? e} NOT parked and NOT executable — but decision ${p.decisionId} may already be routed; reject it in your queue: npx @decidio/sdk approvals reject ${p.decisionId}`, p.decisionId);
             }
-            const argsSig = signArgs(p, ctrl.agentKey, ctrl.webhookSecret);
+            const argsSig = signArgs(p, ctrl.agentKey, integrityKey());
             if (!argsSig)
                 console.warn(`[decidio] parking ${p.decisionId} UNBOUND — no agent key or webhook secret to sign the payload with, so a modified pending file could not be detected. Run \`npx @decidio/sdk init\` to configure keys.`);
             await ctrl.store.put({ ...p, createdAt: new Date().toISOString(), ...(argsSig ? { argsSig } : {}) });
         },
-        async resolve({ decisionId, verdict, reason }) {
-            const finish = (o) => { if (o.status !== "unknown")
-                opts.onResolved?.(o); return o; };
-            const idProblem = decisionIdProblem(decisionId);
-            if (idProblem)
-                return { status: "unknown", decisionId: String(decisionId ?? ""), reason: `not a decision id this SDK will act on (${idProblem})` };
-            const pending = await ctrl.store.get(decisionId);
-            if (!pending) {
-                const mapped = outcomeFromHead(await ctrl.store.getExecution(decisionId), decisionId);
-                if (mapped)
-                    return finish(mapped);
-                return { status: "unknown", decisionId };
-            }
-            if (verdict === "rejected" || verdict === "blocked") {
-                await ctrl.store.markDiscarded(decisionId, verdict, reason);
-                await ctrl.store.delete(decisionId);
-                return finish({ status: verdict, decisionId, action: pending.action, reason });
-            }
-            if (verdict !== "approved" && verdict !== "auto_approved")
-                return { status: "unknown", decisionId };
-            if (pending.decisionId !== decisionId) {
-                refuseOnce(decisionId, `[decidio] REFUSING to execute ${decisionId}: the parked entry in this slot belongs to a DIFFERENT decision (${pending.decisionId}) — the pending file was moved or swapped. Delete it and re-run the action.`);
-                return finish({ status: "no_handler", decisionId, action: pending.action, reason: "parked payload decision-id mismatch" });
-            }
-            const strictBinding = !!ctrl.agentKey;
-            const integrity = verifyArgs(pending, ctrl.agentKey, ctrl.webhookSecret);
-            if (integrity === "mismatch") {
-                refuseOnce(decisionId, `[decidio] REFUSING to execute ${decisionId}: the parked payload FAILED its integrity check — the arguments on disk are not the arguments that were routed for approval. The pending file is untouched for inspection; delete it and re-run the action to request a fresh approval.`);
-                return finish({ status: "no_handler", decisionId, action: pending.action, reason: "parked payload integrity check failed" });
-            }
-            if (integrity === "unverifiable") {
-                refuseOnce(decisionId, `[decidio] REFUSING to execute ${decisionId}: the parked payload is signed but this process lacks the key material to verify it (DECIDIO_AGENT_KEY / DECIDIO_WEBHOOK_SECRET). Restore the agent's env and retry.`);
-                return finish({ status: "no_handler", decisionId, action: pending.action, reason: "parked payload unverifiable" });
-            }
-            if (integrity === "unbound" && strictBinding) {
-                refuseOnce(decisionId, `[decidio] REFUSING to execute ${decisionId}: the parked payload has NO integrity signature, but this agent has keys and would have signed it — a missing signature means the file was tampered with. Delete it and re-run the action.`);
-                return finish({ status: "no_handler", decisionId, action: pending.action, reason: "parked payload unsigned (expected a signature)" });
-            }
-            if (integrity === "unbound")
-                console.warn(`[decidio] executing ${decisionId} from an UNBOUND parked entry (this agent has no key material to bind or verify payloads) — its arguments cannot be integrity-checked. Run \`npx @decidio/sdk init\` to enable binding.`);
-            const fn = registry.get(pending.action)?.fn;
-            if (!fn) {
-                console.error(`[decidio] cannot resume ${decisionId}: no function is registered for action "${pending.action}" in THIS process.`);
-                console.error(`  A worker only re-executes actions registered where it runs. At startup, either declare the action on the wrapper:`);
-                console.error(`      const doIt = guard.protect(doItRaw, describe, { action: "${pending.action}" });`);
-                console.error(`  or register the raw function directly:`);
-                console.error(`      guard.register("${pending.action}", doItRaw);`);
-                console.error(`  then start the worker. The approved action stays parked until then — nothing is lost.`);
-                return finish({ status: "no_handler", decisionId, action: pending.action, reason: `no fn registered for action "${pending.action}" in this process — declare { action } on protect(), or call guard.register("${pending.action}", fn) at startup` });
-            }
-            const attemptId = randomUUID();
-            const claim = await ctrl.store.claim(decisionId, attemptId);
-            if (!claim.ok) {
-                if (claim.state && NON_REPLAYABLE.includes(claim.state)) {
-                    refuseOnce(decisionId, claim.state === "discarded"
-                        ? `[decidio] REFUSING to execute ${decisionId}: it was DENIED (${(await ctrl.store.getExecution(decisionId))?.verdict ?? "rejected"}) and that answer is final. Nothing ran. A denial cannot be reconciled or retried — if this action should now proceed, it needs a NEW request and a new approval.`
-                        : `[decidio] REFUSING to execute ${decisionId}: its durable state is ${claim.state} — invocation already began, so re-running it could duplicate a committed effect. Inspect it with guard.resume.recover(); settle it with guard.resume.reconcile("${decisionId}", …).`, claim.state === "discarded" ? " (This prints once per worker process. The decision is closed — no action is needed.)" : undefined);
-                    if (claim.state === "invoking" || claim.state === "indeterminate") {
-                        return finish({ status: "indeterminate", decisionId, action: pending.action, reason: claim.state === "invoking"
-                                ? `this decision is in durable state invoking: its action may still be running, may have crashed before any effect, or may have finished without reporting - it may or may not have run. Nothing will retry it; check the worker and the downstream system, then settle it with reconcile("${decisionId}", …).`
-                                : claim.reason });
-                    }
-                    return finish({ status: "already_resolved", decisionId, action: pending.action, reason: claim.state === "discarded" ? `this decision was already DENIED (${(await ctrl.store.getExecution(decisionId))?.verdict ?? "rejected"}); that answer is final and this signal lost the race to it` : `this decision already ran (durable state ${claim.state}); this signal lost the race to it` });
-                }
-                const mapped = outcomeFromHead(await ctrl.store.getExecution(decisionId), decisionId, pending.action);
-                if (mapped)
-                    return finish(mapped);
-                return finish({ status: "lost_race", decisionId, action: pending.action, reason: `another attempt holds the pre-invocation claim on this decision${claim.state ? ` (durable state ${claim.state})` : ""}; this signal lost the race and did nothing. If that attempt is alive it will report; if it died, recover() lists the decision and reconcile() can settle it` });
-            }
-            try {
-                await ctrl.store.markInvoking(decisionId, attemptId);
-            }
-            catch (e) {
-                await ctrl.store.releasePreinvoke(decisionId, attemptId).catch(() => { });
-                console.error(`[decidio] ${decisionId}: could not record the invocation boundary (${e?.message ?? e}) — refusing to run the action rather than run it unrecorded.`);
-                const mapped = outcomeFromHead(await ctrl.store.getExecution(decisionId), decisionId, pending.action);
-                if (mapped)
-                    return finish(mapped);
-                return finish({ status: "lost_race", decisionId, action: pending.action, reason: `could not durably record the invocation boundary (${e?.message ?? e}); nothing ran, the entry stays parked, and a later signal may retry` });
-            }
-            let result;
-            try {
-                const entry = registry.get(pending.action);
-                result = entry?.withContext
-                    ? await fn({ decisionId, attemptId, idempotencyKey: decisionId }, ...pending.args)
-                    : await fn(...pending.args);
-            }
-            catch (e) {
-                const why = String(e?.message ?? e);
-                await ctrl.store.markIndeterminate(decisionId, attemptId, why).catch((se) => console.error(`[decidio] ${decisionId}: could not record INDETERMINATE (${se?.message ?? se}) — treat this decision as possibly executed.`));
-                console.error(`[decidio] ${decisionId}: "${pending.action}" was INVOKED and then threw (${why}). Whether the downstream effect committed is not knowable from here, so it will NOT be retried automatically. Check the downstream system, then: guard.resume.reconcile("${decisionId}", { outcome: "committed", evidence: … }) or { outcome: "not_committed", reason: … }.`);
-                return finish({ status: "indeterminate", decisionId, action: pending.action, reason: why });
-            }
-            return finish(await reportAfterExecution(pending, decisionId, result, attemptId));
-        },
+        async resolve(input) { return resolveCore(input); },
         webhookHandler() {
+            warnIfNoWebhookKey();
             return (req, res) => {
                 if (req.method !== "POST") {
                     res.statusCode = 405;
@@ -1108,7 +1214,7 @@ export function createDecidioResume(opts) {
                         if (!secret) {
                             if (!opts.allowUnsigned) {
                                 res.statusCode = 401;
-                                return res.end(JSON.stringify({ error: "resume webhook unsigned and no secret configured (set webhookSecret or allowUnsigned)" }));
+                                return res.end(JSON.stringify({ error: NO_WEBHOOK_SECRET }));
                             }
                         }
                         else if (!verifyResumeSignature(secret, raw, req.headers["x-decidio-signature"])) {
@@ -1116,8 +1222,7 @@ export function createDecidioResume(opts) {
                             return res.end(JSON.stringify({ error: "bad signature" }));
                         }
                         const body = JSON.parse(raw || "{}");
-                        const verdict = body.verdict;
-                        const outcome = await ctrl.resolve({ decisionId: body.decisionId, verdict, reason: body.reason });
+                        const outcome = await wake(body.decisionId);
                         res.statusCode = 200;
                         res.setHeader("content-type", "application/json");
                         res.end(JSON.stringify(webhookBody(outcome)));
@@ -1130,20 +1235,21 @@ export function createDecidioResume(opts) {
             };
         },
         fetchHandler() {
+            warnIfNoWebhookKey();
             return async (req) => {
                 if (req.method !== "POST")
                     return new Response("method not allowed", { status: 405 });
                 const raw = await req.text();
                 if (!secret) {
                     if (!opts.allowUnsigned)
-                        return new Response(JSON.stringify({ error: "resume webhook unsigned and no secret configured (set webhookSecret or allowUnsigned)" }), { status: 401 });
+                        return new Response(JSON.stringify({ error: NO_WEBHOOK_SECRET }), { status: 401 });
                 }
                 else if (!verifyResumeSignature(secret, raw, req.headers.get("x-decidio-signature") ?? undefined)) {
                     return new Response(JSON.stringify({ error: "bad signature" }), { status: 401 });
                 }
                 try {
                     const body = JSON.parse(raw || "{}");
-                    const outcome = await ctrl.resolve({ decisionId: body.decisionId, verdict: body.verdict, reason: body.reason });
+                    const outcome = await wake(body.decisionId);
                     return new Response(JSON.stringify(webhookBody(outcome)), { status: 200, headers: { "content-type": "application/json" } });
                 }
                 catch (e) {
@@ -1173,7 +1279,7 @@ export function createDecidioResume(opts) {
                 return { reportRecorded: false, executionConfirmed: false, diagnostic: `the evidence you passed to reconcile("${decisionId}") is not reportable as-is (${e?.message ?? e}). Nothing was settled. Pass plain JSON — the same rule your action's return value follows.` };
             }
             const settleSig = opts.outcome === "committed"
-                ? signEvidence(decisionId, entry.attemptId ?? null, settleEvidence, ctrl.agentKey, ctrl.webhookSecret)
+                ? signEvidence(decisionId, entry.attemptId ?? null, settleEvidence, ctrl.agentKey, integrityKey())
                 : undefined;
             try {
                 await ctrl.store.settle(decisionId, opts.outcome, { evidence: settleEvidence, reason: opts.reason, evidenceSig: settleSig, workerStopped: opts.workerStopped });
@@ -1239,7 +1345,7 @@ export function createDecidioResume(opts) {
                 };
             }
             const evStrict = !!ctrl.agentKey;
-            const evStatus = verifyEvidence(entry, ctrl.agentKey, ctrl.webhookSecret);
+            const evStatus = verifyEvidence(entry, ctrl.agentKey, integrityKey());
             if (evStatus === "mismatch") {
                 return { reportRecorded: false, executionConfirmed: false, diagnostic: `the recorded evidence for ${decisionId} does not match its integrity binding — it was altered after this agent wrote it. REFUSING to attest it. Inspect the pending store; if you know the true outcome, settle it with reconcile("${decisionId}", …).` };
             }
@@ -1353,7 +1459,7 @@ export function createDecidioResume(opts) {
                         try {
                             let outcome;
                             try {
-                                outcome = await ctrl.resolve({ decisionId: p.decisionId, verdict, reason: st.reason });
+                                outcome = await resolveCore({ decisionId: p.decisionId, verdict, ...(typeof st.reason === "string" && st.reason ? { reason: st.reason } : {}) }, st);
                             }
                             catch (e) {
                                 if (e instanceof DecidioStateCorruptError) {

package/dist/signing.d.ts

@@ -1,3 +1,4 @@
+import { type JsonValue } from "./canonical.js";
 /** Sorted-key JCS — must match apps/api/src/canonical.ts byte-for-byte.
  *
  *  ONE IMPLEMENTATION (F-006). This was a module-local copy that reached `JSON.stringify` for every
@@ -91,6 +92,45 @@ export declare const carriesCredential: (c: {
     agentKey?: string;
     agentDid?: string;
 }) => boolean;
+/** The agent-held secret a request commitment (and the LangGraph idempotency key) is keyed with. */
+export interface BindingMaterial {
+    readonly kind: "ed25519" | "api-token";
+    readonly secret: Buffer;
+}
+/** The key material this configuration binds approvals with: the Ed25519 signing key when signing is
+ *  configured (`agentKey` AND `agentDid`, the same predicate the identity proof uses), else the API
+ *  token, else none. Throws on a signing key that cannot be read - the identity proof would refuse the
+ *  same key, and silently binding with the token instead would make two processes disagree. */
+export declare function bindingMaterial(cfg: {
+    agentKey?: string;
+    agentDid?: string;
+    apiToken?: string;
+}): BindingMaterial | undefined;
+/** The exact request an approval covers. The core wrapper commits to what EXECUTES — the canonical
+ *  argument snapshot plus the described action/amount/scope; an engine adapter cannot see inside its
+ *  `run()` closure, so it commits to the whole described context (display details included). */
+export interface CommittedRequest {
+    action: string;
+    amount: number;
+    scope?: string | null;
+    context?: Record<string, string | number> | null;
+    args?: readonly unknown[];
+    /** Python only (keyword arguments); present in the shape so the two languages share one model. */
+    kwargs?: Record<string, unknown>;
+}
+/** The canonical bytes a commitment covers: optional members OMITTED when absent (null counts as
+ *  absent), so the two languages hash the same bytes. */
+export declare function committedRequestJson(request: CommittedRequest): string;
+/** lowercase-hex HMAC-SHA256 over the canonical request, under the agent-held key. */
+export declare function requestCommitment(material: BindingMaterial, request: CommittedRequest): string;
+/** lowercase-hex idempotency key over an execution identity (e.g. LangGraph's thread + task +
+ *  commitment), keyed so the host's thread ids never reach Decidio in the clear. */
+export declare function idempotencyKey(material: BindingMaterial, identity: Record<string, JsonValue>): string;
+/** The Claude Code hook's request scope: `cmd-` + 16 hex of a KEYED digest over the command text and its subject
+ *  (chat approvals follow-up, invariant-guard 2026-10-15). The text may carry a credential the display redacts; an
+ *  unkeyed digest sealed beside the redacted text would be an offline oracle for a weak password. Keyed under its own
+ *  domain, so it is deterministic for this agent and nothing to anyone without the key material. */
+export declare function boundScope(material: BindingMaterial, text: string): string;
 /** A signed, DOMAIN-SEPARATED, versioned attestation that THIS agent reported THIS captured
  *  response for THIS decision. Distinct from the identity proof (`signConfirm`) in every field
  *  that matters, so a report can never be lifted from one decision onto another: the decision id,

package/dist/signing.js

@@ -1,4 +1,4 @@
-import { generateKeyPairSync, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, createHash, randomUUID } from "node:crypto";
+import { generateKeyPairSync, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, createHash, createHmac, randomUUID } from "node:crypto";
 import { canonicalJson } from "./canonical.js";
 const B58 = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
 function b58encode(buf) {
@@ -159,6 +159,48 @@ export function assertSafeTransport(url, hasCredential) {
         : `[decidio] refusing to talk to ${u.origin} over plaintext http — Decidio is https, and an unauthenticated plaintext reply cannot be trusted to carry an authority decision. Use https, or localhost for local dev. Nothing was sent.`);
 }
 export const carriesCredential = (c) => !!c.apiToken || !!(c.agentKey && c.agentDid);
+export function bindingMaterial(cfg) {
+    if (cfg.agentKey && cfg.agentDid) {
+        let jwk;
+        try {
+            jwk = createPrivateKey({ key: Buffer.from(cfg.agentKey, "base64"), format: "der", type: "pkcs8" }).export({ format: "jwk" });
+        }
+        catch (e) {
+            throw new Error(`[decidio] DECIDIO_AGENT_KEY is not a readable private key (PKCS8, base64): ${e?.message ?? e}. It binds this agent's approvals to their requests; restore the key \`init\` wrote, or unset DECIDIO_AGENT_KEY/DECIDIO_AGENT_DID. Nothing was sent or executed.`);
+        }
+        if (jwk.crv !== "Ed25519" || typeof jwk.d !== "string") {
+            throw new Error(`[decidio] DECIDIO_AGENT_KEY is not an Ed25519 private key (got ${JSON.stringify(jwk.crv ?? null)}). Restore the key \`init\` wrote. Nothing was sent or executed.`);
+        }
+        return { kind: "ed25519", secret: Buffer.from(jwk.d, "base64url") };
+    }
+    if (cfg.apiToken)
+        return { kind: "api-token", secret: Buffer.from(cfg.apiToken, "utf8") };
+    return undefined;
+}
+function bindingSubkey(m, label) {
+    return createHmac("sha256", m.secret).update(`${label}/${m.kind}`, "utf8").digest();
+}
+export function committedRequestJson(request) {
+    const r = { action: request.action, amount: request.amount };
+    if (request.scope !== undefined && request.scope !== null)
+        r.scope = request.scope;
+    if (request.context !== undefined && request.context !== null)
+        r.context = request.context;
+    if (request.args !== undefined && request.args !== null)
+        r.args = request.args;
+    if (request.kwargs !== undefined && request.kwargs !== null)
+        r.kwargs = request.kwargs;
+    return canonicalJson(r, "request commitment");
+}
+export function requestCommitment(material, request) {
+    return createHmac("sha256", bindingSubkey(material, "decidio.request-commitment.v1")).update(committedRequestJson(request), "utf8").digest("hex");
+}
+export function idempotencyKey(material, identity) {
+    return createHmac("sha256", bindingSubkey(material, "decidio.idempotency-key.v1")).update(canonicalJson(identity, "idempotency identity"), "utf8").digest("hex");
+}
+export function boundScope(material, text) {
+    return "cmd-" + createHmac("sha256", bindingSubkey(material, "decidio.hook-scope.v1")).update(text, "utf8").digest("hex").slice(0, 16);
+}
 export function signExecutionReport(privateKeyBase64, fields) {
     const key = createPrivateKey({ key: Buffer.from(privateKeyBase64, "base64"), format: "der", type: "pkcs8" });
     const nonce = fields.nonce ?? randomUUID();