@decidio/sdk 0.1.8 → 0.1.9

package/dist/resume.d.ts

@@ -1,4 +1,6 @@
 import type { RequestListener } from "node:http";
+/** A routed action parked on the agent side, awaiting human approval. The `args`
+ *  are the original call arguments, replayed verbatim when the action resumes. */
 export interface PendingAction {
     decisionId: string;
     receiptId?: string;
@@ -7,17 +9,37 @@ export interface PendingAction {
     scope?: string;
     args: unknown[];
     createdAt: string;
+    /** Integrity binding over {decisionId, action, amount, scope, args} (round-6 acceptance
+     *  catch: the parked payload was mutable between routing and execution). ed25519 = detached
+     *  signature by the agent's key; hmac = keyed by the webhook secret. Verified before ANY
+     *  re-execution; a mismatch REFUSES and leaves the file for inspection. When the controller
+     *  holds an agent key, a MISSING signature is also refused (a stripped signature is
+     *  indistinguishable from tampering) — including entries parked by pre-0.1.6 versions:
+     *  drain pending approvals before upgrading, or delete + re-run them. Only a keyless
+     *  controller executes unbound entries (with a loud warning). Honest scope: this defends
+     *  against modification by anything lacking the agent's key material — a fully compromised
+     *  agent host can bypass the guard entirely and is out of client-side scope (server-sealed
+     *  args binding is the receipt-v2 design). */
     argsSig?: {
         kind: "ed25519" | "hmac";
         sig: string;
     };
 }
+/** Where suspended actions live between request and approval. The default is a
+ *  file store; swap in Redis/Postgres/your queue for production. AGENT-SIDE only —
+ *  Decidio never sees this. */
 export interface PendingStore {
     put(p: PendingAction): Promise<void>;
     get(decisionId: string): Promise<PendingAction | null>;
     delete(decisionId: string): Promise<void>;
     list(): Promise<PendingAction[]>;
+    /** Atomically take ownership of a parked action for execution. Returns true if THIS
+     *  caller claimed it, false if it's already claimed/gone — the cross-process single-use
+     *  guarantee (a production store backs this with rename/SETNX/SELECT-FOR-UPDATE). A
+     *  claimed entry is excluded from list(). Optional: if absent, the controller falls
+     *  back to an in-process guard (same-process only). */
     claim?(decisionId: string): Promise<boolean>;
+    /** Undo a claim so a failed execution is retryable. */
     release?(decisionId: string): Promise<void>;
 }
 export declare class MemoryPendingStore implements PendingStore {
@@ -30,6 +52,11 @@ export declare class MemoryPendingStore implements PendingStore {
     claim(id: string): Promise<boolean>;
     release(id: string): Promise<void>;
 }
+/** File-backed store so a COLD process (the original requester long gone) can still
+ *  resume — the proof that nothing is "kept alive". One JSON file per decision. A claim
+ *  renames `<id>.json` → `<id>.claimed` atomically (same-volume rename), so two processes
+ *  sharing the dir can't both execute. (A stale `.claimed` from a crash mid-execute needs
+ *  TTL recovery — tracked in the backlog.) */
 export declare class FilePendingStore implements PendingStore {
     private dir;
     constructor(dir: string);
@@ -43,6 +70,10 @@ export declare class FilePendingStore implements PendingStore {
     claim(id: string): Promise<boolean>;
     release(id: string): Promise<void>;
 }
+/** Thrown by a `withApproval`-wrapped call when the action is routed and configured
+ *  for async resume: the action is now SUSPENDED (parked in the store), not failed.
+ *  The caller can stop here — the process may even exit; the resume transport will
+ *  complete it later. */
 export declare class DecidioSuspendedError extends Error {
     decisionId: string;
     action: string;
@@ -55,31 +86,71 @@ export interface ResumeOutcome {
     action?: string;
     result?: unknown;
     reason?: string;
+    /** executed only: did the execution-evidence report reach Decidio AND come back with a recorded
+     *  tier? `status: "executed"` describes the LOCAL run; this describes the record (prodsec F-03:
+     *  the two were conflated, and a lost confirmation read as success). */
+    confirmed?: boolean;
+    /** executed only: the evidence tier the server says it recorded (e.g. application_confirmed). */
+    evidenceTier?: string;
 }
+/** Minimal config the controller needs to confirm outcomes + poll status. Shared
+ *  with GuardConfig (apiUrl/apiToken). */
 export interface ResumeConfig {
     apiUrl: string;
     apiToken?: string;
+    /** Agent identity for SIGNING the confirm call on resume (so the durable path can earn the
+     *  application_confirmed tier, not just the inline path). Default from DECIDIO_AGENT_ID/
+     *  _KEY/_DID env when unset — a cold resume process that has the env signs automatically. */
     agentId?: string;
     agentKey?: string;
     agentDid?: string;
+    /** The workspace the agent acts in (DECIDIO_WORKSPACE_ID) — bound into the cold-resume confirm
+     *  proof (D-B3.6) so it's tenant-scoped too. Default from env when unset. */
     workspaceId?: string;
+    /** Shared secret Decidio signs the resume webhook with (HMAC-SHA256). Defaults to
+     *  the API token if unset. Verified before any re-execution. */
     webhookSecret?: string;
+    /** Escape hatch to accept UNSIGNED resume webhooks (no secret). Off by default:
+     *  with no secret and this unset, the webhook handler rejects every call (fail
+     *  closed) so a misconfigured agent can't be driven by forged callbacks. Setting it
+     *  true REMOVES webhook authenticity — anyone who can reach the endpoint can signal
+     *  work — and the controller says so loudly at startup (prodsec F-07: an absolute
+     *  fail-closed claim must disclose its opt-out). Only behind a trusted network
+     *  boundary (e.g. mTLS / private mesh), never on an internet-reachable endpoint. */
     allowUnsigned?: boolean;
+    /** The callback URL Decidio should POST the verdict to (webhook transport). Sent
+     *  on /agent/authorize so the decision carries it; omit when using the poll worker. */
     resumeUrl?: string;
+    /** Fired after every terminal resolution (executed / rejected / blocked / no_handler),
+     *  via either transport. Use it to log, close a listener, or exit a CLI. */
     onResolved?: (o: ResumeOutcome) => void;
     fetchImpl?: typeof fetch;
 }
+/** Re-execute the agent's own fn on approval, confirm the captured outcome to
+ *  Decidio, and clear the parked entry. Bound to a store + a registry of raw fns. */
 export interface ResumeController extends ResumeConfig {
     store: PendingStore;
+    /** Register a RAW fn under its action name so a (possibly cold) resume can replay
+     *  it. `withApproval` auto-registers on the hot path; a cold worker/service should
+     *  register at startup so it can resume actions it never originated. */
     register(action: string, fn: (...args: any[]) => Promise<any>): void;
+    /** Park a routed action WITH its integrity binding (prefer this over store.put — the
+     *  binding is what lets resolve() refuse a tampered payload). */
     park(p: Omit<PendingAction, "createdAt" | "argsSig">): Promise<void>;
+    /** Drive a parked decision to completion once a verdict is known. Idempotent:
+     *  a second call after success finds nothing parked → "unknown" (no double-write). */
     resolve(input: {
         decisionId: string;
         verdict: "approved" | "rejected" | "blocked";
         reason?: string;
     }): Promise<ResumeOutcome>;
+    /** node:http listener for Decidio's signed approval webhook (Express/Fastify/node). */
     webhookHandler(): RequestListener;
+    /** Web-Fetch handler (Request → Response) for Next.js route handlers, Hono,
+     *  Cloudflare Workers, Bun, Deno. Same fail-closed signature check. */
     fetchHandler(): (req: Request) => Promise<Response>;
+    /** Poll-based resume for hosts with no inbound URL (CLI/laptop). A long-lived
+     *  watcher — this is a durable WORKER, not the request path blocking. */
     worker(opts?: {
         intervalMs?: number;
         timeoutMs?: number;
@@ -89,7 +160,25 @@ export interface ResumeController extends ResumeConfig {
     };
 }
 declare function sign(secret: string, body: string): string;
+/** Verify Decidio's `x-decidio-signature` over the raw webhook body (HMAC-SHA256).
+ *  Exported so engine adapters (e.g. the Inngest bridge) reuse the exact check. */
 export declare function verifyResumeSignature(secret: string, body: string, header: string | undefined): boolean;
+/** The ONE confirm-body rule, used by ALL THREE TS confirm doors (resume, inline withApproval,
+ *  adapter gate — guard equivalent-path catch: it lived only on the resume door). Transport
+ *  success is not confirmation (prodsec F-03): a 2xx whose body carries no recorded tier is a
+ *  FAILED confirm; a SIGNED confirm coming back below application_confirmed is disclosed, never
+ *  silent. Returns the recorded tier or throws. */
+export declare function assertConfirmRecorded(body: any, decisionId: string, signed: boolean): string;
+/**
+ * Build the resume controller. Spread it into your GuardConfig as `resume`, then
+ * either mount `webhookHandler()` (production) or run `worker()` (CLI/laptop).
+ *
+ *   const resume = createDecidioResume({ apiUrl, apiToken, store: new FilePendingStore(".decidio-pending"), resumeUrl });
+ *   const guard  = { apiUrl, agentId, apiToken, resume };
+ *   const createOpportunity = withApproval(createOpportunityRaw, describe, guard);
+ *   // production:  http.createServer(resume.webhookHandler()).listen(4100)
+ *   // or CLI:      resume.worker()
+ */
 export declare function createDecidioResume(opts: ResumeConfig & {
     store: PendingStore;
 }): ResumeController;

package/dist/resume.js

@@ -1,7 +1,27 @@
+// @decidio/sdk — durable async resume.
+//
+// The hard problem behind a "one-line" agent gate: a real human approval takes
+// minutes to days. Nobody watches a 60-second polling window. So a routed action
+// must SUSPEND (the requesting process may even exit) and RESUME later when the
+// approval arrives — and the AGENT must perform its own action on resume. Decidio
+// stays the approval layer above: it authorizes, records, and (on approval) SIGNALS
+// the agent. It never holds the agent's downstream credentials and never executes
+// the write itself. This is the same shape as HumanLayer's webhooks, Temporal
+// Signals, Inngest waitForEvent, and Decidio's own A2A `input-required` state.
+//
+// Two resume transports, same core:
+//   • webhookHandler() — production: Decidio POSTs a signed verdict to the agent's
+//     resume URL; the handler re-executes the agent's own fn and confirms.
+//   • worker()         — no inbound URL (laptop/CLI): a long-lived watcher polls
+//     /agent/status for each pending decision, then re-executes on approval.
+// Either way the args are replayed from an AGENT-SIDE store (Decidio holds none of
+// the downstream payload — only the authority decision), and execution is single-use
+// (the pending entry is deleted on completion, so a duplicate signal can't double-write).
 import { createHmac, timingSafeEqual, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify } from "node:crypto";
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, rmSync, renameSync } from "node:fs";
 import { join } from "node:path";
-import { signConfirm, canonicalize } from "./signing.js";
+import { signConfirm, canonicalize, assertJsonSafe } from "./signing.js";
+// ---- parked-payload integrity (round-6 acceptance catch) -------------------------------------
 const argsBindingBytes = (p) => Buffer.from(canonicalize({ decisionId: p.decisionId, action: p.action, amount: p.amount, ...(p.scope !== undefined ? { scope: p.scope } : {}), args: p.args }), "utf8");
 function signArgs(p, agentKey, webhookSecret) {
     const bytes = argsBindingBytes(p);
@@ -10,7 +30,7 @@ function signArgs(p, agentKey, webhookSecret) {
             const key = createPrivateKey({ key: Buffer.from(agentKey, "base64"), format: "der", type: "pkcs8" });
             return { kind: "ed25519", sig: Buffer.from(edSign(null, bytes, key)).toString("base64url") };
         }
-        catch { }
+        catch { /* fall through to hmac */ }
     }
     if (webhookSecret)
         return { kind: "hmac", sig: createHmac("sha256", webhookSecret).update(bytes).digest("hex") };
@@ -48,6 +68,11 @@ export class MemoryPendingStore {
         return false; this.claimed.add(id); return true; }
     async release(id) { this.claimed.delete(id); }
 }
+/** File-backed store so a COLD process (the original requester long gone) can still
+ *  resume — the proof that nothing is "kept alive". One JSON file per decision. A claim
+ *  renames `<id>.json` → `<id>.claimed` atomically (same-volume rename), so two processes
+ *  sharing the dir can't both execute. (A stale `.claimed` from a crash mid-execute needs
+ *  TTL recovery — tracked in the backlog.) */
 export class FilePendingStore {
     dir;
     constructor(dir) {
@@ -70,8 +95,12 @@ export class FilePendingStore {
     async list() {
         if (!existsSync(this.dir))
             return [];
+        // ONE BAD FILE MUST NOT STALL THE QUEUE: an unparseable entry (partial write, disk corruption,
+        // a human editing it) used to throw out of list() and take every other parked action down with
+        // it — a worker that can never poll is a worker that never resumes anything. Skip it loudly
+        // and keep the rest moving; the bad file stays on disk for inspection.
         const out = [];
-        for (const f of readdirSync(this.dir).filter((f) => f.endsWith(".json"))) {
+        for (const f of readdirSync(this.dir).filter((f) => f.endsWith(".json"))) { // .claimed excluded — in flight
             try {
                 out.push(JSON.parse(readFileSync(join(this.dir, f), "utf8")));
             }
@@ -85,7 +114,7 @@ export class FilePendingStore {
         try {
             renameSync(this.path(id), this.claimedPath(id));
             return true;
-        }
+        } // atomic; fails if already claimed/gone
         catch {
             return false;
         }
@@ -94,9 +123,13 @@ export class FilePendingStore {
         try {
             renameSync(this.claimedPath(id), this.path(id));
         }
-        catch { }
+        catch { /* already released/gone */ }
     }
 }
+/** Thrown by a `withApproval`-wrapped call when the action is routed and configured
+ *  for async resume: the action is now SUSPENDED (parked in the store), not failed.
+ *  The caller can stop here — the process may even exit; the resume transport will
+ *  complete it later. */
 export class DecidioSuspendedError extends Error {
     decisionId;
     action;
@@ -111,6 +144,8 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function sign(secret, body) {
     return "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
 }
+/** Verify Decidio's `x-decidio-signature` over the raw webhook body (HMAC-SHA256).
+ *  Exported so engine adapters (e.g. the Inngest bridge) reuse the exact check. */
 export function verifyResumeSignature(secret, body, header) {
     if (!header)
         return false;
@@ -118,17 +153,39 @@ export function verifyResumeSignature(secret, body, header) {
     const a = Buffer.from(expected), b = Buffer.from(header);
     return a.length === b.length && timingSafeEqual(a, b);
 }
+/** The ONE confirm-body rule, used by ALL THREE TS confirm doors (resume, inline withApproval,
+ *  adapter gate — guard equivalent-path catch: it lived only on the resume door). Transport
+ *  success is not confirmation (prodsec F-03): a 2xx whose body carries no recorded tier is a
+ *  FAILED confirm; a SIGNED confirm coming back below application_confirmed is disclosed, never
+ *  silent. Returns the recorded tier or throws. */
+export function assertConfirmRecorded(body, decisionId, signed) {
+    if (!body || body.ok !== true || typeof body.confirmation !== "string") {
+        throw new Error(`confirm answered 2xx but reported no evidence tier — treating the confirmation as NOT recorded`);
+    }
+    if (signed && body.confirmation !== "application_confirmed") {
+        console.warn(`[decidio] execution evidence for ${decisionId} was recorded as "${body.confirmation}", not application_confirmed, despite a signed report — the server did not accept the identity proof (key/DID/registration mismatch?). Run \`npx @decidio/sdk doctor\` and re-init if this persists.`);
+    }
+    return body.confirmation;
+}
+/** Resume-door confirm: POST + the shared body rule above. */
 async function confirm(cfg, decisionId, capturedResponse) {
     const f = cfg.fetchImpl ?? fetch;
+    // Sign the confirm so the DURABLE/resume path can earn application_confirmed too (bound to
+    // {action:"confirm", scope:decisionId}); without a key the server caps it at agent_asserted.
     const requesterIdentity = signConfirm(decisionId, cfg);
+    // Same no-silent-downgrade rule as the inline wrap (guard equivalent-path catch): the durable
+    // path is what production agents run, so it must disclose an agent_asserted cap too.
     if (!requesterIdentity)
         console.warn(`[decidio] execution evidence for ${decisionId} recorded as agent_asserted — no signing key configured, so the report can't be proven to come from this agent. Set DECIDIO_AGENT_KEY/DID to earn application_confirmed.`);
-    await f(cfg.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
+    const r = await f(cfg.apiUrl.replace(/\/$/, "") + "/agent/confirm", {
         method: "POST",
         headers: { "content-type": "application/json", ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
         body: JSON.stringify({ decisionId, capturedResponse: capturedResponse ?? null, source: "wrapper", ...(requesterIdentity ? { requesterIdentity } : {}) }),
-    }).then((r) => { if (!r.ok)
-        throw new Error(`confirm ${r.status}`); });
+    });
+    if (!r.ok)
+        throw new Error(`confirm ${r.status}`);
+    const body = await r.json().catch(() => null);
+    return assertConfirmRecorded(body, decisionId, !!requesterIdentity);
 }
 async function statusOf(cfg, decisionId) {
     const f = cfg.fetchImpl ?? fetch;
@@ -139,25 +196,58 @@ async function statusOf(cfg, decisionId) {
         throw new Error(`status ${r.status}`);
     return r.json();
 }
+/**
+ * Build the resume controller. Spread it into your GuardConfig as `resume`, then
+ * either mount `webhookHandler()` (production) or run `worker()` (CLI/laptop).
+ *
+ *   const resume = createDecidioResume({ apiUrl, apiToken, store: new FilePendingStore(".decidio-pending"), resumeUrl });
+ *   const guard  = { apiUrl, agentId, apiToken, resume };
+ *   const createOpportunity = withApproval(createOpportunityRaw, describe, guard);
+ *   // production:  http.createServer(resume.webhookHandler()).listen(4100)
+ *   // or CLI:      resume.worker()
+ */
 export function createDecidioResume(opts) {
     const registry = new Map();
-    const inFlight = new Set();
+    const inFlight = new Set(); // concurrent-duplicate guard (same process)
     const secret = opts.webhookSecret ?? opts.apiToken ?? "";
+    // CONTROLLER-scoped, not resolve()-scoped (guard catch: declared inside resolve, this Set was
+    // reborn empty every poll — the refusal printed 3/3 times, each ending with a false "prints
+    // once"). Refusals repeat on every cycle while the file sits parked; the MESSAGE must not.
+    // The opt-out of webhook authenticity must never be silent (prodsec F-07).
+    if (opts.allowUnsigned)
+        console.warn("[decidio] WARNING: allowUnsigned is ON — this controller will accept UNSIGNED resume webhooks. Anyone who can reach the endpoint can signal work (parked-payload integrity still gates execution). Use this only behind a trusted network boundary, never on an internet-reachable endpoint.");
+    const refusalWarned = new Set();
+    const refuseOnce = (decisionId, msg) => {
+        if (refusalWarned.has(decisionId))
+            return;
+        refusalWarned.add(decisionId);
+        console.error(msg + " (This prints once — the entry stays parked until you act.)");
+    };
     const ctrl = {
         ...opts,
+        // Default the signing identity from env so a COLD resume process (a fresh worker that has
+        // the agent's env but wasn't passed config) still signs the confirm and earns the wrapper tier.
         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,
+        workspaceId: opts.workspaceId ?? process.env.DECIDIO_WORKSPACE_ID, // D-B3.6: tenant-bind the cold-resume confirm proof
         webhookSecret: secret,
         store: opts.store,
         register(action, fn) {
+            // Silent last-writer-wins is the wrong default for an EXECUTION registry: two wrappers
+            // sharing an action name would let a resumed decision replay its args into the other
+            // function. Say so loudly — the parked args and the fn must be the pair that was routed.
             const prev = registry.get(action);
             if (prev && prev !== fn)
                 console.warn(`[decidio] action "${action}" is being registered again with a DIFFERENT function — the latest one wins, and a resumed decision would run IT. Give each protected function its own action name.`);
             registry.set(action, fn);
         },
         async park(p) {
+            // GATE, not serialization (prodsec F-01): a value that cannot survive JSON with its meaning
+            // intact must be REFUSED before it is signed or parked — the signature covers canonical
+            // bytes, and NaN/Map collide with null/{} in those bytes, so it would verify and execute
+            // with drifted semantics. Refusal here means no decision, no signature, no file.
+            assertJsonSafe(p.args, "args");
             const argsSig = signArgs(p, ctrl.agentKey, ctrl.webhookSecret);
             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.`);
@@ -168,7 +258,7 @@ export function createDecidioResume(opts) {
                 opts.onResolved?.(o); return o; };
             const pending = await ctrl.store.get(decisionId);
             if (!pending)
-                return { status: "unknown", decisionId };
+                return { status: "unknown", decisionId }; // not ours / already resumed
             if (verdict === "rejected") {
                 await ctrl.store.delete(decisionId);
                 return finish({ status: "rejected", decisionId, action: pending.action, reason });
@@ -177,30 +267,47 @@ export function createDecidioResume(opts) {
                 await ctrl.store.delete(decisionId);
                 return finish({ status: "blocked", decisionId, action: pending.action, reason });
             }
+            // Fail CLOSED on any unexpected verdict — never execute on a garbage/unknown value.
             if (verdict !== "approved" && verdict !== "auto_approved")
                 return { status: "unknown", decisionId };
+            // INTEGRITY BEFORE EXECUTION (round-6 acceptance catch: a locally edited pending file
+            // executed different arguments from those routed for approval).
+            // SLOT ASSERTION FIRST (guard catch): the store keys on the FILENAME while the signature
+            // covers the CONTENT's decisionId — without this line, copying validly-signed entry A into
+            // slot B executes A's args when B is approved. No forgery needed, so it must be checked
+            // even before signature verification.
             if (pending.decisionId !== decisionId) {
-                console.error(`[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.`);
+                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" });
             }
+            // STRICT binding is keyed to the agent's ED25519 signing key (what `init` writes) — an
+            // init'd agent always signs via park(), so an unbound entry there is tampering (incl. a
+            // stripped signature). A bare store.put user with no agent key keeps the documented
+            // low-level behavior (execute+warn); the apiToken-derived HMAC secret does NOT trigger
+            // strict mode (it lives in .env next to the pending dir — not a local-tamper defense).
             const strictBinding = !!ctrl.agentKey;
             const integrity = verifyArgs(pending, ctrl.agentKey, ctrl.webhookSecret);
             if (integrity === "mismatch") {
-                console.error(`[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.`);
+                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") {
-                console.error(`[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.`);
+                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) {
-                console.error(`[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.`);
+                // A controller WITH key material would have signed at park time, so a MISSING signature is
+                // itself tampering — an attacker stripping argsSig to reach the legacy path. Refuse. Only a
+                // keyless controller (genuine legacy / no-key deploy) may execute an unbound entry.
+                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);
             if (!fn) {
+                // Actionable, because this is the failure a restarted worker actually hits: the registry
+                // is per-process, and a cold process never ran the original call that would have filled it.
                 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}" });`);
@@ -209,19 +316,34 @@ export function createDecidioResume(opts) {
                 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` });
             }
+            // Atomically CLAIM before executing — the cross-process single-use guarantee. If
+            // the store has no claim primitive, fall back to an in-process guard (same-process).
             const claimed = ctrl.store.claim ? await ctrl.store.claim(decisionId) : (!inFlight.has(decisionId) && (inFlight.add(decisionId), true));
             if (!claimed)
-                return { status: "unknown", decisionId };
+                return { status: "unknown", decisionId }; // another worker owns it
             try {
+                // Approved: the AGENT performs its own action FIRST. If it throws, RELEASE the claim so
+                // the entry stays parked + retryable — an approved action is never lost.
                 const result = await fn(...pending.args);
+                // CONFIRM BEFORE DELETE. Deleting first meant a failed confirm lost the only local record
+                // that this action had executed — the evidence could never be re-sent. The entry stays
+                // CLAIMED throughout (claim, not presence, is what prevents double-execution), so keeping
+                // it a moment longer cannot cause a second run.
                 let confirmed = true;
+                let tier;
                 try {
-                    await confirm(ctrl, decisionId, result);
+                    tier = await confirm(ctrl, decisionId, result);
                 }
                 catch (e) {
                     confirmed = false;
                     console.warn(`[decidio] resume confirm failed (your action DID succeed): ${e.message}`);
                 }
+                // RETAIN-vs-DELETE on a failed confirm. Keeping the entry preserves local evidence that
+                // this action executed — but ONLY a store with claim() can guarantee a retained entry
+                // never runs again (its claim refuses it; the in-process fallback dies with the process).
+                // For a claim-LESS store the delete IS the single-use guarantee, so it must still happen:
+                // an undelivered confirmation is an evidence gap, a second execution is a double write,
+                // and we never trade the second away for the first.
                 const retainedIsSafe = typeof ctrl.store.claim === "function";
                 if (confirmed || !retainedIsSafe)
                     await ctrl.store.delete(decisionId);
@@ -231,7 +353,7 @@ export function createDecidioResume(opts) {
                     else
                         console.warn(`  This store provides no claim() primitive, so the entry was DELETED to guarantee the action cannot execute twice. ${decisionId} executed, but its confirmation never reached Decidio — re-confirm it from your own records.`);
                 }
-                return finish({ status: "executed", decisionId, action: pending.action, result });
+                return finish({ status: "executed", decisionId, action: pending.action, result, confirmed, ...(tier ? { evidenceTier: tier } : {}) });
             }
             catch (e) {
                 if (ctrl.store.release)
@@ -252,6 +374,9 @@ export function createDecidioResume(opts) {
                 req.on("data", (c) => (raw += c));
                 req.on("end", async () => {
                     try {
+                        // Fail CLOSED when no secret is configured: an agent that forgot to set a
+                        // webhookSecret must NOT be drivable by forged callbacks. Opt out only with
+                        // allowUnsigned (trusted network boundary).
                         if (!secret) {
                             if (!opts.allowUnsigned) {
                                 res.statusCode = 401;
@@ -318,8 +443,22 @@ export function createDecidioResume(opts) {
                                 st.state === "blocked" ? "blocked" : null;
                         if (!verdict)
                             continue;
+                        // A throwing resolve (the agent's own fn failed) must NOT kill the watcher —
+                        // the entry stays parked and is retried on the next poll.
                         try {
                             const outcome = await ctrl.resolve({ decisionId: p.decisionId, verdict, reason: st.reason });
+                            // ONE line per lifecycle event, on stderr (round-3 blind catch: the
+                            // production-recommended worker executed, restart-resumed and discarded actions in
+                            // total silence — the only evidence was a file vanishing). onResolved remains the
+                            // programmatic hook; this is the human-visible floor.
+                            if (outcome.status === "executed" && outcome.confirmed)
+                                console.error(`[decidio] resumed ${p.decisionId}: approved → "${p.action}" executed, evidence recorded as ${outcome.evidenceTier ?? "confirmed"}.`);
+                            else if (outcome.status === "executed")
+                                console.error(`[decidio] resumed ${p.decisionId}: approved → "${p.action}" executed, but its execution evidence did NOT reach Decidio — see the warning above.`);
+                            else if (outcome.status === "rejected")
+                                console.error(`[decidio] resumed ${p.decisionId}: REJECTED — the parked "${p.action}" was discarded, nothing executed.`);
+                            else if (outcome.status === "blocked")
+                                console.error(`[decidio] resumed ${p.decisionId}: BLOCKED by policy — the parked "${p.action}" was discarded, nothing executed.`);
                             workerOpts?.onResolved?.(outcome);
                         }
                         catch (e) {

package/dist/signing.d.ts

@@ -1,4 +1,8 @@
+/** Sorted-key JCS — must match apps/api/src/canonical.ts byte-for-byte. */
 export declare function canonicalize(v: unknown): string;
+/** Generate a fresh Ed25519 keypair LOCALLY. Returns the public `did:key` (register this)
+ *  and the PKCS8 private key base64 (keep this in the agent host's env as DECIDIO_AGENT_KEY —
+ *  it never goes back to Decidio). */
 export declare function generateKeypair(): {
     did: string;
     privateKeyBase64: string;
@@ -17,12 +21,20 @@ export interface RequesterIdentity {
         signature: string;
     };
 }
+/** Sign the CONFIRM call (bound to {action:"confirm", scope:decisionId}) so the gate can
+ *  prove the caller is the receipt's original requester before granting the wrapper tier
+ *  (application_confirmed). Returns undefined when no signing key is configured (the server
+ *  then caps the report at agent_asserted). Used by EVERY confirm path — inline, durable
+ *  resume, and the engine adapters — so the production paths confirm with a proof too. Also
+ *  binds `workspaceId` (D-B3.6) when configured, so the confirm proof is tenant-scoped too. */
 export declare function signConfirm(decisionId: string, cfg: {
     agentId?: string;
     agentKey?: string;
     agentDid?: string;
     workspaceId?: string;
 }): RequesterIdentity | undefined;
+/** Sign a request-bound identity proof. The returned object is sent verbatim as the
+ *  `requesterIdentity` field of /agent/authorize. */
 export declare function signBoundProof(privateKeyBase64: string, fields: {
     agentId: string;
     did: string;
@@ -34,3 +46,11 @@ export declare function signBoundProof(privateKeyBase64: string, fields: {
     now?: number;
     nonce?: string;
 }): RequesterIdentity;
+/** The values that do not survive `JSON.stringify → JSON.parse` with their meaning intact.
+ *  Refused at the GATE, before anything is routed, signed, or parked (prodsec F-01: `NaN`
+ *  canonicalized to `null` and a `Map` to `{}`, so the integrity signature matched the drifted
+ *  bytes and the function EXECUTED with arguments that meant something else — the exact wrong
+ *  execution the parked-payload signature exists to refuse). Throws naming the offending path;
+ *  returns nothing. The supported data model is plain JSON: null, boolean, string, finite
+ *  number, plain array, plain object. */
+export declare function assertJsonSafe(value: unknown, path?: string): void;