@decidio/sdk 0.1.6 → 0.1.7

package/README.md

@@ -51,7 +51,8 @@ Every later command reads `.env` from this directory automatically.
 
 What `.env` contains after a successful init: `DECIDIO_API_URL`, `DECIDIO_AGENT_ID`,
 `DECIDIO_AGENT_DID` + `DECIDIO_AGENT_KEY` (the local keypair — the key is what earns
-`application_confirmed` evidence later), `DECIDIO_API_TOKEN` (the floor-limited agent token),
+`application_confirmed` evidence later), `DECIDIO_API_TOKEN` (the floor-limited agent token —
+90 days by default, `--expires-days N` to change),
 `DECIDIO_WORKSPACE_ID`, and `DECIDIO_WEBHOOK_SECRET` (operator deployments only). Pick any
 agent name — if it's already taken in your workspace, `init` stops cleanly and suggests a
 fresh one (or pass `--unique` to auto-append a random suffix — collision-proof for shared
@@ -122,8 +123,13 @@ implementation as the standalone `@decidio/verify`). The receipt is a W3C Verifi
 Credential: signature and content binding verify with no Decidio account and no network — the
 evidence is yours, not ours. To also prove *who* issued it, pin your workspace's issuer:
 `npx @decidio/sdk verify --issuer <did:key:...> receipt.json` (the DID is shown in your app's
-record verify panel). One receipt proves itself; chain order across receipts is verified when
-you pass several files at once.
+record verify panel — or simply read it off the `receipt` command's output, which prints your
+workspace's issuer DID from the authenticated response so you never have to hunt for it).
+
+One receipt proves itself. Pass several files and their **ordering** is verified too: the first
+file is the anchor and each subsequent receipt must follow it, so verifying any consecutive
+*segment* works — you are told whether the segment starts at your workspace's genesis or
+mid-history, and a set spanning two different issuers is refused outright.
 
 What the credential contains, honestly: the sealed **authority decision** — who decided, what
 was authorized, when, under which policy. It seals at decision time and is immutable — which is
@@ -168,15 +174,36 @@ waiting: it parks its call arguments agent-side (`.decidio-pending/` by default
 stores none of your downstream payload) and throws `DecidioSuspendedError`. The process may
 exit. Two ways the parked action resumes when a human decides:
 
-**The worker (self-serve — start here).** One line in any long-lived process:
+**The worker (self-serve — start here).** No inbound URL, no shared secrets, and it resumes work
+the current process never started. Here is a complete `agent.mjs` you can run:
 
 ```js
 import { guard } from "@decidio/sdk";
-guard.worker();   // polls Decidio outward, re-executes parked actions on approval, exactly once
+
+const payInvoiceRaw = async (invoice) => ({ paid: true, id: invoice.id });
+
+// Declare the action name so the wrapper registers at LOAD time, not on first call —
+// that is what lets a restarted process resume actions approved while it was down.
+const payInvoice = guard.protect(
+  payInvoiceRaw,
+  (invoice) => ({ action: "payInvoice", amount: invoice.amount, scope: "Invoice" }),
+  { action: "payInvoice" },
+);
+
+guard.worker();   // polls Decidio, re-executes parked actions on approval, one execution each
+
+// New work suspends immediately; approvals land later, through the same worker.
+try { await payInvoice({ id: "INV-1", amount: 86_000 }); }
+catch (e) { console.log(e.name); }   // DecidioSuspendedError — expected, not a failure
 ```
 
-No inbound URL, no shared secrets, survives restarts. This is the transport to use against the
-hosted sandbox.
+Run it with `node --env-file=.env agent.mjs`, approve from another terminal, and the running
+worker executes it. Kill the process, restart it, then approve: it still executes, because the
+action was registered at load. **If you can't declare the name at wrap time** (a dynamic
+`describe`), register the raw function explicitly at startup instead —
+`guard.register("payInvoice", payInvoiceRaw)` — before calling `guard.worker()`. Without one of
+those two, a cold worker has an empty registry and reports `no_handler` (the parked action is
+kept, not lost, and the message names the exact fix).
 
 **The signed webhook (operator deployments).** Decidio POSTs a signed verdict to your agent's
 `resumeUrl`; the handler verifies the HMAC signature fail-closed, then re-runs your function:
