@fidacy/mcp 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -85,3 +85,30 @@ semantic versioning.
 - Onboarding: first-run `~/.fidacy/config.json` now writes the mandate template
   explicitly (payees/categories/currency/caps) — adding a trusted payee is a
   visible one-line edit; friendlier first-boot message (no more "dev mode" scare).
+
+## 0.1.11 — 2026-07-02
+
+- Upgrade micro-triggers, elegant by doctrine: fire only at value-proven moments
+  (first block, first duplicate-invoice/BEC catch, 10th gated action, one week
+  protected), each ONCE per install ever (persisted in config.json) — the free
+  tier stays fully usable in silence. The 0.1.10 every-DENY nudge is replaced.
+- verify_mandate/get_audit_proof gain one informational closing line each;
+  assess_action's missing-key error now offers the free-key path.
+- config.json gains created_at + nudge/decision state (preserved on read).
+
+## 0.1.12 — 2026-07-02
+
+- **The BEC guarantee now survives restarts.** The local free-tier core kept the
+  duplicate-invoice set and the spent counter in memory only, so a re-presented
+  invoice was ALLOWED again after every process restart — exactly the short-lived
+  shell case (`npx` per session). The core now rehydrates both from the persisted
+  audit log at boot: prior ALLOW records rebuild the invoice claims (a paid
+  invoice stays paid, regardless of age) and re-sum `spent` within the current
+  mandate window and currency. One O(records) pass over the already-loaded chain.
+- Audit records for ALLOWs now carry `amount`, `currency`, and the canonical
+  `invoiceRef` (rehydration fields). Additive: old logs stay valid, chain hashes
+  unchanged; pre-0.1.12 records simply carry no rehydratable state.
+- Torn-tail recovery: a crash mid-append used to quarantine the WHOLE audit log
+  on next boot (losing all dedup state). A torn trailing line is now recognized,
+  the intact prefix is salvaged, and the tail truncated. Mid-file damage still
+  quarantines the file as before.

package/dist/core.js

