@decidio/sdk 0.1.5 → 0.1.7

package/dist/cli.js

@@ -1,31 +1,12 @@
 #!/usr/bin/env node
-// @decidio/sdk CLI — the on-ramp. Run via `npx @decidio/sdk <cmd>` (or tsx in-repo).
-//   init [agentId]   sign in, register the agent, mint its API token, write .env
-//   doctor           check config + connectivity + durability readiness
-//   approvals        list pending agent approvals; `approvals approve|reject <id> [reason]`
-//   receipt <id>     download a sealed decision's Authority Receipt to a .json file
-//   dev [--target U] signal-only relay: forwards Decidio's webhook to your local agent URL
-//
-// TWO TOKEN KINDS, deliberately (self-serve design 2026-08-28): commands that ADMINISTER a
-// workspace (init's register+mint, approvals, receipt) need the owner's SESSION token — acquired
-// interactively per run or from DECIDIO_SESSION_TOKEN, held in memory, NEVER written to disk.
-// What lands in .env as DECIDIO_API_TOKEN is the floor-limited AGENT token the runtime SDK
-// needs (it can call /agent/* and nothing else). A session-capable secret must never live in
-// an agent host's .env — that was the pre-publish design's hole.
-//
-// MESSAGE DISCIPLINE (founder bar 2026-08-29, from the Codex acceptance run): every failure
-// tells the developer WHAT happened, WHY, and the EXACT next command. Every success says what
-// changed, where, and what to do next. No stack traces for expected failures; no green ✔ for a
-// no-op (the replay-approve bug: the server's idempotent alreadyResolved was reported as a
-// fresh success — an authority CLI may never dress a no-op as an action).
-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;
@@ -34,8 +15,6 @@ const VERSION = (() => {
         return "unknown";
     }
 })();