@@ -198,6 +225,12 @@ your action succeeds but the process dies *before* the entry is cleared, the cla
 (robust crash-recovery of stale claims is on the roadmap), so make your downstream action
 idempotent if you need exactly-once under crashes.
 
+**Parked arguments must be JSON-serializable.** A suspended action is signed and then written to
+disk as JSON, so values that don't survive `JSON.stringify` round-tripping — `Date`, `Map`,
+`undefined`, `NaN`, class instances with custom `toJSON` — come back changed and fail the
+integrity check on resume (a refusal, never a wrong execution). Pass plain data; rehydrate
+inside your function.
+
 **Payload integrity.** When a routed action is parked, the SDK signs its arguments (bound to the
 decision id) with your agent key; on resume it **refuses to execute** if the parked payload was
 modified, its signature stripped, or the file swapped into another decision's slot. That defends
@@ -227,9 +260,9 @@ imports none of them. Each adapter's shipped `.d.ts` header documents its wiring
 `npx @decidio/sdk <cmd>`:
 
 - `quickstart` — the guided two-minute tour (gate → approve → execute → proof)
-- `init [agentId] [--unique]` — sign in, register, mint the agent token, write `.env` (+ `.gitignore` entries)
+- `init [agentId] [--unique] [--force] [--expires-days N]` — sign in, register, mint the agent token, write `.env` (+ `.gitignore` entries). Refuses to overwrite a *different* agent's key in this directory; `--force` backs the old `.env` up first.
 - `doctor` — config, connectivity, and what your current token can do
-- `approvals` / `approvals approve|reject <id> [reason]` — the human side, from your terminal
+- `approvals [--mine] [--json]` / `approvals approve|reject <id> [reason]` — the human side, from your terminal (the list is workspace-wide; `--mine` narrows it to this directory's agent)
 - `receipt <id>` — download a sealed decision's Authority Receipt to a `.json` file
 - `verify [--issuer <did>] <file>...` — verify receipts offline (the canonical verifier; the standalone `@decidio/verify` package is the same implementation, for auditors who want zero Decidio dependency)
 - `dev [--target URL]` — local relay for the resume webhook (operator setups)

package/dist/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync, existsSync, appendFileSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, appendFileSync, chmodSync } from "node:fs";
 import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { createInterface } from "node:readline";
 import { createRequire } from "node:module";
 import { generateKeypair } from "./signing.js";
 import { withApproval } from "./index.js";
