@decidio/sdk 0.1.10 → 0.1.11

package/dist/index.js

@@ -1,8 +1,14 @@
-import { DecidioSuspendedError, assertConfirmRecorded } from "./resume.js";
-import { signBoundProof, signConfirm, assertJsonSafe, assertSafeTransport, DecidioUnsafeArgumentsError } from "./signing.js";
+import { DecidioSuspendedError } from "./resume.js";
+import { signBoundProof, signConfirm, assertSafeTransport } from "./signing.js";
+import { canonicalize, canonicalizeArgs } from "./canonical.js";
+import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
 export { DecidioSuspendedError, FilePendingStore, MemoryPendingStore, createDecidioResume, assertConfirmRecorded } from "./resume.js";
 export { guard, Guard } from "./guard.js";
-export { generateKeypair, signBoundProof, signConfirm, canonicalize, assertJsonSafe, assertSafeTransport, DecidioUnsafeArgumentsError } from "./signing.js";
+export { DecidioHttpError } from "./errors.js";
+import { DecidioHttpError } from "./errors.js";
+export { generateKeypair, didFromPrivateKey, signBoundProof, signConfirm, signExecutionReport, verifyExecutionReport, resultDigest, assertSafeTransport } from "./signing.js";
+export { canonicalize, canonicalizeArgs, canonicalJson, DecidioUnsafeArgumentsError } from "./canonical.js";
+export { readConfirmResponse, buildConfirmBody, describeTierGap, EVIDENCE_TIERS } from "./evidence.js";
 export class DecidioBlockedError extends Error {
     reason;
     decisionId;
@@ -84,8 +90,15 @@ async function post(cfg, path, body) {
         const b = await res.json().catch(() => null);
         throw new DecidioRateLimitError(b?.limit, b?.remaining, b?.resetAt, b?.message);
     }
-    if (!res.ok)
-        throw new Error(`decidio ${path} ${res.status}: ${await res.text().catch(() => "")}`);
+    if (!res.ok) {
+        const raw = await res.text().catch(() => "");
+        let parsed = raw;
+        try {
+            parsed = raw ? JSON.parse(raw) : undefined;
+        }
+        catch { }
+        throw new DecidioHttpError(res.status, path, parsed);
+    }
     return res.json();
 }
 async function get(cfg, path) {
@@ -95,7 +108,7 @@ async function get(cfg, path) {
         headers: { ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
     });
     if (!res.ok)
-        throw new Error(`decidio ${path} ${res.status}`);
+        throw new DecidioHttpError(res.status, path);
     return res.json();
 }
 export function decisionUrl(appUrl, decisionId) {
@@ -103,27 +116,32 @@ export function decisionUrl(appUrl, decisionId) {
         return null;
     return `${appUrl.replace(/\/$/, "")}/d/${encodeURIComponent(decisionId)}`;
 }
-export function withApproval(fn, describe, config) {
+export function withApproval(fn, describe, config, opts) {
     const pollInterval = config.pollIntervalMs ?? 2_000;
     const pollTimeout = config.pollTimeoutMs ?? 600_000;
     const resumeUrl = config.resumeUrl ?? config.resume?.resumeUrl;
-    return async (...args) => {
+    return async (...rawArgs) => {
+        const args = canonicalizeArgs(rawArgs);
+        let ctx;
         try {
-            assertJsonSafe(args, "args");
+            ctx = describe(...args);
         }
         catch (e) {
-            throw new DecidioUnsafeArgumentsError(`${e?.message ?? e} The decision was NOT routed; nothing reached Decidio.`);
+            if (e instanceof TypeError && /read only|not extensible|object is not extensible|frozen/i.test(e.message ?? "")) {
+                throw new TypeError(`[decidio] your describe() callback tried to MODIFY the call arguments (${e.message}). ` +
+                    `Those arguments are the approved value: they are what a human sees, what the signature covers, ` +
+                    `what is parked for a durable resume, and what your function ultimately runs on — so changing them ` +
+                    `here would mean the action that executes is not the action that was approved. Read from the ` +
+                    `arguments and RETURN the context instead: (inv) => ({ action: "pay", amount: inv.amount }). ` +
+                    `If you need a modified value at execution time, compute it inside your function. ` +
+                    `Nothing was routed or executed.`);
+            }
+            throw e;
         }
-        const ctx = describe(...args);
         const requesterIdentity = (config.agentKey && config.agentDid)
             ? signBoundProof(config.agentKey, { agentId: config.agentId, did: config.agentDid, action: ctx.action, amount: ctx.amount, scope: ctx.scope, workspaceId: config.workspaceId })
             : undefined;
-        try {
-            assertJsonSafe(ctx, "describe(...)");
-        }
-        catch (e) {
-            throw new DecidioUnsafeArgumentsError(`${e?.message ?? e} The decision was NOT routed; nothing reached Decidio.`);
-        }
+        canonicalize(ctx, "describe(...)");
         const auth = await post(config, "/agent/authorize", {
             requester: config.agentId, action: ctx.action, amount: ctx.amount,
             scope: ctx.scope, sourceSystem: config.sourceSystem,
@@ -171,15 +189,14 @@ export function withApproval(fn, describe, config) {
         const result = await fn(...args);
         try {
             const confirmIdentity = signConfirm(auth.decisionId, config);
-            const confirmBody = await post(config, "/agent/confirm", {
-                decisionId: auth.decisionId,
-                capturedResponse: result ?? null,
-                source: "wrapper",
-                ...(confirmIdentity ? { requesterIdentity: confirmIdentity } : {}),
-            });
-            assertConfirmRecorded(confirmBody, auth.decisionId, !!confirmIdentity);
-            if (!confirmIdentity)
-                console.warn(`[decidio] execution evidence for ${auth.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 (npx @decidio/sdk init writes them) to earn application_confirmed.`);
+            const evidenceOf = (opts?.evidence ?? ((r) => r));
+            const reported = canonicalize(evidenceOf(result) ?? null, "evidence(result)");
+            const confirmBody = await post(config, "/agent/confirm", buildConfirmBody(config, auth.decisionId, reported, confirmIdentity));
+            const ev = readConfirmResponse(confirmBody, { signed: !!confirmIdentity, capturedResponse: reported });
+            if (!ev.reportRecorded)
+                console.warn(`[decidio] ${auth.decisionId}: ${ev.diagnostic}`);
+            else if (!ev.executionConfirmed)
+                console.warn(`[decidio] execution evidence for ${auth.decisionId} recorded as ${ev.evidenceTier} — ${ev.diagnostic}`);
         }
         catch (e) {
             console.warn(`[decidio] confirmation post failed (action succeeded): ${e.message}`);

package/dist/inngest.js

@@ -1,28 +1,10 @@
 import { verifyResumeSignature } from "./resume.js";
-import { signBoundProof, signConfirm } from "./signing.js";
+import { gateAuthorize, gateConfirm, assertAuthorizeVerdict, verdictFrom, checkEngineVersion } from "./adapters/_gate.js";
 export const DECIDIO_RESUME_EVENT = "decidio/decision.resolved";
 export async function decidioGateStep(args) {
     const { step, config, ctx } = args;
-    const base = config.apiUrl.replace(/\/$/, "");
-    const f = config.fetchImpl ?? fetch;
-    const authHeaders = { "content-type": "application/json", ...(config.apiToken ? { authorization: `Bearer ${config.apiToken}` } : {}) };
-    const auth = await step.run("decidio-authorize", async () => {
-        const requesterIdentity = (config.agentKey && config.agentDid)
-            ? signBoundProof(config.agentKey, { agentId: config.agentId, did: config.agentDid, action: ctx.action, amount: ctx.amount, scope: ctx.scope, workspaceId: config.workspaceId })
-            : undefined;
-        const res = await f(base + "/agent/authorize", {
-            method: "POST", headers: authHeaders,
-            body: JSON.stringify({
-                requester: config.agentId, action: ctx.action, amount: ctx.amount, scope: ctx.scope,
-                sourceSystem: config.sourceSystem,
-                ...(requesterIdentity ? { requesterIdentity } : {}),
-                ...(config.resumeUrl ? { resumeUrl: config.resumeUrl } : {}),
-            }),
-        });
-        if (!res.ok)
-            throw new Error(`decidio authorize ${res.status}`);
-        return res.json();
-    });
+    const auth = await step.run("decidio-authorize", async () => gateAuthorize(config, ctx));
+    assertAuthorizeVerdict(auth, auth?.decisionId);
     if (auth.decision === "block")
         return { status: "blocked", decisionId: auth.decisionId };
     if (auth.decision === "route") {
@@ -33,21 +15,14 @@ export async function decidioGateStep(args) {
         });
         if (!ev)
             throw new Error(`decidio approval timed out (${auth.decisionId})`);
-        const verdict = ev.data?.verdict;
+        const verdict = verdictFrom(ev.data);
         if (verdict === "rejected")
             return { status: "rejected", decisionId: auth.decisionId };
         if (verdict !== "approved" && verdict !== "auto_approved")
             return { status: "blocked", decisionId: auth.decisionId };
     }
     const result = await step.run("agent-action", args.run);
-    await step.run("decidio-confirm", async () => {
-        const requesterIdentity = signConfirm(auth.decisionId, config);
-        await f(base + "/agent/confirm", {
-            method: "POST", headers: authHeaders,
-            body: JSON.stringify({ decisionId: auth.decisionId, capturedResponse: result ?? null, source: "wrapper", ...(requesterIdentity ? { requesterIdentity } : {}) }),
-        });
-        return true;
-    });
+    await step.run("decidio-confirm", async () => { await gateConfirm(config, auth.decisionId, result); return true; });
     return { status: "executed", decisionId: auth.decisionId, result };
 }
 export function createInngestResumeBridge(opts) {
@@ -86,3 +61,4 @@ export function createInngestResumeBridge(opts) {
     };
 }
 export { verifyResumeSignature };
+checkEngineVersion("inngest");

package/dist/resume.d.ts

@@ -1,4 +1,5 @@
 import type { RequestListener } from "node:http";
+import { type EvidenceOutcome, type EvidenceTier } from "./evidence.js";
 /** 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 {
@@ -41,6 +42,9 @@ export interface PendingStore {
     claim?(decisionId: string): Promise<boolean>;
     /** Undo a claim so a failed execution is retryable. */
     release?(decisionId: string): Promise<void>;
+    /** Entries currently CLAIMED (excluded from list()). Needed for honest recovery reporting —
+     *  a claimed entry with no journalled result is the indeterminate case. */
+    listClaimed?(): Promise<PendingAction[]>;
 }
 export declare class MemoryPendingStore implements PendingStore {
     private m;
@@ -51,7 +55,13 @@ export declare class MemoryPendingStore implements PendingStore {
     list(): Promise<PendingAction[]>;
     claim(id: string): Promise<boolean>;
     release(id: string): Promise<void>;
+    listClaimed(): Promise<PendingAction[]>;
 }
+/** Restrict a directory to its owner. On Windows POSIX modes are a no-op, so strip inheritance
+ *  and grant only the effective user. A FAILURE IS SAID, never swallowed: these files hold the
+ *  arguments of actions awaiting approval, and "silently kept the directory's inherited
+ *  permissions" is exactly the outcome an operator must not discover from an auditor. */
+export declare function hardenDir(dir: string): 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
@@ -69,6 +79,9 @@ export declare class FilePendingStore implements PendingStore {
     list(): Promise<PendingAction[]>;
     claim(id: string): Promise<boolean>;
     release(id: string): Promise<void>;
+    /** Claimed entries (`.claimed` files) — invisible to list() by design, but a stranded one is
+     *  exactly what recovery must surface. */
+    listClaimed(): Promise<PendingAction[]>;
 }
 /** 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.
@@ -80,18 +93,57 @@ export declare class DecidioSuspendedError extends Error {
     constructor(decisionId: string, action: string);
 }
 export type ResumeStatus = "executed" | "rejected" | "blocked" | "no_handler" | "unknown";
+/** A durable note that an action ALREADY RAN and what must still be reported. It lives OUTSIDE
+ *  the pending store on purpose: a journal entry carries no handler binding, so replaying it can
+ *  only ever re-send a report — it can never re-run the business action. That is what makes
+ *  recovery safe on stores with and without claim(). */
+export interface ExecutionJournalEntry {
+    decisionId: string;
+    action: string;
+    /** The canonical value that was reported — the durable FACT, journalled before the first
+     *  attempt. Deliberately NOT the signed request: both proofs on a confirm are short-lived (the
+     *  identity proof lives 120s, the execution report 5 minutes), so a replayed envelope is
+     *  refused by the server for any outage longer than that — which is every outage worth
+     *  recovering from. `reconfirm` re-signs at SEND time over these same bytes, so the report
+     *  stays replay-safe (it still cannot re-run anything: no handler is journalled) while staying
+     *  usable a week later. */
+    reported: unknown;
+    at: string;
+}
+/** The states a durable action can actually be in — every one of them nameable, including the
+ *  one nobody likes. */
+export type RecoveryState = 
+/** Parked, waiting on a human. Nothing has executed. */
+"parked"
+/** Claimed for execution and NOT journalled: the process died somewhere between claiming and
+ *  recording the result. The action MAY OR MAY NOT have run — this cannot be resolved locally
+ *  and must never be retried automatically. */
+ | "indeterminate"
+/** Executed, result captured, report not yet accepted by Decidio. Safe to `reconfirm`. */
+ | "executed_unreported";
+export interface RecoveryItem {
+    decisionId: string;
+    action?: string;
+    state: RecoveryState;
+    /** What a human should do about it, in words. */
+    guidance: string;
+}
 export interface ResumeOutcome {
     status: ResumeStatus;
     decisionId: string;
     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 — a lost
-     *  confirmation must never read as recorded evidence. */
-    confirmed?: boolean;
-    /** executed only: the evidence tier the server says it recorded (e.g. application_confirmed). */
-    evidenceTier?: string;
+    /** executed only: Decidio ACCEPTED the execution report and named the tier it recorded.
+     *  `status: "executed"` describes the LOCAL run; this describes the record. */
+    reportRecorded?: boolean;
+    /** executed only: the recorded tier attests a COMMITTED execution. Deliberately a different
+     *  question — and a different name — from `reportRecorded`. */
+    executionConfirmed?: boolean;
+    /** executed only: the evidence tier Decidio recorded, verbatim. */
+    evidenceTier?: EvidenceTier;
+    /** executed only: why the evidence landed where it did, when that is worth explaining. */
+    diagnostic?: string;
 }
 /** Minimal config the controller needs to confirm outcomes + poll status. Shared
  *  with GuardConfig (apiUrl/apiToken). */
@@ -110,6 +162,12 @@ export interface ResumeConfig {
     /** Shared secret Decidio signs the resume webhook with (HMAC-SHA256). Defaults to
      *  the API token if unset. Verified before any re-execution. */
     webhookSecret?: string;
+    /** Where the execution journal lives (default `<pending dir>/reports`). Separate from the
+     *  pending store by design: journal entries can only re-send a report, never re-run an action. */
+    reportDir?: string;
+    /** Map the action's natural return value to the evidence Decidio records — same option, same
+     *  meaning as `protect`'s, so a durable resume reports exactly what the inline path would. */
+    evidence?: (result: any) => unknown;
     /** 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
@@ -158,6 +216,16 @@ export interface ResumeController extends ResumeConfig {
     }): {
         stop: () => void;
     };
+    /** Re-send a journalled execution report, IDEMPOTENTLY. Replays the exact request built before
+     *  the first attempt — it can never re-run the business action, because the journal holds no
+     *  handler binding. Returns the evidence outcome; a decision with nothing journalled returns
+     *  `reportRecorded: false` with guidance rather than pretending. */
+    reconfirm(decisionId: string): Promise<EvidenceOutcome>;
+    /** Every durable item that needs a human's attention, with its state named — including the one
+     *  state that CANNOT be resolved automatically: `indeterminate`, where a process died between
+     *  claiming an action and journalling its result, so whether the action ran is unknown locally.
+     *  This never executes or retries anything; it reports. */
+    recover(): Promise<RecoveryItem[]>;
 }
 declare function sign(secret: string, body: string): string;
 /** Verify Decidio's `x-decidio-signature` over the raw webhook body (HMAC-SHA256).
@@ -168,16 +236,6 @@ export declare function verifyResumeSignature(secret: string, body: string, head
  *  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

@@ -3,8 +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, assertJsonSafe, assertSafeTransport, DecidioUnsafeArgumentsError } from "./signing.js";
-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");
+import { signConfirm, canonicalize as jcs, assertSafeTransport } from "./signing.js";
+import { canonicalize as toCanonical, DecidioUnsafeArgumentsError } from "./canonical.js";
+import { readConfirmResponse, buildConfirmBody } from "./evidence.js";
+import { DecidioHttpError } 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");
 function signArgs(p, agentKey, webhookSecret) {
     const bytes = argsBindingBytes(p);
     if (agentKey) {
@@ -49,24 +52,32 @@ export class MemoryPendingStore {
     async claim(id) { if (this.claimed.has(id) || !this.m.has(id))
         return false; this.claimed.add(id); return true; }
     async release(id) { this.claimed.delete(id); }
+    async listClaimed() { return [...this.claimed].map((id) => this.m.get(id)).filter(Boolean); }
+}
+export function hardenDir(dir) {
+    if (process.platform !== "win32")
+        return;
+    try {
+        const user = (() => { try {
+            return userInfo().username;
+        }
+        catch {
+            return process.env.USERNAME ?? process.env.USER ?? "";
+        } })();
+        if (!user)
+            throw new Error("could not determine the current user");
+        execFileSync("icacls", [dir, "/inheritance:r", "/grant:r", `${user}:(OI)(CI)F`], { stdio: "ignore" });
+    }
+    catch (e) {
+        console.warn(`[decidio] WARNING: could not restrict ${dir} to owner-only (${e?.message ?? e}). It keeps the directory's inherited permissions, so other accounts on this machine may be able to read parked action arguments. Move the pending store to a protected location, or set DECIDIO_PENDING_DIR to one.`);
+    }
 }
 export class FilePendingStore {
     dir;
     constructor(dir) {
         this.dir = dir;
         mkdirSync(dir, { recursive: true });
-        if (process.platform === "win32") {
-            try {
-                const user = (() => { try {
-                    return userInfo().username;
-                }
-                catch {
-                    return process.env.USERNAME ?? process.env.USER ?? "";
-                } })();
-                execFileSync("icacls", [dir, "/inheritance:r", "/grant:r", `${user}:(OI)(CI)F`], { stdio: "ignore" });
-            }
-            catch { }
-        }
+        hardenDir(dir);
     }
     key(id) { return id.replace(/[^\w.-]/g, "_"); }
     path(id) { return join(this.dir, `${this.key(id)}.json`); }
@@ -110,6 +121,20 @@ export class FilePendingStore {
         }
         catch { }
     }
+    async listClaimed() {
+        if (!existsSync(this.dir))
+            return [];
+        const out = [];
+        for (const name of readdirSync(this.dir)) {
+            if (!name.endsWith(".claimed"))
+                continue;
+            try {
+                out.push(JSON.parse(readFileSync(join(this.dir, name), "utf8")));
+            }
+            catch { }
+        }
+        return out;
+    }
 }
 export class DecidioSuspendedError extends Error {
     decisionId;
@@ -141,21 +166,31 @@ export function assertConfirmRecorded(body, decisionId, signed) {
     }
     return body.confirmation;
 }
-async function confirm(cfg, decisionId, capturedResponse) {
-    const f = cfg.fetchImpl ?? fetch;
-    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
+function buildResumeConfirmRequest(cfg, decisionId, canonicalResult) {
     const requesterIdentity = signConfirm(decisionId, cfg);
     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.`);
+        console.warn(`[decidio] execution evidence for ${decisionId} will be recorded as an unproven agent assertion — no signing key configured. Set DECIDIO_AGENT_KEY/DID to earn a confirming tier.`);
+    return buildConfirmBody({ agentId: cfg.agentId ?? "agent", agentKey: cfg.agentKey, agentDid: cfg.agentDid, workspaceId: cfg.workspaceId }, decisionId, canonicalResult, requesterIdentity);
+}
+async function postConfirm(cfg, decisionId, body) {
+    const f = cfg.fetchImpl ?? fetch;
+    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
     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 } : {}) }),
+        body: JSON.stringify(body),
     });
-    if (!r.ok)
-        throw new Error(`confirm ${r.status}`);
-    const body = await r.json().catch(() => null);
-    return assertConfirmRecorded(body, decisionId, !!requesterIdentity);
+    if (!r.ok) {
+        const raw = await r.text().catch(() => "");
+        let parsed = raw;
+        try {
+            parsed = raw ? JSON.parse(raw) : undefined;
+        }
+        catch { }
+        throw new DecidioHttpError(r.status, "/agent/confirm", parsed);
+    }
+    const parsed = await r.json().catch(() => null);
+    return readConfirmResponse(parsed, { signed: !!body.requesterIdentity, capturedResponse: body.capturedResponse, journalled: true });
 }
 async function statusOf(cfg, decisionId) {
     const f = cfg.fetchImpl ?? fetch;
@@ -164,15 +199,106 @@ async function statusOf(cfg, decisionId) {
         headers: { ...(cfg.apiToken ? { authorization: `Bearer ${cfg.apiToken}` } : {}) },
     });
     if (!r.ok)
-        throw new Error(`status ${r.status}`);
+        throw new DecidioHttpError(r.status, `/agent/status/${decisionId}`);
     return r.json();
 }
+class ReportJournal {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+        try {
+            mkdirSync(dir, { recursive: true });
+            hardenDir(dir);
+        }
+        catch { }
+    }
+    p(id) { return join(this.dir, `${id.replace(/[^\w.-]/g, "_")}.json`); }
+    write(e) { try {
+        writeFileSync(this.p(e.decisionId), JSON.stringify(e, null, 2), { mode: 0o600 });
+    }
+    catch { } }
+    read(id) { try {
+        return existsSync(this.p(id)) ? JSON.parse(readFileSync(this.p(id), "utf8")) : null;
+    }
+    catch {
+        return null;
+    } }
+    clear(id) { try {
+        if (existsSync(this.p(id)))
+            rmSync(this.p(id));
+    }
+    catch { } }
+    list() {
+        try {
+            if (!existsSync(this.dir))
+                return [];
+            return readdirSync(this.dir).filter((f) => f.endsWith(".json")).map((f) => { try {
+                return JSON.parse(readFileSync(join(this.dir, f), "utf8"));
+            }
+            catch {
+                return null;
+            } }).filter(Boolean);
+        }
+        catch {
+            return [];
+        }
+    }
+}
 export function createDecidioResume(opts) {
     const registry = new Map();
     const inFlight = new Set();
     const secret = opts.webhookSecret ?? opts.apiToken ?? "";
     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 journal = new ReportJournal(opts.reportDir ?? join(process.env.DECIDIO_PENDING_DIR ?? ".decidio-pending", "reports"));
+    async function reportAfterExecution(pending, decisionId, result) {
+        const base = { status: "executed", decisionId, action: pending.action, result };
+        let reported;
+        let haveReported = false;
+        let buildProblem;
+        try {
+            reported = toCanonical((ctrl.evidence ? ctrl.evidence(result) : result) ?? null, "evidence(result)");
+            haveReported = true;
+        }
+        catch (e) {
+            buildProblem = `${e?.message ?? e}`;
+            reported = null;
+            haveReported = true;
+        }
+        if (haveReported)
+            journal.write({ decisionId, action: pending.action, reported, at: new Date().toISOString() });
+        let confirmRequest;
+        try {
+            confirmRequest = buildResumeConfirmRequest(ctrl, decisionId, reported);
+        }
+        catch {
+            confirmRequest = undefined;
+        }
+        if (!confirmRequest) {
+            await ctrl.store.delete(decisionId).catch(() => { });
+            const diagnostic = `"${pending.action}" EXECUTED, but no execution report could be built (${buildProblem ?? "unknown"}). Nothing will re-run it; record the outcome from your own system.`;
+            console.warn(`[decidio] ${decisionId}: ${diagnostic}`);
+            return { ...base, reportRecorded: false, executionConfirmed: false, diagnostic };
+        }
+        await ctrl.store.delete(decisionId).catch(() => { });
+        let ev;
+        try {
+            ev = await postConfirm(ctrl, decisionId, confirmRequest);
+        }
+        catch (e) {
+            ev = { reportRecorded: false, executionConfirmed: false, diagnostic: `the execution report did not reach Decidio (${e?.message ?? e}). Your action DID run and the report is journalled - re-send it with reconfirm("${decisionId}").` };
+        }
+        if (ev.reportRecorded)
+            journal.clear(decisionId);
+        const diagnostic = buildProblem
+            ? `${ev.diagnostic ? ev.diagnostic + " " : ""}Also: the action's return value was not reportable (${buildProblem}), so an empty response was reported - map it with the \`evidence\` option to earn a confirming tier.`
+            : ev.diagnostic;
+        if (!ev.reportRecorded)
+            console.warn(`[decidio] ${decisionId}: ${diagnostic}`);
+        else if (!ev.executionConfirmed)
+            console.warn(`[decidio] execution evidence for ${decisionId} recorded as ${ev.evidenceTier} - ${diagnostic}`);
+        return { ...base, reportRecorded: ev.reportRecorded, executionConfirmed: ev.executionConfirmed, ...(ev.evidenceTier ? { evidenceTier: ev.evidenceTier } : {}), ...(diagnostic ? { diagnostic } : {}) };
+    }
     const refusalWarned = new Set();
     const refuseOnce = (decisionId, msg) => {
         if (refusalWarned.has(decisionId))
@@ -196,7 +322,7 @@ export function createDecidioResume(opts) {
         },
         async park(p) {
             try {
-                assertJsonSafe(p.args, "args");
+                toCanonical(p.args, "args");
             }
             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);
@@ -257,25 +383,7 @@ export function createDecidioResume(opts) {
                 return { status: "unknown", decisionId };
             try {
                 const result = await fn(...pending.args);
-                let confirmed = true;
-                let tier;
-                try {
-                    tier = await confirm(ctrl, decisionId, result);
-                }
-                catch (e) {
-                    confirmed = false;
-                    console.warn(`[decidio] resume confirm failed (your action DID succeed): ${e.message}`);
-                }
-                const retainedIsSafe = typeof ctrl.store.claim === "function";
-                if (confirmed || !retainedIsSafe)
-                    await ctrl.store.delete(decisionId);
-                if (!confirmed) {
-                    if (retainedIsSafe)
-                        console.warn(`  The parked entry for ${decisionId} is kept as local evidence that it executed — it stays CLAIMED, so it cannot re-run. Retry the confirmation, then delete it.`);
-                    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, confirmed, ...(tier ? { evidenceTier: tier } : {}) });
+                return finish(await reportAfterExecution(pending, decisionId, result));
             }
             catch (e) {
                 if (ctrl.store.release)
@@ -342,6 +450,48 @@ export function createDecidioResume(opts) {
                 }
             };
         },
+        async reconfirm(decisionId) {
+            const entry = journal.read(decisionId);
+            if (!entry) {
+                return {
+                    reportRecorded: false, executionConfirmed: false,
+                    diagnostic: `nothing is journalled for ${decisionId}: either its report was already recorded (nothing to do) or this process never executed it. Check the record in Decidio — do NOT re-run the action to find out.`,
+                };
+            }
+            let request;
+            try {
+                request = buildResumeConfirmRequest(ctrl, decisionId, entry.reported);
+            }
+            catch (e) {
+                return { reportRecorded: false, executionConfirmed: false, diagnostic: `the journalled report for ${decisionId} could not be re-signed (${e?.message ?? e}). The entry is kept; fix the agent's signing config (DECIDIO_AGENT_KEY/DID) and retry.` };
+            }
+            const ev = await postConfirm(ctrl, decisionId, request);
+            if (ev.reportRecorded)
+                journal.clear(decisionId);
+            return ev;
+        },
+        async recover() {
+            const items = [];
+            for (const e of journal.list()) {
+                items.push({
+                    decisionId: e.decisionId, action: e.action, state: "executed_unreported",
+                    guidance: `"${e.action}" executed at ${e.at} and its execution report has not been recorded. Re-send it safely: guard.resume.reconfirm("${e.decisionId}") — this replays the saved report and cannot re-run the action.`,
+                });
+            }
+            const claimed = ctrl.store.listClaimed ? await ctrl.store.listClaimed().catch(() => []) : [];
+            for (const p of claimed) {
+                if (journal.read(p.decisionId))
+                    continue;
+                items.push({
+                    decisionId: p.decisionId, action: p.action, state: "indeterminate",
+                    guidance: `"${p.action}" was CLAIMED for execution but no result was ever recorded: a process died mid-flight, so it is unknown locally whether the action ran. Reconcile in the downstream system (or with an idempotency key) before deciding. The SDK will NOT retry it automatically, and neither should a script.`,
+                });
+            }
+            for (const p of await ctrl.store.list().catch(() => [])) {
+                items.push({ decisionId: p.decisionId, action: p.action, state: "parked", guidance: `"${p.action}" is parked awaiting a human decision. Nothing has executed.` });
+            }
+            return items;
+        },
         worker(workerOpts) {
             const interval = workerOpts?.intervalMs ?? 2_500;
             const deadline = workerOpts?.timeoutMs ? Date.now() + workerOpts.timeoutMs : Infinity;
@@ -364,10 +514,10 @@ export function createDecidioResume(opts) {
                             continue;
                         try {
                             const outcome = await ctrl.resolve({ decisionId: p.decisionId, verdict, reason: st.reason });
-                            if (outcome.status === "executed" && outcome.confirmed)
-                                console.error(`[decidio] resumed ${p.decisionId}: approved → "${p.action}" executed, evidence recorded as ${outcome.evidenceTier ?? "confirmed"}.`);
+                            if (outcome.status === "executed" && outcome.reportRecorded)
+                                console.error(`[decidio] resumed ${p.decisionId}: approved → "${p.action}" executed; evidence recorded as ${outcome.evidenceTier}${outcome.executionConfirmed ? "" : " (execution NOT confirmed — see the warning above)"}.`);
                             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.`);
+                                console.error(`[decidio] resumed ${p.decisionId}: approved → "${p.action}" executed, but its execution report did NOT reach Decidio — recover with: guard.resume.reconfirm("${p.decisionId}")`);
                             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")