-// ---- environment: load the CWD .env FIRST (Codex finding: init writes .env, but the next
-// command ignored it and pointed at localhost). Process env always wins — .env only fills gaps.
 function readEnvFile() {
     const out = {};
     if (existsSync(".env"))
@@ -47,9 +26,6 @@ function readEnvFile() {
     return out;
 }
 for (const [k, v] of Object.entries(readEnvFile())) {
-    // NEVER autoload the session token from disk: the whole design splits session (memory-only)
-    // from the floor-limited agent token (.env). Silently honoring a parked session token would
-    // reward exactly the credential-at-rest the split exists to prevent (guard catch 2026-08-29).
     if (k === "DECIDIO_SESSION_TOKEN") {
         console.log("⚠ ignoring DECIDIO_SESSION_TOKEN found in .env — session tokens belong in your shell or CI secret store, never on disk. Remove that line; export it in the shell instead.");
         continue;
@@ -57,17 +33,11 @@ for (const [k, v] of Object.entries(readEnvFile())) {
     if (process.env[k] === undefined)
         process.env[k] = v;
 }
-// `quickstart` is the zero-config guided tour: with no DECIDIO_API_URL anywhere it targets the
-// hosted sandbox (and says so); every other command keeps the localhost dev default.
 const IS_QUICKSTART = process.argv[2] === "quickstart";
 const API = (process.env.DECIDIO_API_URL ?? (IS_QUICKSTART ? "https://decidio-api.onrender.com" : "http://localhost:4000")).replace(/\/$/, "");
-// Token is read AT CALL TIME, not captured at import: init mints a fresh agent token mid-run and
-// its closing doctor must probe with THAT, not the pre-init env (round-3 Codex catch — the stale
-// capture made init's own doctor print "token: REJECTED" seconds after a successful mint).
 const TOKEN = () => process.env.DECIDIO_API_TOKEN;
 const ENV_PATH = ".env";
 const log = (...a) => console.log(...a);
-/** Fetch wrapper that turns transport failures into guidance instead of a stack trace. */
 async function api(path, init = {}, bearer) {
     const auth = bearer ?? TOKEN();
     let res;
@@ -96,16 +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);
 }
-/** Keep secrets out of git without nagging: append the two entries to .gitignore when they're
- *  not already covered. Creating the file in a non-git directory is harmless. */
 function ensureGitignore() {
-    const entries = [".env", ".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)
@@ -113,12 +88,10 @@ function ensureGitignore() {
     appendFileSync(".gitignore", (existing && !existing.endsWith("\n") ? "\n" : "") + missing.join("\n") + "\n");
     log(`✔ added ${missing.join(" + ")} to .gitignore (your agent key and parked actions stay out of git)`);
 }
-// ---- interactive input (session sign-in) ---------------------------------------------------
 function ask(question, mute = false) {
     return new Promise((resolve) => {
         const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
         if (mute) {
-            // Hide password echo: after the prompt renders, swallow subsequent output writes.
             const anyRl = rl;
             const write = anyRl._writeToOutput?.bind(rl);
             anyRl._writeToOutput = (s) => { if (s.includes(question))
@@ -128,19 +101,14 @@ function ask(question, mute = false) {
             process.stdout.write("\n"); resolve(answer.trim()); });
     });
 }
-/** Owner SESSION token, memory-only. Sources in order: DECIDIO_SESSION_TOKEN env, interactive
- *  email+password (`/demo/login`), pasted sign-in link (`/demo/login-consume` — for the
- *  password-less accounts the welcome flow creates). Never persisted. */
 async function acquireSession(purpose) {
-    if (process.env.DECIDIO_SESSION_TOKEN)
-        return process.env.DECIDIO_SESSION_TOKEN;
-    // Same rule the server applies to resume URLs: credentials never ride plaintext http to a
-    // non-loopback host. Refuse before prompting, not after collecting a password.
     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:`);
@@ -177,16 +145,22 @@ 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}…`);
-    // CLIENT-SIDE KEYGEN: generate the Ed25519 keypair LOCALLY and register only the PUBLIC
-    // did:key. The private key NEVER crosses the wire — it goes straight to this host's env.
-    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 } : {}) });
-    // First try whatever bearer the env already carries (the local-dev / operator path — a static
-    // admin token, or dev-open auth). On 401/403 fall through to the self-serve session flow.
     let session = null;
     let r = await api("/api/agents/register", { method: "POST", body: registerBody });
     if (r.status === 401 || r.status === 403) {
@@ -197,10 +171,6 @@ async function cmdInit(agentId) {
     }
     let did, privateKey;
     if (r.status === 409) {
-        // Already registered to a server-held did. WITHOUT the original private key on this machine
-        // this is a HARD STOP, not a degraded continue (round-3 Codex catch: init used to write a
-        // keyless .env and print happy-path next steps — every request then routed unproven and
-        // execution evidence silently capped at agent_asserted).
         did = r.body?.did;
         if (existingKey) {
             log(`• "${agentId}" is already registered in this workspace (did ${did}) — reusing it with the DECIDIO_AGENT_KEY already in .env.`);
@@ -227,18 +197,15 @@ async function cmdInit(agentId) {
         log(`  Fix the cause above and re-run — init is safe to repeat.`);
         return 1;
     }
-    // Mint the runtime credential: the floor-limited AGENT token (can call /agent/* only). This is
-    // what .env gets — the session token stays in memory and dies with this process. On boxes
-    // without the tester-lab fence (plain local dev) the mint endpoint refuses; that's fine —
-    // local dev auths with its existing env and we say so instead of failing the init.
     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)}`);
@@ -256,19 +223,21 @@ async function cmdInit(agentId) {
     if (did)
         envOut.DECIDIO_AGENT_DID = did;
     if (privateKey)
-        envOut.DECIDIO_AGENT_KEY = privateKey; // written locally; never left this host
+        envOut.DECIDIO_AGENT_KEY = privateKey;
     if (agentToken)
-        envOut.DECIDIO_API_TOKEN = agentToken; // the FLOOR-LIMITED token — never the session
+        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);
-    // The closing doctor (and anything else this process does) must see what init just wrote —
-    // OVERWRITE process.env with the fresh values (round-3 Codex catch: doctor probed with the
-    // stale pre-init token and reported the mint it just watched as REJECTED).
     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("");
@@ -305,27 +274,33 @@ async function cmdDoctor() {
     line(!!(process.env.DECIDIO_AGENT_ID || env.DECIDIO_AGENT_ID), `agent id: ${process.env.DECIDIO_AGENT_ID || env.DECIDIO_AGENT_ID || "(unset — run: npx @decidio/sdk init <agent-name>)"}`);
     const secret = process.env.DECIDIO_WEBHOOK_SECRET || env.DECIDIO_WEBHOOK_SECRET;
     line(!!secret, secret ? "webhook secret: set — operator-only transport (inactive against the hosted sandbox; the poll worker guard.worker() is the self-serve resume path)" : "webhook secret: MISSING — the resume webhook (operator deployments) would fail closed; init generates one");
-    // Signing key — REQUIRED to be ELIGIBLE for auto-approve. Whether anything auto-approves is
-    // the workspace policy's call, not this key's (Codex finding: the old wording claimed
-    // "auto-approve is in effect" while deny-by-default routed everything).
     const signing = (process.env.DECIDIO_AGENT_KEY || env.DECIDIO_AGENT_KEY) && (process.env.DECIDIO_AGENT_DID || env.DECIDIO_AGENT_DID);
     if (signing)
         log("✔ signing key: set — the agent can prove its identity, making it ELIGIBLE for policy auto-approve. Whether a rule matches is your workspace policy's decision; with no matching rule every request routes to a human (deny-by-default).");
     else
         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.");
-    // Reachability and token role are SEPARATE checks (the old probe called any <500 green, so a
-    // wrong-kind token looked healthy). /api/health is unauthenticated truth about reachability;
-    // /api/records then classifies the token.
     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)");
     else if (rec.status === 401) {
-        // A 401 off the agent floor could also mean an INVALID token (Codex catch: don't
-        // false-green expiry). Disambiguate with a floor probe: a valid agent token gets 404 for an
-        // unknown decision (authorized, not found); an invalid one gets 401 again. A rejection here
-        // flips the overall verdict — "all green" after a red line was round 3's other doctor bug.
         const probe = await api("/agent/status/doctor-scope-probe");
         if (probe.status === 404)
             log("✔ token scope: agent floor — correct for the runtime SDK (approvals/receipt will ask you to sign in)");
@@ -339,11 +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) {
-    // Approvals are a HUMAN act on the workspace — session scope, never the agent token. If the
-    // env's token is agent-floor (401 on /api/*), sign in interactively; memory-only as always.
-    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");
@@ -360,9 +334,6 @@ async function cmdApprovals(sub, id, reason) {
         }
         const r = await api(`/api/decisions/${encodeURIComponent(id)}/${sub === "approve" ? "approve" : "reject"}`, { method: "POST", body: JSON.stringify({ reason: reason ?? undefined }) }, bearer);
         if (r.status >= 200 && r.status < 300) {
-            // HONESTY over green checkmarks (Codex finding: the server resolves each decision exactly
-            // once and answers replays idempotently — a replay is a NO-OP and must read as one, never
-            // as a fresh approval). Non-zero exit so scripts can tell the difference.
             if (r.body?.alreadyResolved) {
                 log(`• ${id} was already resolved — nothing changed.`);
                 log(`  Decisions are single-use: a second ${sub} can never re-execute the action (that's the replay protection working).`);
@@ -392,7 +363,6 @@ async function cmdApprovals(sub, id, reason) {
     const cards = r.body?.cards ?? [];
     const pending = cards.filter((c) => c.isAgentRequest && c.status !== "sealed");
     if (jsonMode) {
-        // Stable machine output (round-3 ask): agents scripting the queue parse this, not prose.
         log(JSON.stringify(pending.map((c) => ({ decisionId: c.id, action: c.agentRequest?.action ?? null, amount: c.agentRequest?.amount ?? null, title: c.title ?? null })), null, 2));
         return 0;
     }
@@ -401,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]`);
@@ -418,8 +393,6 @@ async function cmdReceipt(id, jsonMode = false) {
         log("  Find decision ids via `npx @decidio/sdk approvals` or in your Decidio app.");
         return 2;
     }
-    // Receipts are workspace data — session scope, like approvals. (The record-detail /verify
-    // route carries the credential; the plain record route does not — Codex finding.)
     let bearer;
     let r = await api(`/api/records/${encodeURIComponent(id)}/verify`);
     if (r.status === 401 || r.status === 403) {
@@ -439,32 +412,40 @@ async function cmdReceipt(id, jsonMode = false) {
         return 1;
     }
     const name = `decidio-receipt-${id.replace(/[^A-Za-z0-9_-]/g, "")}.json`;
-    writeFileSync(name, JSON.stringify(r.body.credential, null, 2) + "\n");
-    log(`✔ wrote ${name} (downloaded from your workspace — the download is online; VERIFYING it is offline)`);
-    // The credential seals at DECISION time (immutable), so execution evidence that arrived later
-    // lives on the record — surface the CURRENT tier here so the reader doesn't need a second
-    // lookup to see it (Codex catch).
+    const nextBytes = JSON.stringify(r.body.credential, null, 2) + "\n";
+    if (existsSync(name)) {
+        if (readFileSync(name, "utf8") !== nextBytes) {
+            log(`✘ ${name} already exists with DIFFERENT bytes — refusing to overwrite an audit artifact. Move it aside or delete it, then re-run.`);
+            return 1;
+        }
+        log(`• ${name} already exists (byte-identical — receipts are immutable); leaving it in place.`);
+    }
+    else {
+        writeFileSync(name, nextBytes);
+        log(`✔ wrote ${name} (downloaded from your workspace — the download is online; VERIFYING it is offline)`);
+    }
     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)" : ""}.`);
-    // Emit EXACTLY the deterministic command we document (round-4 catch: the README and this hint
-    // disagreed, and bare npx re-probes the registry) — the verifier ships INSIDE this package.
     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;
 }
-// ---- verify (embedded) ----------------------------------------------------------------------
-/** Duplicate-key-refusing parse — the SAME semantics as the decidio-verify CLI (RFC 8785 §3.1:
- *  duplicate keys make different parsers disagree on which value is real; refuse instead).
- *  Conformance-locked: the cross-language runner asserts this door refuses the same vectors for
- *  the same reasons as decidio-verify and python -m decidio.verify. */
 function parseReceiptStrict(text, file) {
     const value = JSON.parse(text);
     const stack = [];
@@ -512,8 +493,33 @@ 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("--"))) {
+        log("✘ --issuer needs a did:key value.");
+        return 2;
+    }
     const expectedIssuer = issIdx >= 0 ? argsIn[issIdx + 1] : undefined;
     const files = argsIn.filter((a, i) => !a.startsWith("--") && !(issIdx >= 0 && i === issIdx + 1));
     if (!files.length) {
@@ -538,13 +544,12 @@ 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;
 }