@@ -33,66 +33,9 @@ function sha256(input) {
 
 // ../firewall/dist/audit-store.js
 import fs from "node:fs";
-var FileAuditStore = class {
-  path;
-  chain = [];
-  constructor(path) {
-    this.path = path;
-    this.load();
-  }
-  load() {
-    if (!fs.existsSync(this.path))
-      return;
-    try {
-      const raw = fs.readFileSync(this.path, "utf8");
-      const parsed = [];
-      for (const line of raw.split("\n")) {
-        if (!line.trim())
-          continue;
-        parsed.push(JSON.parse(line));
-      }
-      this.chain = parsed;
-      if (!this.intact())
-        throw new Error("audit chain integrity broken");
-    } catch (err) {
-      this.chain = [];
-      try {
-        const quarantine = `${this.path}.corrupt-${Date.now()}`;
-        fs.renameSync(this.path, quarantine);
-        console.error(`[fidacy] audit log at ${this.path} is unreadable/tampered (${err.message}); quarantined to ${quarantine}, starting a fresh chain.`);
-      } catch {
-        console.error(`[fidacy] audit log at ${this.path} is unreadable/tampered and could not be quarantined; starting a fresh in-memory chain.`);
-      }
-    }
-  }
-  head() {
-    return this.chain.length ? this.chain[this.chain.length - 1].hash : "GENESIS";
-  }
-  append(decision) {
-    const prevHash = this.head();
-    const seq = this.chain.length;
-    const ts = decision.ts;
-    const digest = sha256(stableStringify({ decisionId: decision.decisionId, status: decision.status, request: decision.request, violatedRule: decision.violatedRule ?? null }));
-    const hash = sha256(`${prevHash}|${digest}|${seq}|${ts}`);
-    const record2 = { seq, decisionId: decision.decisionId, status: decision.status, subject: decision.subject, digest, prevHash, hash, ts };
-    fs.appendFileSync(this.path, JSON.stringify(record2) + "\n");
-    this.chain.push(record2);
-    return record2;
-  }
-  find(decisionId) {
-    return this.chain.find((r) => r.decisionId === decisionId);
-  }
-  intact() {
-    let prev = "GENESIS";
-    for (const r of this.chain) {
-      const expected = sha256(`${prev}|${r.digest}|${r.seq}|${r.ts}`);
-      if (expected !== r.hash || r.prevHash !== prev)
-        return false;
-      prev = r.hash;
-    }
-    return true;
-  }
-};
+
+// ../firewall/dist/core.js
+import { randomUUID } from "node:crypto";
 
 // ../firewall/dist/evaluate.js
 function fold(s) {
@@ -169,7 +112,6 @@ function evaluate(mandate, req, spentSoFar) {
 }
 
 // ../firewall/dist/core.js
-import { randomUUID } from "node:crypto";
 function canonInvoice(ref) {
   if (typeof ref !== "string")
     return "";
@@ -217,6 +159,35 @@ var DevFidacyCore = class {
     this.mandate = opts.mandate;
     this.store = new FileAuditStore(opts.auditLogPath ?? "./fidacy-audit.log");
     this.onDecision = opts.onDecision;
+    this.rehydrate();
+  }
+  /**
+   * Rebuild the in-memory decision state from the persisted audit log, so a process
+   * restart cannot re-open a claimed invoice (BEC dedup) or reset the maxTotal
+   * counter. One O(records) pass at boot over the already-loaded chain:
+   *   - claimedInvoices: every ALLOW that carried an invoiceRef, regardless of age —
+   *     a paid invoice stays paid.
+   *   - spent: ALLOW amounts whose timestamp falls inside the CURRENT mandate window
+   *     and whose currency matches the mandate (the cap is defined per window/currency).
+   * Records from older versions lack the rehydration fields and are skipped.
+   */
+  rehydrate() {
+    const notBefore = Date.parse(this.mandate.window.notBefore);
+    const notAfter = Date.parse(this.mandate.window.notAfter);
+    for (const r of this.store.records()) {
+      if (r.status !== "ALLOW")
+        continue;
+      if (r.invoiceRef)
+        this.claimedInvoices.add(`${r.subject}|${r.invoiceRef}`);
+      if (typeof r.amount !== "number" || !Number.isFinite(r.amount))
+        continue;
+      if (r.currency !== this.mandate.allow.currency)
+        continue;
+      const t = Date.parse(r.ts);
+      if (!Number.isFinite(t) || t < notBefore || t > notAfter)
+        continue;
+      this.spent += r.amount;
+    }
   }
   async getMandate() {
     return this.mandate;
@@ -303,6 +274,96 @@ var HttpFidacyCore = class {
   }
 };
 
+// ../firewall/dist/audit-store.js
+var FileAuditStore = class {
+  path;
+  chain = [];
+  constructor(path) {
+    this.path = path;
+    this.load();
+  }
+  load() {
+    if (!fs.existsSync(this.path))
+      return;
+    try {
+      const raw = fs.readFileSync(this.path, "utf8");
+      const lines = raw.split("\n");
+      const parsed = [];
+      let torn = false;
+      for (let i = 0; i < lines.length; i++) {
+        if (!lines[i].trim())
+          continue;
+        try {
+          parsed.push(JSON.parse(lines[i]));
+        } catch {
+          if (lines.slice(i + 1).some((l) => l.trim()))
+            throw new Error(`unparseable record at line ${i + 1}`);
+          torn = true;
+          break;
+        }
+      }
+      this.chain = parsed;
+      if (!this.intact())
+        throw new Error("audit chain integrity broken");
+      if (torn) {
+        const clean = parsed.map((r) => JSON.stringify(r)).join("\n") + (parsed.length ? "\n" : "");
+        fs.writeFileSync(this.path, clean);
+        console.error(`[fidacy] audit log at ${this.path} had a torn trailing line (crash during append?); salvaged ${parsed.length} intact records and truncated the tail.`);
+      }
+    } catch (err) {
+      this.chain = [];
+      try {
+        const quarantine = `${this.path}.corrupt-${Date.now()}`;
+        fs.renameSync(this.path, quarantine);
+        console.error(`[fidacy] audit log at ${this.path} is unreadable/tampered (${err.message}); quarantined to ${quarantine}, starting a fresh chain.`);
+      } catch {
+        console.error(`[fidacy] audit log at ${this.path} is unreadable/tampered and could not be quarantined; starting a fresh in-memory chain.`);
+      }
+    }
+  }
+  head() {
+    return this.chain.length ? this.chain[this.chain.length - 1].hash : "GENESIS";
+  }
+  append(decision) {
+    const prevHash = this.head();
+    const seq = this.chain.length;
+    const ts = decision.ts;
+    const digest = sha256(stableStringify({ decisionId: decision.decisionId, status: decision.status, request: decision.request, violatedRule: decision.violatedRule ?? null }));
+    const hash = sha256(`${prevHash}|${digest}|${seq}|${ts}`);
+    const record2 = { seq, decisionId: decision.decisionId, status: decision.status, subject: decision.subject, digest, prevHash, hash, ts };
+    if (decision.status === "ALLOW") {
+      const req = decision.request;
+      if (typeof req?.amount === "number" && Number.isFinite(req.amount))
+        record2.amount = req.amount;
+      if (typeof req?.currency === "string")
+        record2.currency = req.currency;
+      const invoice = canonInvoice(req?.invoiceRef);
+      if (invoice)
+        record2.invoiceRef = invoice;
+    }
+    fs.appendFileSync(this.path, JSON.stringify(record2) + "\n");
+    this.chain.push(record2);
+    return record2;
+  }
+  find(decisionId) {
+    return this.chain.find((r) => r.decisionId === decisionId);
+  }
+  /** The full loaded chain, oldest first. Read-only; used to rehydrate core state at boot. */
+  records() {
+    return this.chain;
+  }
+  intact() {
+    let prev = "GENESIS";
+    for (const r of this.chain) {
+      const expected = sha256(`${prev}|${r.digest}|${r.seq}|${r.ts}`);
+      if (expected !== r.hash || r.prevHash !== prev)
+        return false;
+      prev = r.hash;
+    }
+    return true;
+  }
+};
+
 // src/config.ts
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -337,7 +398,12 @@ function readConfig() {
       anon_id: raw.anon_id,
       tier: raw.tier === "paid" ? "paid" : "free",
       api_key: typeof raw.api_key === "string" ? raw.api_key : null,
-      mandate: raw.mandate
+      mandate: raw.mandate,
+      // Install-state passthrough: dropping these on a read→write cycle would
+      // reset every once-per-install nudge into an every-time nag.
+      created_at: typeof raw.created_at === "string" ? raw.created_at : void 0,
+      nudges: raw.nudges && typeof raw.nudges === "object" ? raw.nudges : void 0,
+      decisions_count: typeof raw.decisions_count === "number" ? raw.decisions_count : void 0
     };
   } catch {
     return null;
@@ -357,7 +423,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.10" : "dev";
+var CLIENT_VERSION = true ? "0.1.12" : "dev";
 var currentShell = "mcp";
 function telemetryEnabled() {
   const v = (process.env.FIDACY_DISABLE_TELEMETRY ?? "").trim().toLowerCase();

package/dist/index.js

@@ -40,66 +40,9 @@ function sha256(input) {
 
 // ../firewall/dist/audit-store.js
 import fs from "node:fs";
-var FileAuditStore = class {
-  path;
-  chain = [];
-  constructor(path) {
-    this.path = path;
-    this.load();
-  }
-  load() {
-    if (!fs.existsSync(this.path))
-      return;
-    try {
-      const raw = fs.readFileSync(this.path, "utf8");
-      const parsed = [];
-      for (const line of raw.split("\n")) {
-        if (!line.trim())
-          continue;
-        parsed.push(JSON.parse(line));
-      }
-      this.chain = parsed;
-      if (!this.intact())
-        throw new Error("audit chain integrity broken");
-    } catch (err) {
-      this.chain = [];
-      try {
-        const quarantine = `${this.path}.corrupt-${Date.now()}`;
-        fs.renameSync(this.path, quarantine);
-        console.error(`[fidacy] audit log at ${this.path} is unreadable/tampered (${err.message}); quarantined to ${quarantine}, starting a fresh chain.`);
-      } catch {
-        console.error(`[fidacy] audit log at ${this.path} is unreadable/tampered and could not be quarantined; starting a fresh in-memory chain.`);
-      }
-    }
-  }
-  head() {
-    return this.chain.length ? this.chain[this.chain.length - 1].hash : "GENESIS";
-  }
-  append(decision) {
-    const prevHash = this.head();
-    const seq = this.chain.length;
-    const ts = decision.ts;
-    const digest = sha256(stableStringify({ decisionId: decision.decisionId, status: decision.status, request: decision.request, violatedRule: decision.violatedRule ?? null }));
-    const hash = sha256(`${prevHash}|${digest}|${seq}|${ts}`);
-    const record2 = { seq, decisionId: decision.decisionId, status: decision.status, subject: decision.subject, digest, prevHash, hash, ts };
-    fs.appendFileSync(this.path, JSON.stringify(record2) + "\n");
-    this.chain.push(record2);
-    return record2;
-  }
-  find(decisionId) {
-    return this.chain.find((r) => r.decisionId === decisionId);
-  }
-  intact() {
-    let prev = "GENESIS";
-    for (const r of this.chain) {
-      const expected = sha256(`${prev}|${r.digest}|${r.seq}|${r.ts}`);
-      if (expected !== r.hash || r.prevHash !== prev)
-        return false;
-      prev = r.hash;
-    }
-    return true;
-  }
-};
+
+// ../firewall/dist/core.js
+import { randomUUID } from "node:crypto";
 
 // ../firewall/dist/evaluate.js
 function fold(s) {
@@ -176,7 +119,6 @@ function evaluate(mandate, req, spentSoFar) {
 }
 
 // ../firewall/dist/core.js
-import { randomUUID } from "node:crypto";
 function canonInvoice(ref) {
   if (typeof ref !== "string")
     return "";
@@ -224,6 +166,35 @@ var DevFidacyCore = class {
     this.mandate = opts.mandate;
     this.store = new FileAuditStore(opts.auditLogPath ?? "./fidacy-audit.log");
     this.onDecision = opts.onDecision;
+    this.rehydrate();
+  }
+  /**
+   * Rebuild the in-memory decision state from the persisted audit log, so a process
+   * restart cannot re-open a claimed invoice (BEC dedup) or reset the maxTotal
+   * counter. One O(records) pass at boot over the already-loaded chain:
+   *   - claimedInvoices: every ALLOW that carried an invoiceRef, regardless of age —
+   *     a paid invoice stays paid.
+   *   - spent: ALLOW amounts whose timestamp falls inside the CURRENT mandate window
+   *     and whose currency matches the mandate (the cap is defined per window/currency).
+   * Records from older versions lack the rehydration fields and are skipped.
+   */
+  rehydrate() {
+    const notBefore = Date.parse(this.mandate.window.notBefore);
+    const notAfter = Date.parse(this.mandate.window.notAfter);
+    for (const r of this.store.records()) {
+      if (r.status !== "ALLOW")
+        continue;
+      if (r.invoiceRef)
+        this.claimedInvoices.add(`${r.subject}|${r.invoiceRef}`);
+      if (typeof r.amount !== "number" || !Number.isFinite(r.amount))
+        continue;
+      if (r.currency !== this.mandate.allow.currency)
+        continue;
+      const t = Date.parse(r.ts);
+      if (!Number.isFinite(t) || t < notBefore || t > notAfter)
+        continue;
+      this.spent += r.amount;
+    }
   }
   async getMandate() {
     return this.mandate;
@@ -310,6 +281,96 @@ var HttpFidacyCore = class {
   }
 };
 
+// ../firewall/dist/audit-store.js
+var FileAuditStore = class {
+  path;
+  chain = [];
+  constructor(path) {
+    this.path = path;
+    this.load();
+  }
+  load() {
+    if (!fs.existsSync(this.path))
+      return;
+    try {
+      const raw = fs.readFileSync(this.path, "utf8");
+      const lines = raw.split("\n");
+      const parsed = [];
+      let torn = false;
+      for (let i = 0; i < lines.length; i++) {
+        if (!lines[i].trim())
+          continue;
+        try {
+          parsed.push(JSON.parse(lines[i]));
+        } catch {
+          if (lines.slice(i + 1).some((l) => l.trim()))
+            throw new Error(`unparseable record at line ${i + 1}`);
+          torn = true;
+          break;
+        }
+      }
+      this.chain = parsed;
+      if (!this.intact())
+        throw new Error("audit chain integrity broken");
+      if (torn) {
+        const clean = parsed.map((r) => JSON.stringify(r)).join("\n") + (parsed.length ? "\n" : "");
+        fs.writeFileSync(this.path, clean);
+        console.error(`[fidacy] audit log at ${this.path} had a torn trailing line (crash during append?); salvaged ${parsed.length} intact records and truncated the tail.`);
+      }
+    } catch (err) {
+      this.chain = [];
+      try {
+        const quarantine = `${this.path}.corrupt-${Date.now()}`;
+        fs.renameSync(this.path, quarantine);
+        console.error(`[fidacy] audit log at ${this.path} is unreadable/tampered (${err.message}); quarantined to ${quarantine}, starting a fresh chain.`);
+      } catch {
+        console.error(`[fidacy] audit log at ${this.path} is unreadable/tampered and could not be quarantined; starting a fresh in-memory chain.`);
+      }
+    }
+  }
+  head() {
+    return this.chain.length ? this.chain[this.chain.length - 1].hash : "GENESIS";
+  }
+  append(decision) {
+    const prevHash = this.head();
+    const seq = this.chain.length;
+    const ts = decision.ts;
+    const digest = sha256(stableStringify({ decisionId: decision.decisionId, status: decision.status, request: decision.request, violatedRule: decision.violatedRule ?? null }));
+    const hash = sha256(`${prevHash}|${digest}|${seq}|${ts}`);
+    const record2 = { seq, decisionId: decision.decisionId, status: decision.status, subject: decision.subject, digest, prevHash, hash, ts };
+    if (decision.status === "ALLOW") {
+      const req = decision.request;
+      if (typeof req?.amount === "number" && Number.isFinite(req.amount))
+        record2.amount = req.amount;
+      if (typeof req?.currency === "string")
+        record2.currency = req.currency;
+      const invoice = canonInvoice(req?.invoiceRef);
+      if (invoice)
+        record2.invoiceRef = invoice;
+    }
+    fs.appendFileSync(this.path, JSON.stringify(record2) + "\n");
+    this.chain.push(record2);
+    return record2;
+  }
+  find(decisionId) {
+    return this.chain.find((r) => r.decisionId === decisionId);
+  }
+  /** The full loaded chain, oldest first. Read-only; used to rehydrate core state at boot. */
+  records() {
+    return this.chain;
+  }
+  intact() {
+    let prev = "GENESIS";
+    for (const r of this.chain) {
+      const expected = sha256(`${prev}|${r.digest}|${r.seq}|${r.ts}`);
+      if (expected !== r.hash || r.prevHash !== prev)
+        return false;
+      prev = r.hash;
+    }
+    return true;
+  }
+};
+
 // src/config.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
 import { homedir } from "node:os";
@@ -345,7 +406,12 @@ function readConfig() {
       anon_id: raw.anon_id,
       tier: raw.tier === "paid" ? "paid" : "free",
       api_key: typeof raw.api_key === "string" ? raw.api_key : null,
-      mandate: raw.mandate
+      mandate: raw.mandate,
+      // Install-state passthrough: dropping these on a read→write cycle would
+      // reset every once-per-install nudge into an every-time nag.
+      created_at: typeof raw.created_at === "string" ? raw.created_at : void 0,
+      nudges: raw.nudges && typeof raw.nudges === "object" ? raw.nudges : void 0,
+      decisions_count: typeof raw.decisions_count === "number" ? raw.decisions_count : void 0
     };
   } catch {
     return null;
@@ -363,7 +429,8 @@ function ensureState() {
     anon_id: randomUUID2(),
     tier: "free",
     api_key: null,
-    mandate: { payees: [], categories: ["*"], currency: "USD", perTxMax: 2500, maxTotal: 1e4 }
+    mandate: { payees: [], categories: ["*"], currency: "USD", perTxMax: 2500, maxTotal: 1e4 },
+    created_at: (/* @__PURE__ */ new Date()).toISOString()
   };
   try {
     writeConfig(config);
@@ -385,7 +452,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.10" : "dev";
+var CLIENT_VERSION = true ? "0.1.12" : "dev";
 var currentShell = "mcp";
 function telemetryEnabled() {
   const v = (process.env.FIDACY_DISABLE_TELEMETRY ?? "").trim().toLowerCase();
@@ -609,7 +676,7 @@ async function postOnce(fetchImpl, url, headers, payload, timeoutMs) {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.1.10" : "dev";
+var CLIENT_VERSION2 = true ? "0.1.12" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -656,6 +723,55 @@ function requestUpgrade() {
   return { url: upgradeUrl(), anonId: anonId2 };
 }
 
+// src/nudges.ts
+function nudgeOnce(key) {
+  const cfg = readConfig();
+  if (!cfg) return false;
+  if (cfg.nudges?.[key]) return false;
+  cfg.nudges = { ...cfg.nudges ?? {}, [key]: true };
+  try {
+    writeConfig(cfg);
+  } catch {
+    return false;
+  }
+  return true;
+}
+function bumpDecisionCount() {
+  const cfg = readConfig();
+  if (!cfg) return 0;
+  const n = (cfg.decisions_count ?? 0) + 1;
+  cfg.decisions_count = n;
+  try {
+    writeConfig(cfg);
+  } catch {
+  }
+  return n;
+}
+function installAgeDays() {
+  const t = Date.parse(readConfig()?.created_at ?? "");
+  if (Number.isNaN(t)) return 0;
+  return Math.floor((Date.now() - t) / 864e5);
+}
+function decisionNudge(status, violatedRule, upgradeToolName) {
+  const count = bumpDecisionCount();
+  if (status === "DENY" && violatedRule?.startsWith("duplicate_invoice") && nudgeOnce("bec_catch")) {
+    return `That was a duplicate-invoice (BEC) catch \u2014 the #1 payment fraud. On a free account every block like this is server-signed and anchored to Bitcoin: court-grade evidence. Call the ${upgradeToolName} tool to start.`;
+  }
+  if (status === "DENY" && nudgeOnce("first_deny")) {
+    return `Fidacy just blocked this for you \u2014 for server-signed, anchored proof of every block (free account, local history migrates), call the ${upgradeToolName} tool.`;
+  }
+  if (count === 10 && nudgeOnce("milestone_10")) {
+    return `That's 10 actions gated on this install. For a signed, Bitcoin-anchored history of all of them (free account), call the ${upgradeToolName} tool.`;
+  }
+  return null;
+}
+function weekOneBootNudge(upgradeToolName) {
+  if (installAgeDays() >= 7 && nudgeOnce("week_1")) {
+    return ` One week protected \u2014 anchor your history to Bitcoin with a free account: the ${upgradeToolName} tool starts it.`;
+  }
+  return null;
+}
+
 // src/index.ts
 var state = ensureState();
 var core = makeCore();
@@ -689,8 +805,10 @@ server.registerTool(
     const req = args;
     const d = await core.decide(req, subject);
     const out = { status: d.status, decisionId: d.decisionId, grant: d.grant, violatedRule: d.violatedRule };
-    const human = d.status === "ALLOW" ? `ALLOW (decision ${d.decisionId})${req.invoiceRef ? ` for invoice ${req.invoiceRef}` : ""}. To settle, call execute_payment with the SAME payee, amount, currency, and idempotencyKey, and set "grant" to EXACTLY this signed value:
-${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}. No grant issued, this payment cannot proceed. The denial itself is recorded in the tamper-evident, hash-chained audit: call get_audit_proof with decisionId ${d.decisionId} for the proof of what was blocked. Fidacy just blocked this for you \u2014 for server-signed, anchored proof of every block (free account, local history migrates), call the upgrade tool.`;
+    const base = d.status === "ALLOW" ? `ALLOW (decision ${d.decisionId})${req.invoiceRef ? ` for invoice ${req.invoiceRef}` : ""}. To settle, call execute_payment with the SAME payee, amount, currency, and idempotencyKey, and set "grant" to EXACTLY this signed value:
+${d.grant}` : `DENY (decision ${d.decisionId}). Rule violated: ${d.violatedRule}. No grant issued, this payment cannot proceed. The denial itself is recorded in the tamper-evident, hash-chained audit: call get_audit_proof with decisionId ${d.decisionId} for the proof of what was blocked.`;
+    const nudge = decisionNudge(d.status, d.violatedRule, "upgrade");
+    const human = nudge ? `${base} ${nudge}` : base;
     return { content: [{ type: "text", text: human }], structuredContent: out };
   }
 );
@@ -705,7 +823,8 @@ server.registerTool(
   async () => {
     const m = await core.getMandate(subject);
     const payload = { mandate: m, fidacyPublicKey: core.publicKey() };
-    return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], structuredContent: payload };
+    const text = JSON.stringify(payload, null, 2) + "\n\nThis mandate is local (free tier). Hosted mandates add team governance and server-signed verdicts \u2014 the upgrade tool starts a free account.";
+    return { content: [{ type: "text", text }], structuredContent: payload };
   }
 );
 server.registerTool(
@@ -719,7 +838,8 @@ server.registerTool(
   async ({ decisionId }) => {
     const proof = await core.getProof(decisionId);
     if (!proof) return { content: [{ type: "text", text: `No proof found for ${decisionId}` }], isError: true };
-    return { content: [{ type: "text", text: JSON.stringify(proof, null, 2) }], structuredContent: proof };
+    const text = JSON.stringify(proof, null, 2) + "\n\nThis proof lives on this machine. On a free hosted account the chain is anchored to Bitcoin \u2014 verifiable by anyone, forever, even against Fidacy (the upgrade tool starts it).";
+    return { content: [{ type: "text", text }], structuredContent: proof };
   }
 );
 server.registerTool(
@@ -745,7 +865,7 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: "assess_action requires FIDACY_ENGINE_API_KEY (an fky_live_/fky_test_ key with assess:write). Set it to enable signed verdicts."
+            text: "assess_action needs an engine key \u2014 free in about a minute: call the upgrade tool (your usage history migrates), or set FIDACY_ENGINE_API_KEY if you already have one."
           }
         ],
         isError: true
@@ -805,7 +925,8 @@ async function main() {
   void autoProvision();
   const verdictHint = process.env.FIDACY_ENGINE_API_KEY ? "" : " Set FIDACY_ENGINE_API_KEY to enable verdicts (assess_action).";
   const tierHint = state.firstRun ? " First run: free local tier active (deny-unknown payee + cap). Add trusted payees in ~/.fidacy/config.json." : ` Tier: ${state.config.tier} (local-first).`;
-  console.error("[fidacy] @fidacy/mcp ready on stdio: signed verdict + payment firewall." + tierHint + verdictHint);
+  const weekNudge = weekOneBootNudge("upgrade") ?? "";
+  console.error("[fidacy] @fidacy/mcp ready on stdio: signed verdict + payment firewall." + tierHint + verdictHint + weekNudge);
 }
 main().catch((e) => {
   console.error("[fidacy] fatal:", e);

package/dist/lib.js

@@ -74,151 +74,9 @@ function verifyGrant(publicKeyPem2, grant, expected) {
 
 // ../firewall/dist/audit-store.js
 import fs from "node:fs";
-var FileAuditStore = class {
-  path;
-  chain = [];
-  constructor(path) {
-    this.path = path;
-    this.load();
-  }
-  load() {
-    if (!fs.existsSync(this.path))
-      return;
-    try {
-      const raw = fs.readFileSync(this.path, "utf8");
-      const parsed = [];
-      for (const line of raw.split("\n")) {
-        if (!line.trim())
-          continue;
-        parsed.push(JSON.parse(line));
-      }
-      this.chain = parsed;
-      if (!this.intact())
-        throw new Error("audit chain integrity broken");
-    } catch (err) {
-      this.chain = [];
-      try {
-        const quarantine = `${this.path}.corrupt-${Date.now()}`;
-        fs.renameSync(this.path, quarantine);
-        console.error(`[fidacy] audit log at ${this.path} is unreadable/tampered (${err.message}); quarantined to ${quarantine}, starting a fresh chain.`);
-      } catch {
-        console.error(`[fidacy] audit log at ${this.path} is unreadable/tampered and could not be quarantined; starting a fresh in-memory chain.`);
-      }
-    }
-  }
-  head() {
-    return this.chain.length ? this.chain[this.chain.length - 1].hash : "GENESIS";
-  }
-  append(decision) {
-    const prevHash = this.head();
-    const seq = this.chain.length;
-    const ts = decision.ts;
-    const digest = sha256(stableStringify({ decisionId: decision.decisionId, status: decision.status, request: decision.request, violatedRule: decision.violatedRule ?? null }));
-    const hash = sha256(`${prevHash}|${digest}|${seq}|${ts}`);
-    const record2 = { seq, decisionId: decision.decisionId, status: decision.status, subject: decision.subject, digest, prevHash, hash, ts };
-    fs.appendFileSync(this.path, JSON.stringify(record2) + "\n");
-    this.chain.push(record2);
-    return record2;
-  }
-  find(decisionId) {
-    return this.chain.find((r) => r.decisionId === decisionId);
-  }
-  intact() {
-    let prev = "GENESIS";
-    for (const r of this.chain) {
-      const expected = sha256(`${prev}|${r.digest}|${r.seq}|${r.ts}`);
-      if (expected !== r.hash || r.prevHash !== prev)
-        return false;
-      prev = r.hash;
-    }
-    return true;
-  }
-};
 
-// ../firewall/dist/executor.js
-import { createPublicKey } from "node:crypto";
+// ../firewall/dist/core.js
 import { randomUUID } from "node:crypto";
-var ReferenceRail = class {
-  settlements = [];
-  async execute(req) {
-    const railRef = "ref_" + randomUUID();
-    this.settlements.push({ ...req, railRef, at: (/* @__PURE__ */ new Date()).toISOString() });
-    return { railRef };
-  }
-};
-function httpRedeem(coreUrl, apiKey) {
-  const base = String(coreUrl ?? "").replace(/\/+$/, "");
-  const u = new URL(base);
-  if (u.protocol !== "https:" && !(u.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1"))) {
-    throw new Error("core URL must be https:// (the API key is sent to it)");
-  }
-  return async (grant) => {
-    const res = await fetch(`${base}/v1/grant/redeem`, {
-      method: "POST",
-      headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
-      body: JSON.stringify({ grant })
-    });
-    if (res.status === 200)
-      return true;
-    if (res.status === 409)
-      return false;
-    throw new Error(`redeem -> ${res.status}`);
-  };
-}
-var GrantEnforcingExecutor = class {
-  rail;
-  used = /* @__PURE__ */ new Set();
-  pub;
-  redeem;
-  constructor(publicKeyPem2, rail, opts) {
-    this.rail = rail;
-    this.pub = createPublicKey(publicKeyPem2);
-    this.redeem = opts?.redeem;
-  }
-  async execute(req, grant) {
-    if (!grant)
-      return { status: "REFUSED", reason: "missing_grant" };
-    const dot = grant.indexOf(".");
-    if (dot < 0)
-      return { status: "REFUSED", reason: "malformed_grant" };
-    const body = grant.slice(0, dot);
-    const sig = grant.slice(dot + 1);
-    if (!verify(this.pub, body, sig))
-      return { status: "REFUSED", reason: "invalid_signature" };
-    let p;
-    try {
-      p = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
-    } catch {
-      return { status: "REFUSED", reason: "undecodable_grant" };
-    }
-    if (Date.now() > p.exp)
-      return { status: "REFUSED", reason: "grant_expired" };
-    if (this.used.has(p.decisionId))
-      return { status: "REFUSED", reason: "grant_replayed" };
-    if (p.payee !== req.payee)
-      return { status: "REFUSED", reason: "payee_mismatch" };
-    if (p.amount !== req.amount)
-      return { status: "REFUSED", reason: "amount_mismatch" };
-    if (p.currency !== req.currency)
-      return { status: "REFUSED", reason: "currency_mismatch" };
-    if (req.invoiceRef != null && req.invoiceRef !== (p.invoiceRef ?? null)) {
-      return { status: "REFUSED", reason: "invoice_mismatch" };
-    }
-    if (this.redeem) {
-      let first;
-      try {
-        first = await this.redeem(grant);
-      } catch {
-        return { status: "REFUSED", reason: "redeem_unavailable" };
-      }
-      if (!first)
-        return { status: "REFUSED", reason: "grant_replayed" };
-    }
-    this.used.add(p.decisionId);
-    const { railRef } = await this.rail.execute(req);
-    return { status: "EXECUTED", railRef, decisionId: p.decisionId };
-  }
-};
 
 // ../firewall/dist/evaluate.js
 function fold(s) {
@@ -295,7 +153,6 @@ function evaluate(mandate, req, spentSoFar) {
 }
 
 // ../firewall/dist/core.js
-import { randomUUID as randomUUID2 } from "node:crypto";
 function canonInvoice(ref) {
   if (typeof ref !== "string")
     return "";
@@ -343,12 +200,41 @@ var DevFidacyCore = class {
     this.mandate = opts.mandate;
     this.store = new FileAuditStore(opts.auditLogPath ?? "./fidacy-audit.log");
     this.onDecision = opts.onDecision;
+    this.rehydrate();
+  }
+  /**
+   * Rebuild the in-memory decision state from the persisted audit log, so a process
+   * restart cannot re-open a claimed invoice (BEC dedup) or reset the maxTotal
+   * counter. One O(records) pass at boot over the already-loaded chain:
+   *   - claimedInvoices: every ALLOW that carried an invoiceRef, regardless of age —
+   *     a paid invoice stays paid.
+   *   - spent: ALLOW amounts whose timestamp falls inside the CURRENT mandate window
+   *     and whose currency matches the mandate (the cap is defined per window/currency).
+   * Records from older versions lack the rehydration fields and are skipped.
+   */
+  rehydrate() {
+    const notBefore = Date.parse(this.mandate.window.notBefore);
+    const notAfter = Date.parse(this.mandate.window.notAfter);
+    for (const r of this.store.records()) {
+      if (r.status !== "ALLOW")
+        continue;
+      if (r.invoiceRef)
+        this.claimedInvoices.add(`${r.subject}|${r.invoiceRef}`);
+      if (typeof r.amount !== "number" || !Number.isFinite(r.amount))
+        continue;
+      if (r.currency !== this.mandate.allow.currency)
+        continue;
+      const t = Date.parse(r.ts);
+      if (!Number.isFinite(t) || t < notBefore || t > notAfter)
+        continue;
+      this.spent += r.amount;
+    }
   }
   async getMandate() {
     return this.mandate;
   }
   async decide(req, subject) {
-    const decisionId = randomUUID2();
+    const decisionId = randomUUID();
     const ts = (/* @__PURE__ */ new Date()).toISOString();
     const invalid = validateRequest(req);
     if (invalid) {
@@ -429,6 +315,181 @@ var HttpFidacyCore = class {
   }
 };
 
+// ../firewall/dist/audit-store.js
+var FileAuditStore = class {
+  path;
+  chain = [];
+  constructor(path) {
+    this.path = path;
+    this.load();
+  }
+  load() {
+    if (!fs.existsSync(this.path))
+      return;
+    try {
+      const raw = fs.readFileSync(this.path, "utf8");
+      const lines = raw.split("\n");
+      const parsed = [];
+      let torn = false;
+      for (let i = 0; i < lines.length; i++) {
+        if (!lines[i].trim())
+          continue;
+        try {
+          parsed.push(JSON.parse(lines[i]));
+        } catch {
+          if (lines.slice(i + 1).some((l) => l.trim()))
+            throw new Error(`unparseable record at line ${i + 1}`);
+          torn = true;
+          break;
+        }
+      }
+      this.chain = parsed;
+      if (!this.intact())
+        throw new Error("audit chain integrity broken");
+      if (torn) {
+        const clean = parsed.map((r) => JSON.stringify(r)).join("\n") + (parsed.length ? "\n" : "");
+        fs.writeFileSync(this.path, clean);
+        console.error(`[fidacy] audit log at ${this.path} had a torn trailing line (crash during append?); salvaged ${parsed.length} intact records and truncated the tail.`);
+      }
+    } catch (err) {
+      this.chain = [];
+      try {
+        const quarantine = `${this.path}.corrupt-${Date.now()}`;
+        fs.renameSync(this.path, quarantine);
+        console.error(`[fidacy] audit log at ${this.path} is unreadable/tampered (${err.message}); quarantined to ${quarantine}, starting a fresh chain.`);
+      } catch {
+        console.error(`[fidacy] audit log at ${this.path} is unreadable/tampered and could not be quarantined; starting a fresh in-memory chain.`);
+      }
+    }
+  }
+  head() {
+    return this.chain.length ? this.chain[this.chain.length - 1].hash : "GENESIS";
+  }
+  append(decision) {
+    const prevHash = this.head();
+    const seq = this.chain.length;
+    const ts = decision.ts;
+    const digest = sha256(stableStringify({ decisionId: decision.decisionId, status: decision.status, request: decision.request, violatedRule: decision.violatedRule ?? null }));
+    const hash = sha256(`${prevHash}|${digest}|${seq}|${ts}`);
+    const record2 = { seq, decisionId: decision.decisionId, status: decision.status, subject: decision.subject, digest, prevHash, hash, ts };
+    if (decision.status === "ALLOW") {
+      const req = decision.request;
+      if (typeof req?.amount === "number" && Number.isFinite(req.amount))
+        record2.amount = req.amount;
+      if (typeof req?.currency === "string")
+        record2.currency = req.currency;
+      const invoice = canonInvoice(req?.invoiceRef);
+      if (invoice)
+        record2.invoiceRef = invoice;
+    }
+    fs.appendFileSync(this.path, JSON.stringify(record2) + "\n");
+    this.chain.push(record2);
+    return record2;
+  }
+  find(decisionId) {
+    return this.chain.find((r) => r.decisionId === decisionId);
+  }
+  /** The full loaded chain, oldest first. Read-only; used to rehydrate core state at boot. */
+  records() {
+    return this.chain;
+  }
+  intact() {
+    let prev = "GENESIS";
+    for (const r of this.chain) {
+      const expected = sha256(`${prev}|${r.digest}|${r.seq}|${r.ts}`);
+      if (expected !== r.hash || r.prevHash !== prev)
+        return false;
+      prev = r.hash;
+    }
+    return true;
+  }
+};
+
+// ../firewall/dist/executor.js
+import { createPublicKey } from "node:crypto";
+import { randomUUID as randomUUID2 } from "node:crypto";
+var ReferenceRail = class {
+  settlements = [];
+  async execute(req) {
+    const railRef = "ref_" + randomUUID2();
+    this.settlements.push({ ...req, railRef, at: (/* @__PURE__ */ new Date()).toISOString() });
+    return { railRef };
+  }
+};
+function httpRedeem(coreUrl, apiKey) {
+  const base = String(coreUrl ?? "").replace(/\/+$/, "");
+  const u = new URL(base);
+  if (u.protocol !== "https:" && !(u.protocol === "http:" && (u.hostname === "localhost" || u.hostname === "127.0.0.1"))) {
+    throw new Error("core URL must be https:// (the API key is sent to it)");
+  }
+  return async (grant) => {
+    const res = await fetch(`${base}/v1/grant/redeem`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
+      body: JSON.stringify({ grant })
+    });
+    if (res.status === 200)
+      return true;
+    if (res.status === 409)
+      return false;
+    throw new Error(`redeem -> ${res.status}`);
+  };
+}
+var GrantEnforcingExecutor = class {
+  rail;
+  used = /* @__PURE__ */ new Set();
+  pub;
+  redeem;
+  constructor(publicKeyPem2, rail, opts) {
+    this.rail = rail;
+    this.pub = createPublicKey(publicKeyPem2);
+    this.redeem = opts?.redeem;
+  }
+  async execute(req, grant) {
+    if (!grant)
+      return { status: "REFUSED", reason: "missing_grant" };
+    const dot = grant.indexOf(".");
+    if (dot < 0)
+      return { status: "REFUSED", reason: "malformed_grant" };
+    const body = grant.slice(0, dot);
+    const sig = grant.slice(dot + 1);
+    if (!verify(this.pub, body, sig))
+      return { status: "REFUSED", reason: "invalid_signature" };
+    let p;
+    try {
+      p = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+    } catch {
+      return { status: "REFUSED", reason: "undecodable_grant" };
+    }
+    if (Date.now() > p.exp)
+      return { status: "REFUSED", reason: "grant_expired" };
+    if (this.used.has(p.decisionId))
+      return { status: "REFUSED", reason: "grant_replayed" };
+    if (p.payee !== req.payee)
+      return { status: "REFUSED", reason: "payee_mismatch" };
+    if (p.amount !== req.amount)
+      return { status: "REFUSED", reason: "amount_mismatch" };
+    if (p.currency !== req.currency)
+      return { status: "REFUSED", reason: "currency_mismatch" };
+    if (req.invoiceRef != null && req.invoiceRef !== (p.invoiceRef ?? null)) {
+      return { status: "REFUSED", reason: "invoice_mismatch" };
+    }
+    if (this.redeem) {
+      let first;
+      try {
+        first = await this.redeem(grant);
+      } catch {
+        return { status: "REFUSED", reason: "redeem_unavailable" };
+      }
+      if (!first)
+        return { status: "REFUSED", reason: "grant_replayed" };
+    }
+    this.used.add(p.decisionId);
+    const { railRef } = await this.rail.execute(req);
+    return { status: "EXECUTED", railRef, decisionId: p.decisionId };
+  }
+};
+
 // src/config.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 import { homedir } from "node:os";
@@ -464,7 +525,12 @@ function readConfig() {
       anon_id: raw.anon_id,
       tier: raw.tier === "paid" ? "paid" : "free",
       api_key: typeof raw.api_key === "string" ? raw.api_key : null,
-      mandate: raw.mandate
+      mandate: raw.mandate,
+      // Install-state passthrough: dropping these on a read→write cycle would
+      // reset every once-per-install nudge into an every-time nag.
+      created_at: typeof raw.created_at === "string" ? raw.created_at : void 0,
+      nudges: raw.nudges && typeof raw.nudges === "object" ? raw.nudges : void 0,
+      decisions_count: typeof raw.decisions_count === "number" ? raw.decisions_count : void 0
     };
   } catch {
     return null;
@@ -482,7 +548,8 @@ function ensureState() {
     anon_id: randomUUID3(),
     tier: "free",
     api_key: null,
-    mandate: { payees: [], categories: ["*"], currency: "USD", perTxMax: 2500, maxTotal: 1e4 }
+    mandate: { payees: [], categories: ["*"], currency: "USD", perTxMax: 2500, maxTotal: 1e4 },
+    created_at: (/* @__PURE__ */ new Date()).toISOString()
   };
   try {
     writeConfig(config);
@@ -504,7 +571,7 @@ function resolveMandateRules(cfg) {
 }
 
 // src/telemetry.ts
-var CLIENT_VERSION = true ? "0.1.10" : "dev";
+var CLIENT_VERSION = true ? "0.1.12" : "dev";
 var currentShell = "mcp";
 function setTelemetryShell(shell) {
   currentShell = shell;
@@ -627,7 +694,7 @@ function requestUpgrade() {
 }
 
 // src/provision.ts
-var CLIENT_VERSION2 = true ? "0.1.10" : "dev";
+var CLIENT_VERSION2 = true ? "0.1.12" : "dev";
 function provisionEnabled() {
   const v = (process.env.FIDACY_DISABLE_PROVISION ?? "").trim().toLowerCase();
   return !(v === "1" || v === "true" || v === "yes");
@@ -661,6 +728,55 @@ async function autoProvision() {
     return "failed";
   }
 }
+
+// src/nudges.ts
+function nudgeOnce(key) {
+  const cfg = readConfig();
+  if (!cfg) return false;
+  if (cfg.nudges?.[key]) return false;
+  cfg.nudges = { ...cfg.nudges ?? {}, [key]: true };
+  try {
+    writeConfig(cfg);
+  } catch {
+    return false;
+  }
+  return true;
+}
+function bumpDecisionCount() {
+  const cfg = readConfig();
+  if (!cfg) return 0;
+  const n = (cfg.decisions_count ?? 0) + 1;
+  cfg.decisions_count = n;
+  try {
+    writeConfig(cfg);
+  } catch {
+  }
+  return n;
+}
+function installAgeDays() {
+  const t = Date.parse(readConfig()?.created_at ?? "");
+  if (Number.isNaN(t)) return 0;
+  return Math.floor((Date.now() - t) / 864e5);
+}
+function decisionNudge(status, violatedRule, upgradeToolName) {
+  const count = bumpDecisionCount();
+  if (status === "DENY" && violatedRule?.startsWith("duplicate_invoice") && nudgeOnce("bec_catch")) {
+    return `That was a duplicate-invoice (BEC) catch \u2014 the #1 payment fraud. On a free account every block like this is server-signed and anchored to Bitcoin: court-grade evidence. Call the ${upgradeToolName} tool to start.`;
+  }
+  if (status === "DENY" && nudgeOnce("first_deny")) {
+    return `Fidacy just blocked this for you \u2014 for server-signed, anchored proof of every block (free account, local history migrates), call the ${upgradeToolName} tool.`;
+  }
+  if (count === 10 && nudgeOnce("milestone_10")) {
+    return `That's 10 actions gated on this install. For a signed, Bitcoin-anchored history of all of them (free account), call the ${upgradeToolName} tool.`;
+  }
+  return null;
+}
+function weekOneBootNudge(upgradeToolName) {
+  if (installAgeDays() >= 7 && nudgeOnce("week_1")) {
+    return ` One week protected \u2014 anchor your history to Bitcoin with a free account: the ${upgradeToolName} tool starts it.`;
+  }
+  return null;
+}
 export {
   DevFidacyCore,
   FileAuditStore,
@@ -669,12 +785,15 @@ export {
   ReferenceRail,
   autoProvision,
   canonInvoice,
+  decisionNudge,
   ensureState,
   evaluate,
   httpRedeem,
+  installAgeDays,
   loadOrGenerateKeyPair,
   lookalikePayee,
   makeCore,
+  nudgeOnce,
   publicKeyPem,
   readConfig,
   recordAgentActive,
@@ -688,5 +807,6 @@ export {
   upgradeUrl,
   validateRequest,
   verify,
-  verifyGrant
+  verifyGrant,
+  weekOneBootNudge
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fidacy/mcp",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Fidacy action firewall for AI agents. Mandate-gated payment authorization as an MCP server.",
   "license": "Apache-2.0",
   "homepage": "https://fidacy.com",