@decidio/sdk 0.1.9 → 0.1.11

package/dist/resume.js

@@ -1,28 +1,13 @@
-// @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, 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");
+import { userInfo } from "node:os";
+import { execFileSync } from "node:child_process";
+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) {
@@ -30,7 +15,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 { /* fall through to hmac */ }
+        catch { }
     }
     if (webhookSecret)
         return { kind: "hmac", sig: createHmac("sha256", webhookSecret).update(bytes).digest("hex") };
@@ -67,17 +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.`);
+    }
 }
-/** 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) {
         this.dir = dir;
         mkdirSync(dir, { recursive: true });
+        hardenDir(dir);
     }
     key(id) { return id.replace(/[^\w.-]/g, "_"); }
     path(id) { return join(this.dir, `${this.key(id)}.json`); }
@@ -95,12 +95,8 @@ 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"))) { // .claimed excluded — in flight
+        for (const f of readdirSync(this.dir).filter((f) => f.endsWith(".json"))) {
             try {
                 out.push(JSON.parse(readFileSync(join(this.dir, f), "utf8")));
             }
@@ -114,7 +110,7 @@ export class FilePendingStore {
         try {
             renameSync(this.path(id), this.claimedPath(id));
             return true;
-        } // atomic; fails if already claimed/gone
+        }
         catch {
             return false;
         }
@@ -123,13 +119,23 @@ export class FilePendingStore {
         try {
             renameSync(this.claimedPath(id), this.path(id));
         }
-        catch { /* already released/gone */ }
+        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;
     }
 }
-/** 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;
@@ -144,8 +150,6 @@ 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;
@@ -153,11 +157,6 @@ 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`);
@@ -167,55 +166,139 @@ export function assertConfirmRecorded(body, decisionId, signed) {
     }
     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.
+function buildResumeConfirmRequest(cfg, decisionId, canonicalResult) {
     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.`);
+        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;
+    assertSafeTransport(cfg.apiUrl, !!cfg.apiToken);
     const r = await f(cfg.apiUrl.replace(/\/$/, "") + "/agent/status/" + encodeURIComponent(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();
 }
-/**
- * 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()
- */
+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(); // concurrent-duplicate guard (same process)
+    const inFlight = new Set();
     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 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))
@@ -225,29 +308,25 @@ export function createDecidioResume(opts) {
     };
     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, // D-B3.6: tenant-bind the cold-resume confirm proof
+        workspaceId: opts.workspaceId ?? process.env.DECIDIO_WORKSPACE_ID,
         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");
+            try {
+                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);
+            }
             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.`);
@@ -258,7 +337,7 @@ export function createDecidioResume(opts) {
                 opts.onResolved?.(o); return o; };
             const pending = await ctrl.store.get(decisionId);
             if (!pending)
-                return { status: "unknown", decisionId }; // not ours / already resumed
+                return { status: "unknown", decisionId };
             if (verdict === "rejected") {
                 await ctrl.store.delete(decisionId);
                 return finish({ status: "rejected", decisionId, action: pending.action, reason });
@@ -267,24 +346,12 @@ 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) {
                 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") {
@@ -296,9 +363,6 @@ export function createDecidioResume(opts) {
                 return finish({ status: "no_handler", decisionId, action: pending.action, reason: "parked payload unverifiable" });
             }
             if (integrity === "unbound" && strictBinding) {
-                // 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)" });
             }
@@ -306,8 +370,6 @@ export function createDecidioResume(opts) {
                 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}" });`);
@@ -316,44 +378,12 @@ 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 }; // another worker owns it
+                return { status: "unknown", decisionId };
             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 {
-                    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);
-                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)
@@ -374,9 +404,6 @@ 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;
@@ -423,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;
@@ -443,18 +512,12 @@ 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"}.`);
+                            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")

package/dist/signing.d.ts

@@ -3,6 +3,10 @@ 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). */
+/** Derive the public did:key from a stored private key. Lets `doctor` prove that the key on
+ *  this machine is actually the one registered for this agent — a mismatched restore otherwise
+ *  looks healthy until a signed confirmation quietly fails to earn its tier weeks later. */
+export declare function didFromPrivateKey(privateKeyBase64: string): string;
 export declare function generateKeypair(): {
     did: string;
     privateKeyBase64: string;
@@ -46,11 +50,73 @@ 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
+/** Refuse values that do not survive `JSON.stringify → JSON.parse` with their meaning intact,
+ *  BEFORE anything is routed, signed, or parked. `NaN` canonicalizes to `null` and a `Map` to
+ *  `{}` — an integrity signature over those bytes would verify while the function executed
+ *  arguments that meant something else, so the gate refuses them instead. Throws naming the
+ *  offending path. The supported data model is plain JSON: null, boolean, string, finite
  *  number, plain array, plain object. */
+/** Typed refusal for values that cannot survive JSON with their meaning intact. `decisionId`
+ *  is set only when a decision already exists (defense-in-depth refusals after routing). */
+export declare class DecidioUnsafeArgumentsError extends Error {
+    decisionId?: string | undefined;
+    constructor(message: string, decisionId?: string | undefined);
+}
 export declare function assertJsonSafe(value: unknown, path?: string): void;
+/** The wire rule: a credentialed request must never ride plaintext http to a remote host — the
+ *  rule is about the WIRE, not which credential (the interactive sign-in enforced this for
+ *  session tokens while agent-token requests sailed through). localhost/127.0.0.1/[::1] stay
+ *  allowed for local dev; https always allowed. Throws before anything is sent. */
+export declare function assertSafeTransport(url: string, hasCredential: boolean): void;
+/** 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,
+ *  the workspace, the agent's did, the source, the response digest, the digest algorithm, the
+ *  canonicalization version, a nonce and an expiry are ALL inside the signed bytes.
+ *
+ *  HONEST SCOPE — say this out loud rather than let a reader assume more: this proves integrity
+ *  and agent attribution of the REPORT. It does not prove the downstream system committed
+ *  anything; only the source system can attest that, and the gate's evidence tier is what
+ *  records how strong that attestation is. */
+export interface ExecutionReport {
+    v: 1;
+    purpose: "decidio.execution-report";
+    decisionId: string;
+    agentId: string;
+    did: string;
+    workspaceId?: string;
+    source: string;
+    resultDigest: string;
+    digestAlg: "sha-256";
+    canonicalization: "decidio-jcs-1";
+    nonce: string;
+    exp: number;
+    proof: {
+        protected: string;
+        signature: string;
+    };
+}
+export declare function signExecutionReport(privateKeyBase64: string, fields: {
+    decisionId: string;
+    agentId: string;
+    did: string;
+    workspaceId?: string;
+    source: string;
+    resultDigest: string;
+    ttlMs?: number;
+    now?: number;
+    nonce?: string;
+}): ExecutionReport;
+/** Verify an ExecutionReport LOCALLY — same rules the server applies before persisting it.
+ *  Returns why it failed rather than a bare false, so a caller can say something useful. */
+export declare function verifyExecutionReport(report: unknown, expect: {
+    decisionId: string;
+    did?: string;
+    now?: number;
+}): {
+    valid: boolean;
+    reason?: string;
+};
+/** sha-256 over the canonical JSON of an already-canonical value — the digest an ExecutionReport
+ *  binds. Both languages produce identical bytes for identical values. */
+export declare function resultDigest(canonicalValue: unknown): string;