-import { verifyReceipt, verifyChain } from "@decidio/verify";
+import { verifyReceipt } from "@decidio/verify";
 const VERSION = (() => {
     try {
         return createRequire(import.meta.url)("../package.json").version;
@@ -66,14 +66,21 @@ async function api(path, init = {}, bearer) {
     }
     return { status: res.status, body };
 }
+function writeSecretFile(path, body) {
+    writeFileSync(path, body, { mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch { }
+}
 function upsertEnv(updates) {
     const cur = readEnvFile();
     const merged = { ...cur, ...updates };
     const body = Object.entries(merged).map(([k, v]) => `${k}=${v}`).join("\n") + "\n";
-    writeFileSync(ENV_PATH, body);
+    writeSecretFile(ENV_PATH, body);
 }
 function ensureGitignore() {
-    const entries = [".env", ".env.quickstart", ".decidio-pending/"];
+    const entries = [".env", ".env.quickstart", ".env.*.bak", ".decidio-pending/"];
     const existing = existsSync(".gitignore") ? readFileSync(".gitignore", "utf8") : "";
     const missing = entries.filter((e) => !existing.split(/\r?\n/).some((l) => l.trim() === e || l.trim() === e.replace(/\/$/, "")));
     if (!missing.length)
@@ -95,13 +102,13 @@ function ask(question, mute = false) {
     });
 }
 async function acquireSession(purpose) {
-    if (process.env.DECIDIO_SESSION_TOKEN)
-        return process.env.DECIDIO_SESSION_TOKEN;
     if (/^http:\/\//i.test(API) && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])([:/]|$)/i.test(API)) {
-        log(`✘ refusing to send sign-in credentials over plaintext http to ${API}.`);
+        log(`✘ refusing to send workspace credentials over plaintext http to ${API}.`);
         log(`  Use https (the hosted sandbox is https://decidio-api.onrender.com) or localhost for local dev.`);
         return null;
     }
+    if (process.env.DECIDIO_SESSION_TOKEN)
+        return process.env.DECIDIO_SESSION_TOKEN;
     if (!process.stdin.isTTY) {
         log(`✘ ${purpose} needs a Decidio workspace sign-in, and this terminal can't prompt for one.`);
         log(`  Fix: set DECIDIO_SESSION_TOKEN and re-run. To mint one:`);
@@ -138,10 +145,20 @@ async function acquireSession(purpose) {
     log(`  Sign-in links are single-use and expire in 15 minutes — request a fresh one and re-run.`);
     return null;
 }
-async function cmdInit(agentId) {
+async function cmdInit(agentId, opts = {}) {
     log(`Registering agent "${agentId}" with Decidio at ${API}…`);
-    const existingKey = readEnvFile().DECIDIO_AGENT_KEY;
-    const sourceSystem = process.env.DECIDIO_SOURCE_SYSTEM || readEnvFile().DECIDIO_SOURCE_SYSTEM;
+    const existingEnv = readEnvFile();
+    const existingKey = existingEnv.DECIDIO_AGENT_KEY;
+    const sourceSystem = process.env.DECIDIO_SOURCE_SYSTEM || existingEnv.DECIDIO_SOURCE_SYSTEM;
+    if (existingKey && existingEnv.DECIDIO_AGENT_ID && existingEnv.DECIDIO_AGENT_ID !== agentId && !opts.force) {
+        log(`✘ this directory's .env already holds the key for a DIFFERENT agent ("${existingEnv.DECIDIO_AGENT_ID}").`);
+        log(`  Registering "${agentId}" here would overwrite that key — and a private key that is`);
+        log(`  overwritten is gone for good (it never left this machine). Nothing was written.`);
+        log(`  Pick one:`);
+        log(`    1. New directory (cleanest): mkdir ${agentId} && cd ${agentId} && npx @decidio/sdk init ${agentId}`);
+        log(`    2. Replace the old agent here, backing its .env up first: npx @decidio/sdk init ${agentId} --force`);
+        return 1;
+    }
     const { did: localDid, privateKeyBase64: localKey } = generateKeypair();
     const registerBody = JSON.stringify({ agentId, did: localDid, ...(sourceSystem ? { sourceSystem } : {}) });
     let session = null;
@@ -183,11 +200,12 @@ async function cmdInit(agentId) {
     let agentToken, workspaceId;
     const mintBearer = session ?? TOKEN();
     if (mintBearer) {
-        const mint = await api("/api/workspace/agent-token", { method: "POST", body: JSON.stringify({ agentId, label: "sdk-cli" }) }, mintBearer);
+        const expiresInDays = opts.expiresDays ?? 90;
+        const mint = await api("/api/workspace/agent-token", { method: "POST", body: JSON.stringify({ agentId, label: "sdk-cli", expiresInDays }) }, mintBearer);
         if (mint.status >= 200 && mint.status < 300 && mint.body?.token) {
             agentToken = mint.body.token;
             workspaceId = mint.body.workspaceId;
-            log(`✔ minted the agent's API token — floor-limited: it can request approvals and nothing else${mint.body.expiresAt ? ` (expires ${mint.body.expiresAt})` : ""}`);
+            log(`✔ minted the agent's API token — floor-limited: it can request authorization, poll status and report confirmation; it cannot administer the workspace or approve anything${mint.body.expiresAt ? ` (expires ${mint.body.expiresAt})` : ` (${expiresInDays} days)`}`);
         }
         else if (session) {
             log(`✘ could not mint the agent's API token (${mint.status}): ${JSON.stringify(mint.body)}`);
@@ -210,11 +228,16 @@ async function cmdInit(agentId) {
         envOut.DECIDIO_API_TOKEN = agentToken;
     if (workspaceId)
         envOut.DECIDIO_WORKSPACE_ID = workspaceId;
+    ensureGitignore();
+    if (opts.force && existingKey && existingEnv.DECIDIO_AGENT_ID && existingEnv.DECIDIO_AGENT_ID !== agentId) {
+        const backup = `.env.${existingEnv.DECIDIO_AGENT_ID.replace(/[^\w.-]/g, "_")}.bak`;
+        writeSecretFile(backup, readFileSync(ENV_PATH, "utf8"));
+        log(`✔ backed the previous agent's .env up to ${backup} (its key would otherwise be unrecoverable)`);
+    }
     upsertEnv(envOut);
     for (const [k, v] of Object.entries(envOut))
         process.env[k] = v;
-    log(`✔ wrote ${ENV_PATH} — every decidio command reads it from this directory (your script loads it with node --env-file=.env)`);
-    ensureGitignore();
+    log(`✔ wrote ${ENV_PATH} (owner-only where the OS supports it) — every decidio command reads it from this directory (your script loads it with node --env-file=.env)`);
     if (privateKey)
         log(`  (the agent's private signing key is in there — for production, move it to your secret manager)`);
     log("");
@@ -258,6 +281,22 @@ async function cmdDoctor() {
         log("⚠ signing key: MISSING (DECIDIO_AGENT_KEY/DID) — the agent can't prove identity, so EVERY request routes to a human. Run `npx @decidio/sdk init` to generate one.");
     const h = await api("/api/health", {}, "");
     line(h.status >= 200 && h.status < 300, `connectivity: API reachable (${h.status})`);
+    const tok = process.env.DECIDIO_API_TOKEN || env.DECIDIO_API_TOKEN;
+    if (tok) {
+        try {
+            const payload = JSON.parse(Buffer.from(tok.split(".")[1] ?? "", "base64url").toString("utf8"));
+            if (typeof payload?.exp === "number") {
+                const days = Math.floor((payload.exp * 1000 - Date.now()) / 86_400_000);
+                if (days < 0)
+                    line(false, `agent token: EXPIRED ${-days} day(s) ago — re-run \`npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}\` to mint a fresh one.`);
+                else if (days <= 14)
+                    log(`⚠ agent token: expires in ${days} day(s) — mint a fresh one before it does: npx @decidio/sdk init ${env.DECIDIO_AGENT_ID ?? "<agent>"}`);
+                else
+                    log(`✔ agent token: valid for another ${days} days`);
+            }
+        }
+        catch { }
+    }
     const rec = await api("/api/records");
     if (rec.status >= 200 && rec.status < 300)
         log("✔ token scope: session/admin (init, approvals and receipt work from this env)");
@@ -275,9 +314,10 @@ async function cmdDoctor() {
     log(ok ? "\ndoctor: all green." : "\ndoctor: fix the ✘ items above, then re-run `npx @decidio/sdk doctor`.");
     return ok ? 0 : 1;
 }
-async function cmdApprovals(sub, id, reason) {
-    const jsonMode = sub === "--json";
-    if (jsonMode)
+async function cmdApprovals(sub, id, reason, flags = {}) {
+    const jsonMode = !!flags.json;
+    const mineOnly = !!flags.mine;
+    if (sub?.startsWith("--"))
         sub = undefined;
     let bearer;
     const probe = await api("/api/decisions/cards");
@@ -331,11 +371,16 @@ async function cmdApprovals(sub, id, reason) {
         return 0;
     }
     const myAgent = process.env.DECIDIO_AGENT_ID;
-    log(`Pending agent approvals (${pending.length})${myAgent ? ` — workspace-wide; "←" marks this directory's agent (${myAgent})` : ""}:`);
-    for (const c of pending) {
+    const isMine = (c) => !!myAgent && typeof c.title === "string" && c.title.startsWith(`${myAgent}:`);
+    const shown = mineOnly ? pending.filter(isMine) : pending;
+    if (mineOnly && !shown.length) {
+        log(`No pending approvals for "${myAgent}" (${pending.length} pending elsewhere in this workspace — drop --mine to see them).`);
+        return 0;
+    }
+    log(`Pending agent approvals (${shown.length}${mineOnly ? ` for "${myAgent}"` : ""})${!mineOnly && myAgent ? ` — workspace-wide; "←" marks this directory's agent (${myAgent}). Use --mine to list only those.` : ""}:`);
+    for (const c of shown) {
         const ar = c.agentRequest ?? {};
-        const mine = myAgent && typeof c.title === "string" && c.title.startsWith(`${myAgent}:`);
-        log(`  ${c.id}  ${ar.action ?? "?"}${ar.amount != null ? `  $${Number(ar.amount).toLocaleString()}` : ""}  — ${c.title ?? ""}${mine ? "  ←" : ""}`);
+        log(`  ${c.id}  ${ar.action ?? "?"}${ar.amount != null ? `  $${Number(ar.amount).toLocaleString()}` : ""}  — ${c.title ?? ""}${!mineOnly && isMine(c) ? "  ←" : ""}`);
     }
     log(`\nApprove:  npx @decidio/sdk approvals approve <id> [reason]`);
     log(`Reject:   npx @decidio/sdk approvals reject <id> [reason]`);
@@ -381,16 +426,24 @@ async function cmdReceipt(id, jsonMode = false) {
     }
     const detail = await api(`/api/records/${encodeURIComponent(id)}`, {}, bearer);
     const conf = detail.body?.record?.confirmation;
+    const issuer = r.body?.issuer;
     if (jsonMode) {
-        log(JSON.stringify({ file: name, decisionId: id, evidenceTier: conf?.status ?? null, confirmed: !!conf?.confirmed }, null, 2));
+        log(JSON.stringify({ file: name, decisionId: id, evidenceTier: conf?.status ?? null, confirmed: !!conf?.confirmed, issuer: issuer ?? null }, null, 2));
         return 0;
     }
     if (conf?.status)
         log(`  Sealed credential: the authority decision (its confirmation field reads "pending" forever — immutable). Current record evidence tier: ${conf.status}${conf.confirmed ? " (confirmed)" : ""}.`);
     log(`  Verify it offline — no Decidio account or network needed (the verifier is built in):`);
     log(`    npx @decidio/sdk verify ${name}`);
-    log(`  To also prove WHO issued it, pin your workspace's issuer DID (shown in your app's record verify panel):`);
-    log(`    npx @decidio/sdk verify --issuer <did:key:...> ${name}`);
+    if (issuer) {
+        log(`  Your workspace's issuer DID (from the authenticated response — record it once, then pin it forever):`);
+        log(`    ${issuer}`);
+        log(`    npx @decidio/sdk verify --issuer ${issuer} ${name}`);
+    }
+    else {
+        log(`  To also prove WHO issued it, pin your workspace's issuer DID (shown in your app's record verify panel):`);
+        log(`    npx @decidio/sdk verify --issuer <did:key:...> ${name}`);
+    }
     return 0;
 }
 function parseReceiptStrict(text, file) {
@@ -440,6 +493,27 @@ function parseReceiptStrict(text, file) {
     }
     return value;
 }
+function chainOf(vcs, expectedIssuer) {
+    if (!vcs.length)
+        return { valid: false, length: 0, reason: "no receipts supplied" };
+    const issuers = [...new Set(vcs.map((v) => String(v?.issuer ?? "")))];
+    if (issuers.length > 1)
+        return { valid: false, length: 0, reason: `these receipts come from ${issuers.length} DIFFERENT issuers — a chain must be issued end to end by one issuer` };
+    let prev = null;
+    let anchor = "segment";
+    for (let i = 0; i < vcs.length; i++) {
+        const r = verifyReceipt(vcs[i], expectedIssuer);
+        if (!r.valid)
+            return { valid: false, length: i, reason: `receipt ${i} (${r.recordId ?? "?"}) invalid: ${r.reason}` };
+        const cs = vcs[i]?.credentialSubject ?? {};
+        if (i === 0)
+            anchor = (cs.prevHash ?? null) === null ? "genesis" : "segment";
+        else if ((cs.prevHash ?? null) !== prev)
+            return { valid: false, length: i, reason: `receipt ${i} does not follow receipt ${i - 1} (prevHash mismatch)` };
+        prev = cs.contentHash;
+    }
+    return { valid: true, length: vcs.length, anchor };
+}
 function cmdVerify(argsIn) {
     const issIdx = argsIn.indexOf("--issuer");
     if (issIdx >= 0 && (argsIn[issIdx + 1] === undefined || argsIn[issIdx + 1].startsWith("--"))) {
@@ -470,9 +544,9 @@ function cmdVerify(argsIn) {
         log(`    content-bound: ${res.contentBound}${res.reason ? `   reason: ${res.reason}` : ""}`);
     });
     if (vcs.length > 1) {
-        const c = verifyChain(vcs, expectedIssuer);
+        const c = chainOf(vcs, expectedIssuer);
         allOk = allOk && c.valid;
-        log(`\nchain: ${c.valid ? "✔ intact" : "✘ broken"} (${c.length}/${vcs.length})${c.reason ? ` — ${c.reason}` : ""}`);
+        log(`\nchain: ${c.valid ? "✔ intact" : "✘ broken"} (${c.length}/${vcs.length})${c.valid ? (c.anchor === "segment" ? " — segment: ordering proven from the FIRST file forward; history before it is not covered by these receipts" : " — from genesis") : ""}${c.reason ? ` — ${c.reason}` : ""}`);
     }
     return allOk ? 0 : 1;
 }
@@ -492,7 +566,7 @@ async function cmdQuickstart() {
         log(`✘ registration failed (${reg.status}): ${JSON.stringify(reg.body)}`);
         return 1;
     }
-    const mint = await api("/api/workspace/agent-token", { method: "POST", body: JSON.stringify({ agentId, label: "quickstart" }) }, session);
+    const mint = await api("/api/workspace/agent-token", { method: "POST", body: JSON.stringify({ agentId, label: "quickstart", expiresInDays: 7 }) }, session);
     if (!(mint.status >= 200 && mint.status < 300) || !mint.body?.token) {
         log(`✘ token mint failed (${mint.status}): ${JSON.stringify(mint.body)}`);
         return 1;
@@ -570,8 +644,11 @@ async function cmdQuickstart() {
     }
     const fname = `decidio-receipt-${decisionId.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
     writeFileSync(fname, JSON.stringify(rec.body.credential, null, 2) + "\n");
-    const v = verifyReceipt(rec.body.credential, undefined);
-    log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline; issuer UNPINNED — bind it with: npx @decidio/sdk verify --issuer <your workspace DID>)`);
+    const issuer = rec.body?.issuer;
+    const v = verifyReceipt(rec.body.credential, issuer);
+    log(`  ${v.valid ? "✔ VALID" : "✘ INVALID"} — ${fname} (signature + content binding, offline${issuer ? `, PINNED to your workspace issuer ${issuer}` : "; issuer unpinned"})`);
+    if (issuer)
+        log(`    Keep that DID: it is your trust anchor — npx @decidio/sdk verify --issuer ${issuer} <receipt.json>`);
     const detail = await api(`/api/records/${encodeURIComponent(decisionId)}`, {}, session);
     const tier = detail.body?.record?.confirmation?.status;
     if (tier)
@@ -625,9 +702,12 @@ const USAGE = `decidio — the Decidio SDK command line
 
   npx @decidio/sdk quickstart          the guided two-minute tour: gate → approve → execute → proof
   npx @decidio/sdk init [agentId]      sign in, register the agent, mint its API token, write .env
-                                       (--unique appends a random suffix — collision-proof samples)
+                                       --unique  append a random suffix (collision-proof samples)
+                                       --force   replace a different agent already in this .env
+                                                 (its .env is backed up first)
+                                       --expires-days N   agent-token lifetime (default 90)
   npx @decidio/sdk doctor              check config, connectivity, and what your token can do
-  npx @decidio/sdk approvals [--json]  list pending agent approvals
+  npx @decidio/sdk approvals [--json] [--mine]   list pending agent approvals
   npx @decidio/sdk approvals approve <id> [reason]
   npx @decidio/sdk approvals reject <id> [reason]
   npx @decidio/sdk receipt <id>        download a sealed decision's Authority Receipt (.json)
@@ -657,14 +737,24 @@ async function main(argv) {
         case "init": {
             const argsIn = argv.slice(3);
             const unique = argsIn.includes("--unique");
-            const nameArg = argsIn.find((x) => !x.startsWith("-"));
+            const expIdx = argsIn.indexOf("--expires-days");
+            const expRaw = expIdx >= 0 ? argsIn[expIdx + 1] : undefined;
+            if (expIdx >= 0 && (!expRaw || !/^\d+$/.test(expRaw) || Number(expRaw) < 1)) {
+                log("✘ --expires-days needs a positive whole number of days (e.g. --expires-days 30).");
+                return 2;
+            }
+            const nameArg = argsIn.find((x, i) => !x.startsWith("-") && !(expIdx >= 0 && i === expIdx + 1));
             let name = nameArg ?? process.env.DECIDIO_AGENT_ID ?? "my-agent";
             if (unique)
                 name = `${name}-${randomBytes(2).toString("hex")}`;
-            return cmdInit(name);
+            return cmdInit(name, { force: argsIn.includes("--force"), expiresDays: expRaw ? Number(expRaw) : undefined });
         }
         case "doctor": return cmdDoctor();
-        case "approvals": return cmdApprovals(a, b, rest.join(" ") || undefined);
+        case "approvals": {
+            const argsIn = argv.slice(3);
+            const positional = argsIn.filter((x) => !x.startsWith("-"));
+            return cmdApprovals(positional[0], positional[1], positional.slice(2).join(" ") || undefined, { json: argsIn.includes("--json"), mine: argsIn.includes("--mine") });
+        }
         case "receipt": {
             const argsIn = argv.slice(3);
             return cmdReceipt(argsIn.find((x) => !x.startsWith("-")), argsIn.includes("--json"));

package/dist/guard.d.ts

@@ -17,12 +17,14 @@ export interface GuardFacadeConfig {
 export interface ProtectOptions {
     adapter?: "generic" | "langgraph" | "openai" | "temporal" | "inngest" | "mcp";
     mode?: "durable" | "blocking";
+    action?: string;
 }
 export declare class Guard {
     config: GuardFacadeConfig;
     resume?: ResumeController;
     constructor(config: GuardFacadeConfig, resume?: ResumeController);
     static fromEnv(): Guard;
+    register(action: string, fn: (...a: any[]) => Promise<any>): void;
     resumeHandler(): import("http").RequestListener;
     resumeFetchHandler(): (req: Request) => Promise<Response>;
     worker(opts?: {

package/dist/guard.js

@@ -22,6 +22,7 @@ export class Guard {
             appUrl: process.env.DECIDIO_APP_URL,
         });
     }
+    register(action, fn) { this.ensureResume().register(action, fn); }
     resumeHandler() { return this.ensureResume().webhookHandler(); }
     resumeFetchHandler() { return this.ensureResume().fetchHandler(); }
     worker(opts) {
@@ -53,7 +54,10 @@ export class Guard {
                 "Omit mode:\"blocking\" for durable async resume on real (minutes-to-days) approvals.");
             return withApproval(fn, describe, base);
         }
-        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume: this.ensureResume() });
+        const resume = this.ensureResume();
+        if (opts?.action)
+            resume.register(opts.action, fn);
+        return withApproval(fn, describe, { ...base, resumeUrl: c.resumeUrl, resume });
     }
 }
 export const guard = Guard.fromEnv();

package/dist/resume.js

@@ -57,7 +57,7 @@ export class FilePendingStore {
     key(id) { return id.replace(/[^\w.-]/g, "_"); }
     path(id) { return join(this.dir, `${this.key(id)}.json`); }
     claimedPath(id) { return join(this.dir, `${this.key(id)}.claimed`); }
-    async put(p) { writeFileSync(this.path(p.decisionId), JSON.stringify(p, null, 2)); }
+    async put(p) { writeFileSync(this.path(p.decisionId), JSON.stringify(p, null, 2), { mode: 0o600 }); }
     async get(id) {
         for (const f of [this.path(id), this.claimedPath(id)])
             if (existsSync(f))
@@ -70,8 +70,16 @@ export class FilePendingStore {
     async list() {
         if (!existsSync(this.dir))
             return [];
-        return readdirSync(this.dir).filter((f) => f.endsWith(".json"))
-            .map((f) => JSON.parse(readFileSync(join(this.dir, f), "utf8")));
+        const out = [];
+        for (const f of readdirSync(this.dir).filter((f) => f.endsWith(".json"))) {
+            try {
+                out.push(JSON.parse(readFileSync(join(this.dir, f), "utf8")));
+            }
+            catch (e) {
+                console.error(`[decidio] skipping unreadable parked entry ${f} (${e.message}) — the other parked actions still resume; inspect or delete this file.`);
+            }
+        }
+        return out;
     }
     async claim(id) {
         try {
@@ -143,7 +151,12 @@ export function createDecidioResume(opts) {
         workspaceId: opts.workspaceId ?? process.env.DECIDIO_WORKSPACE_ID,
         webhookSecret: secret,
         store: opts.store,
-        register(action, fn) { registry.set(action, fn); },
+        register(action, fn) {
+            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) {
             const argsSig = signArgs(p, ctrl.agentKey, ctrl.webhookSecret);
             if (!argsSig)
@@ -187,19 +200,36 @@ export function createDecidioResume(opts) {
             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)
-                return finish({ status: "no_handler", decisionId, action: pending.action, reason: `no fn registered for action "${pending.action}" — call resume.register(...) at startup` });
+            if (!fn) {
+                console.error(`[decidio] cannot resume ${decisionId}: no function is registered for action "${pending.action}" in THIS process.`);
+                console.error(`  A worker only re-executes actions registered where it runs. At startup, either declare the action on the wrapper:`);
+                console.error(`      const doIt = guard.protect(doItRaw, describe, { action: "${pending.action}" });`);
+                console.error(`  or register the raw function directly:`);
+                console.error(`      guard.register("${pending.action}", doItRaw);`);
+                console.error(`  then start the worker. The approved action stays parked until then — nothing is lost.`);
+                return finish({ status: "no_handler", decisionId, action: pending.action, reason: `no fn registered for action "${pending.action}" in this process — declare { action } on protect(), or call guard.register("${pending.action}", fn) at startup` });
+            }
             const claimed = ctrl.store.claim ? await ctrl.store.claim(decisionId) : (!inFlight.has(decisionId) && (inFlight.add(decisionId), true));
             if (!claimed)
                 return { status: "unknown", decisionId };
             try {
                 const result = await fn(...pending.args);
-                await ctrl.store.delete(decisionId);
+                let confirmed = true;
                 try {
                     await confirm(ctrl, decisionId, result);
                 }
                 catch (e) {
-                    console.warn(`[decidio] resume confirm failed (action succeeded): ${e.message}`);
+                    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 });
             }

package/openapi.yaml

@@ -5,7 +5,7 @@
 openapi: 3.1.0
 info:
   title: Decidio Agent Gate
-  version: 0.1.6
+  version: 0.1.7
   description: >
     Authorize an AI-agent action (proceed | route | block), confirm the captured outcome, and
     receive the signed resume webhook when a routed action is decided. Every outcome seals a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decidio/sdk",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "One-line approval gate for AI-agent actions. Wrap a risky tool call with guard.protect(); Decidio's policy engine decides proceed | route | block, a human approves routed actions, and every outcome is sealed as a verifiable Authority Receipt.",
   "license": "Apache-2.0",
   "type": "module",