-// ---- quickstart (the guided two-minute tour) ------------------------------------------------
 async function cmdQuickstart() {
     const t0 = Date.now();
     log("Decidio quickstart — gate an action, route it to a human, execute on approval, hold the proof.");
@@ -553,9 +558,6 @@ async function cmdQuickstart() {
     const session = await acquireSession("The quickstart");
     if (!session)
         return 1;
-    // 1. A collision-proof agent, registered fresh every run (round-4 ask: idempotent sample
-    //    registration). Key generated locally; floor-limited token minted; .env written so the
-    //    take-away snippet works in this directory afterward.
     const agentId = `quickstart-${randomBytes(2).toString("hex")}`;
     log(`① Registering agent "${agentId}" (fresh name each run — no collisions)…`);
     const { did, privateKeyBase64 } = generateKeypair();
@@ -564,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;
@@ -574,9 +576,6 @@ async function cmdQuickstart() {
         DECIDIO_AGENT_KEY: privateKeyBase64, DECIDIO_API_TOKEN: mint.body.token,
         DECIDIO_WORKSPACE_ID: mint.body.workspaceId ?? "", DECIDIO_WEBHOOK_SECRET: readEnvFile().DECIDIO_WEBHOOK_SECRET || randomBytes(32).toString("hex"),
     };
-    // NEVER clobber a real agent's key (guard catch: keys never leave this machine — overwriting
-    // .env's DECIDIO_AGENT_KEY orphans that agent irrecoverably). A directory that already holds
-    // one gets a TOUR-SCOPED env file instead.
     let envFile = ENV_PATH;
     if (readEnvFile().DECIDIO_AGENT_KEY) {
         envFile = ".env.quickstart";
@@ -589,11 +588,11 @@ async function cmdQuickstart() {
     ensureGitignore();
     log(`  ✔ key generated locally (public half registered) · floor-limited token minted · ${envFile} written`);
     log("");
-    // 2. Gate a demo action — the same one line you'd wrap your real function with.
-    log(`② Gating a demo action with ONE line — guard.protect(payInvoice, …):`);
+    log(`② Gating a demo action — the tour runs this (blocking mode: watch it live):`);
     log("");
     log(`     const payInvoice = guard.protect(payInvoiceRaw,`);
-    log(`       (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }));`);
+    log(`       (inv) => ({ action: "payInvoice", amount: inv.amount, scope: "Invoice" }),`);
+    log(`       { mode: "blocking" });   // your real agent typically omits this — durable + a worker`);
     log("");
     let decisionId = "";
     const cfg = {
@@ -615,7 +614,6 @@ async function cmdQuickstart() {
     log(`  ✔ $86,000 payInvoice ROUTED to a human (decision ${decisionId}) — this agent has no auto-approve rule,`);
     log(`    so deny-by-default sends everything to a person. Nothing executes until someone decides.`);
     log("");
-    // 3. The human moment — approve right here, or from the Decidio app.
     if (process.stdin.isTTY) {
         await ask(`③ YOU are the approver. Press Enter to approve it here (or approve it in your Decidio queue first, then Enter): `);
     }
@@ -628,7 +626,6 @@ async function cmdQuickstart() {
         return 1;
     }
     log(`  ✔ approved${ap.body?.alreadyResolved ? " (it was already approved from your app — even better)" : ""}`);
-    // 4. The blocking wrapper wakes and runs the agent's own function.
     let result;
     try {
         result = await running;
@@ -639,7 +636,6 @@ async function cmdQuickstart() {
     }
     log(`  ✔ your function executed AFTER approval: ${JSON.stringify(result)}`);
     log("");
-    // 5. The proof: download the receipt and verify it offline, all in-process.
     log("④ Downloading the sealed Authority Receipt and verifying it OFFLINE…");
     const rec = await api(`/api/records/${encodeURIComponent(decisionId)}/verify`, {}, session);
     if (!(rec.status >= 200 && rec.status < 300) || !rec.body?.credential) {
@@ -648,26 +644,28 @@ 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 verified with NO network, no Decidio account)`);
+    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)
-        log(`  ✔ execution evidence on the record: ${tier} — the wrapper's report was cryptographically bound to this agent`);
+        log(`  ✔ execution evidence on the record: ${tier} — the wrapper's signed report. (The receipt seals the DECISION; execution evidence accrues on the record — see the README.)`);
     log("");
     const secs = Math.round((Date.now() - t0) / 1000);
-    log(`Done in ${secs}s: gated → routed to a human → approved → executed once → sealed, verifiable proof in your hands.`);
+    log(`Done in ${secs}s: gated → routed to a human → approved → your function executed once → an authority-decision receipt you can verify offline.`);
     log("");
     log("Take it to your real agent — the .env here already works:");
     log(`  import { guard } from "@decidio/sdk";`);
     log(`  const doIt = guard.protect(doItRaw, (a) => ({ action: "yourAction", amount: a.amount, scope: "YourScope" }));`);
+    log(`  // production is DURABLE mode (default) + one worker: guard.worker();  // README has the full pattern`);
     log("");
-    log("Next: the README's 7-step quickstart (durable mode, workers, adapters) · your queue at your Decidio app.");
+    log(`Your workspace + queue: ${API.replace("decidio-api.onrender.com", "app.decidioai.com")}  ·  Next: the README's 7-step quickstart (durable, workers, adapters).`);
     return v.valid ? 0 : 1;
 }
 function cmdDev(target, port) {
-    // Signal-only relay: receive Decidio's webhook here (a stable URL) and forward it to
-    // your local agent's resume listener. Useful when the agent isn't directly reachable.
     log(`decidio dev relay on http://localhost:${port}/decidio/resume → forwarding to ${target}`);
     createServer((req, res) => {
         if (req.method !== "POST") {
@@ -704,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)
@@ -736,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

@@ -8,36 +8,25 @@ export interface GuardFacadeConfig {
     resumeUrl?: string;
     webhookSecret?: string;
     pendingDir?: string;
-    /** Local signing key (DECIDIO_AGENT_KEY) + public did (DECIDIO_AGENT_DID), from `init`.
-     *  When present the gate authorizes against a PROVEN identity, not a claimed label. */
     agentKey?: string;
     agentDid?: string;
-    /** The workspace this agent acts in (DECIDIO_WORKSPACE_ID). Bound into the signed proof (D-B3.6)
-     *  so a captured proof can't be replayed in another tenant. */
     workspaceId?: string;
-    /** Base URL of the Decidio app (DECIDIO_APP_URL) — used to deep-link a routed decision. */
     appUrl?: string;
     fetchImpl?: typeof fetch;
 }
 export interface ProtectOptions {
-    /** null/"generic" → the core gate; engine adapters (langgraph/openai/temporal/inngest/mcp)
-     *  live in @decidio/sdk/adapters and take the engine handle. */
     adapter?: "generic" | "langgraph" | "openai" | "temporal" | "inngest" | "mcp";
-    /** "durable" (default) suspends for async approval; "blocking" polls (short approvals only). */
     mode?: "durable" | "blocking";
+    action?: string;
 }
 export declare class Guard {
     config: GuardFacadeConfig;
     resume?: ResumeController;
     constructor(config: GuardFacadeConfig, resume?: ResumeController);
     static fromEnv(): Guard;
-    /** Mount on a node/Express/Fastify route: `app.post("/decidio/resume", guard.resumeHandler())`. */
+    register(action: string, fn: (...a: any[]) => Promise<any>): void;
     resumeHandler(): import("http").RequestListener;
-    /** Mount on a Next.js/Hono/CF/Bun route: `export const POST = (req) => guard.resumeFetchHandler()(req)`. */
     resumeFetchHandler(): (req: Request) => Promise<Response>;
-    /** Durable resume with NOTHING to host: a background watcher polls Decidio outward and finishes
-     *  any parked approval — so a suspended action survives a process restart. One line at startup.
-     *  Production may swap this for the webhook (resumeUrl); the suspend/resume shape is identical. */
     worker(opts?: {
         intervalMs?: number;
         timeoutMs?: number;
@@ -48,5 +37,4 @@ export declare class Guard {
     private ensureResume;
     protect<A extends any[], R>(fn: (...a: A) => Promise<R>, describe: (...a: A) => ApprovalContext, opts?: ProtectOptions): (...a: A) => Promise<R>;
 }
-/** Preconfigured singleton — `import { guard } from "@decidio/sdk"`. */
 export declare const guard: Guard;