indelible-mcp 4.3.1 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "indelible-mcp",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "description": "Blockchain-backed memory and code storage for Claude Code. Save AI conversations and source code permanently on BSV.",
   "type": "module",
   "main": "src/index.js",
@@ -11,6 +11,7 @@
     "src/"
   ],
   "scripts": {
+    "test": "node --test test/*.test.js",
     "start": "node src/index.js",
     "build": "bun build --compile src/index.js --outfile dist/indelible.exe",
     "build:all": "bun build --compile --target=bun-windows-x64 src/index.js --outfile dist/indelible-win-x64.exe && bun build --compile --target=bun-linux-x64 src/index.js --outfile dist/indelible-linux-x64 && bun build --compile --target=bun-darwin-arm64 src/index.js --outfile dist/indelible-darwin-arm64"
@@ -33,7 +34,7 @@
   },
   "homepage": "https://indelible.one",
   "dependencies": {
-    "@bsv/sdk": "1.10.1",
+    "@bsv/sdk": "^2.1.0",
     "cross-keychain": "^1.1.0"
   }
 }

package/src/lib/api-client.js

@@ -7,9 +7,51 @@
 import { Transaction } from '@bsv/sdk'
 import { loadConfig } from './config.js'
 import * as spv from './spv.js'
+import { encryptSummary } from './summary.js'
+import { createAuthClient } from './wallet-brc100.js'
 
 const DEFAULT_API_URL = 'https://indelible.one'
 
+// ───────────────────────────────────────────────────────────────────────────
+// g-181 Phase 1 (V3.3): Tier 2 BRC-100 auto-detect with TTL cache + backoff.
+// Mirrors mcp-server/lib/api.js logic exactly.
+// ───────────────────────────────────────────────────────────────────────────
+const TIER2_CACHE_TTL_MS = 5 * 60 * 1000
+const TIER2_BACKOFF_TTL_MS = 30 * 1000
+const TIER2_BACKOFF_THRESHOLD = 3
+
+const tier2Cache = new Map()
+const tier2TransientFailures = new Map()
+
+function getTier2Cached(apiUrl) {
+  const e = tier2Cache.get(apiUrl)
+  if (!e) return null
+  if (Date.now() - e.ts > TIER2_CACHE_TTL_MS) { tier2Cache.delete(apiUrl); return null }
+  return e.supported
+}
+
+function setTier2Cached(apiUrl, supported) {
+  tier2Cache.set(apiUrl, { supported, ts: Date.now() })
+  if (supported) tier2TransientFailures.delete(apiUrl)
+}
+
+function isInTransientBackoff(apiUrl) {
+  const f = tier2TransientFailures.get(apiUrl)
+  if (!f || f.count < TIER2_BACKOFF_THRESHOLD) return false
+  if (Date.now() - f.since > TIER2_BACKOFF_TTL_MS) {
+    tier2TransientFailures.delete(apiUrl)
+    return false
+  }
+  return true
+}
+
+function recordTransientFailure(apiUrl) {
+  const f = tier2TransientFailures.get(apiUrl) || { count: 0, since: Date.now() }
+  f.count += 1
+  if (f.count === TIER2_BACKOFF_THRESHOLD) f.since = Date.now()
+  tier2TransientFailures.set(apiUrl, f)
+}
+
 function getApiUrl() {
   const config = loadConfig()
   return config?.api_url || DEFAULT_API_URL
@@ -70,9 +112,72 @@ export async function register(address, apiKey) {
 /**
  * Index a session on server for web app retrieval.
  * Called after successful broadcast — best effort, doesn't block save.
+ *
+ * g-181 Phase 1 (V3.3): tries BRC-100 Tier 2 first (when wif provided +
+ * server supports), falls back to Bearer (Tier 1) on 404 or after 3
+ * consecutive transient failures (30s backoff).
+ *
+ * @param {object} sessionData - session payload to index
+ * @param {object} config - loaded config (api_key, auth_mode, etc.)
+ * @param {string} [wif] - optional WIF for Tier 2 BRC-100 auth
  */
-export async function indexSession(sessionData, config) {
-  const res = await fetch(`${getApiUrl()}/api/cli/index-session`, {
+export async function indexSession(sessionData, config, wif) {
+  const apiUrl = getApiUrl()
+  const mode = config?.auth_mode || 'auto'
+
+  // tier1 forced or no WIF available: skip Tier 2 entirely
+  if (mode === 'tier1' || !wif) return tier1IndexSession(sessionData, config, apiUrl)
+
+  const cached = getTier2Cached(apiUrl)
+  const inBackoff = isInTransientBackoff(apiUrl)
+  const shouldTryT2 = mode === 'tier2' || cached === true || (cached === null && !inBackoff)
+
+  if (shouldTryT2) {
+    try {
+      const auth = createAuthClient(wif)
+      const res = await auth.fetch(`${apiUrl}/api/cli/v2/index-session`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(sessionData),
+      })
+      if (res.ok) {
+        setTier2Cached(apiUrl, true)
+        return res.json()
+      }
+      if (res.status === 404) {
+        // Pack-V2 fix (Gremlin attack 5): distinguish route-missing from handler-404
+        const tier2Header = res.headers.get('X-Tier2-Supported')
+        let bodyCode = null
+        try { const j = await res.clone().json(); bodyCode = j?.code || null } catch {}
+        const isRouteMissing = tier2Header === 'false' || (!bodyCode && tier2Header !== 'true')
+        if (isRouteMissing) {
+          setTier2Cached(apiUrl, false)
+        }
+        if (mode === 'tier2') {
+          throw new Error('Tier 2 forced but server returned 404')
+        }
+      } else if (res.status >= 500) {
+        recordTransientFailure(apiUrl)
+        if (mode === 'tier2') throw new Error(`Tier 2 forced but server returned ${res.status}`)
+      } else {
+        if (mode === 'tier2') throw new Error(`Tier 2 forced but server returned ${res.status}`)
+      }
+    } catch (err) {
+      if (mode === 'tier2') throw err
+      const is404 = err?.status === 404 || /404|not found/i.test(err?.message || '')
+      if (is404 && !err?.responseCode) {
+        setTier2Cached(apiUrl, false)
+      } else {
+        recordTransientFailure(apiUrl)
+      }
+    }
+  }
+
+  return tier1IndexSession(sessionData, config, apiUrl)
+}
+
+async function tier1IndexSession(sessionData, config, apiUrl) {
+  const res = await fetch(`${apiUrl}/api/cli/index-session`, {
     method: 'POST',
     headers: getHeaders(config),
     body: JSON.stringify(sessionData),
@@ -141,23 +246,37 @@ export async function commitSession(session, wif) {
         protocol: 'indelible.claude-code',
         encrypted: session.encrypted
       }
-      const { txHex, txId, changeUtxos } = await spv.buildOpReturnTxWithChange(wif, utxos, JSON.stringify(payload))
-      await spv.broadcastTx(txHex)
+      const { txHex, txId, changeUtxos, fee, txSize } = await spv.buildOpReturnTxWithChange(wif, utxos, JSON.stringify(payload))
+      const writeReceipt = await spv.broadcastTx(txHex)  // SaveResult: { txid, via, source, federation, confirmed, bridge }
+
+      // g-110: encrypt summary with AAD=txId after broadcast (txId now known).
+      // Plaintext summary is dropped from the index POST entirely.
+      let summaryEnc = null
+      if (session.summary) {
+        try {
+          summaryEnc = encryptSummary(session.summary, wif, txId)
+        } catch {
+          // proceed without summary_enc — tx already on chain, indexing is best-effort
+        }
+      }
 
       // Index session for usage tracking
+      // g-181: pass WIF for Tier 2 BRC-100 auth (auto-detect with Bearer fallback)
       await indexSession({
         txId,
         address: session.address,
         encrypted: session.encrypted,
         session_id: session.session_id,
         prev_session_id: session.prev_session_id,
-        summary: session.summary,
+        summary_enc: summaryEnc,
         message_count: session.message_count,
         save_type: session.type || 'full',
         timestamp: new Date().toISOString()
-      }, config)
+      }, config, wif)
 
-      return { success: true, txId, changeUtxos }
+      // g-314: the Save Receipt — the full sovereign flow, surfaced "out loud".
+      const receipt = buildReceipt(writeReceipt, { txId, fee, txSize })
+      return { success: true, txId, changeUtxos, receipt }
     }
   } catch (err) {
     if (err.message.includes('save limit')) throw err
@@ -167,6 +286,55 @@ export async function commitSession(session, wif) {
   throw new Error('No UTXOs available. Fund your wallet or check gateway connection.')
 }
 
+/**
+ * g-314: assemble a Save Receipt from a broadcastTx write-result + build info.
+ * Shared by commitSession and the direct-broadcast save tools (save_file/project/...)
+ * so the receipt shape never drifts between save paths.
+ * @param {object} writeResult - the object returned by spv.broadcastTx
+ * @param {{txId:string, fee:number, txSize:number}} build
+ */
+export function buildReceipt (writeResult, { txId, fee, txSize }) {
+  const w = writeResult || {}
+  return {
+    txid: txId,
+    satCost: fee,
+    sizeBytes: txSize,
+    readSource: 'bridge',                  // getUtxos + per-input getRawTx are bridge-only (sovereign)
+    writeVia: w.via || 'bridge',
+    source: w.source || null,              // which hop the bridge's waterfall used: sovereign | arc | woc
+    bridge: w.bridge || null,              // which federation bridge accepted it
+    federation: w.federation || null,      // { bridges, totalBsvPeers, confirmations[] }
+    confirmed: !!w.confirmed,
+    status: 'committed'
+  }
+}
+
+/**
+ * g-314: render the Save Receipt "out loud" — the full sovereign flow as one
+ * block. Shows the read side + write side + which bridge/hop, the sat cost, and
+ * the FULL (untruncated) txid. Used by the CLI and the MCP-in-IDE save response.
+ * @param {object} r - the `receipt` object returned by commitSession
+ * @returns {string}
+ */
+export function formatSaveReceipt (r) {
+  if (!r) return ''
+  const hop = r.source === 'sovereign' ? 'your sovereign node'
+    : r.source === 'arc' ? 'ARC (break-glass)'
+    : r.source === 'woc' ? 'WhatsOnChain (last resort)'
+    : (r.bridge ? `bridge ${r.bridge}` : 'federation')
+  const fedN = (r.federation && typeof r.federation.bridges === 'number') ? r.federation.bridges : null
+  const costLine = (typeof r.satCost === 'number')
+    ? `   cost:    ${r.satCost} sats (${r.sizeBytes} bytes)` : null
+  return [
+    '📜 Save Receipt',
+    '   read:    federation bridge → sovereign indexer',
+    `   write:   ${hop}${fedN != null ? ` · ${fedN} bridge${fedN === 1 ? '' : 's'} confirmed` : ''}`,
+    costLine,
+    `   txid:    ${r.txid}`,
+    `   status:  ${r.confirmed ? 'confirmed' : 'broadcast'} (via ${r.writeVia})`
+  ].filter(Boolean).join('\n')
+}
+
 /**
  * Get latest sessions for an address
  * Scans address history via SPV bridge — no remote fallback

package/src/lib/save-log.js

@@ -0,0 +1,93 @@
+/**
+ * g-314: the Save Log — a persistent, append-only ledger of every save (foreground
+ * AND background auto-save), so a save is never silent. Lives at
+ * ~/.indelible/save-log.jsonl, one JSON line per save. Powers:
+ *   - background-auto-save surfacing in the IDE (post-compact-restore reads
+ *     UNSURFACED auto entries and injects their receipts into context), and
+ *   - the web "save-log" ledger (reads the same file).
+ * Every function is fail-soft — logging must NEVER break or block a save.
+ */
+import { appendFileSync, readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
+
+const DIR = join(homedir(), '.indelible')
+const LOG = join(DIR, 'save-log.jsonl')
+
+function ensureDir () { try { if (!existsSync(DIR)) mkdirSync(DIR, { recursive: true }) } catch {} }
+
+/**
+ * Append a save receipt to the ledger. Never throws.
+ * @param {object} receipt - the receipt from commitSession/buildReceipt
+ * @param {object} [meta] - { saveType, trigger:'interactive'|'auto', label }
+ */
+export function appendReceipt (receipt, meta = {}) {
+  if (!receipt || !receipt.txid) return
+  try {
+    ensureDir()
+    const entry = {
+      ts: new Date().toISOString(),
+      txid: receipt.txid,
+      satCost: receipt.satCost ?? null,
+      source: receipt.source || null,           // sovereign | arc | woc — which hop the bridge used
+      bridge: receipt.bridge || null,
+      confirmed: !!receipt.confirmed,
+      readSource: receipt.readSource || null,
+      saveType: meta.saveType || null,          // full | delta | file | project | diary
+      trigger: meta.trigger || 'interactive',   // interactive | auto (background/hook)
+      label: meta.label || null,
+      surfaced: false                           // has the IDE shown this entry yet?
+    }
+    appendFileSync(LOG, JSON.stringify(entry) + '\n')
+  } catch { /* never break a save on logging */ }
+}
+
+/** Read the whole ledger (oldest first). Returns []. */
+export function readAll () {
+  try {
+    if (!existsSync(LOG)) return []
+    return readFileSync(LOG, 'utf8').split('\n').filter(Boolean)
+      .map(l => { try { return JSON.parse(l) } catch { return null } }).filter(Boolean)
+  } catch { return [] }
+}
+
+/** Recent N entries (oldest first within the window). */
+export function readRecent (n = 25) { return readAll().slice(-n) }
+
+/** Background auto-saves the IDE hasn't shown yet. */
+export function readUnsurfaced () { return readAll().filter(e => !e.surfaced && e.trigger === 'auto') }
+
+/** Mark the given txids surfaced so the IDE doesn't re-show them. */
+export function markSurfaced (txids) {
+  try {
+    const set = new Set(txids)
+    const all = readAll()
+    let changed = false
+    for (const e of all) { if (set.has(e.txid) && !e.surfaced) { e.surfaced = true; changed = true } }
+    if (changed) writeFileSync(LOG, all.map(e => JSON.stringify(e)).join('\n') + '\n')
+  } catch { /* non-fatal */ }
+}
+
+function hopLabel (e) {
+  return e.source === 'sovereign' ? 'your sovereign node'
+    : e.source === 'arc' ? 'ARC (break-glass)'
+    : e.source === 'woc' ? 'WhatsOnChain (last resort)'
+    : (e.bridge || 'federation')
+}
+
+/**
+ * Read + render any UNSURFACED background auto-saves as an IDE block, and mark
+ * them surfaced. Returns '' if none. Called by post-compact-restore so a save
+ * that happened while you were away isn't silent — it shows "out loud" on restore.
+ */
+export function renderUnsurfacedBlock () {
+  const entries = readUnsurfaced()
+  if (!entries.length) return ''
+  markSurfaced(entries.map(e => e.txid))
+  const lines = ['# 📜 Saved while you were away (background auto-save)']
+  for (const e of entries) {
+    const cost = e.satCost != null ? `${e.satCost} sats` : '—'
+    lines.push(`- ${e.saveType || 'save'} · ${hopLabel(e)} · ${cost} · ${e.confirmed ? 'confirmed' : 'broadcast'} · txid ${e.txid}`)
+  }
+  return lines.join('\n')
+}

package/src/lib/spv.js

@@ -131,9 +131,18 @@ async function getBridges() {
 
 async function spvFetch(path, options = {}) {
   const bridges = await getBridges()
+  // Read-affinity (g-314): if we just broadcast to a bridge, try IT first — it holds the
+  // fresh tx in its mempool — before normal failover. Prevents the cross-bridge gossip
+  // race from mis-reading a just-broadcast tx as missing (false ghost).
+  const sticky = getStickyBridge()
+  let ordered = bridges
+  if (sticky) {
+    const pinned = bridges.filter(b => b.url === sticky.url)
+    if (pinned.length) ordered = [...pinned, ...bridges.filter(b => b.url !== sticky.url)]
+  }
   let lastError = null
 
-  for (const bridge of bridges) {
+  for (const bridge of ordered) {
     if (!isBridgeHealthy(bridge.url)) continue
 
     try {
@@ -206,44 +215,20 @@ export async function getTx(txid) {
 }
 
 export async function getRawTx(txid) {
+  // Sovereign-only: the bridge serves raw hex from our node/indexer (mempool + mined).
+  // No WhatsOnChain fallback — the client never reads tx data from a third party.
   try {
     const res = await spvFetch(`/api/tx/${txid.trim()}/hex`)
     if (res.ok) return res.text()
   } catch {}
-
-  // WoC fallback for unconfirmed/uncached txs
-  const wocRes = await fetch(`https://api.whatsonchain.com/v1/bsv/main/tx/${txid.trim()}/hex`)
-  if (wocRes.ok) return wocRes.text()
-
   throw new Error(`Failed to get raw tx hex for ${txid}`)
 }
 
-/**
- * Broadcast via ARC (GorillaPool) — direct to Teranode propagation service.
- * Primary broadcast path. No API key needed.
- */
-async function broadcastViaArc(rawTxHex) {
-  const t0 = Date.now()
-  try {
-    const res = await fetch('https://arc.gorillapool.io/v1/tx', {
-      method: 'POST',
-      signal: AbortSignal.timeout(10000),
-      headers: { 'Content-Type': 'text/plain' },
-      body: rawTxHex
-    })
-    const elapsed = Date.now() - t0
-    if (res.ok) {
-      const result = await res.json()
-      process.stderr.write(`[MCP] ARC broadcast OK — txid: ${result.txid} (${elapsed}ms)\n`)
-      return { txid: result.txid, via: 'arc' }
-    }
-    const body = await res.text().catch(() => '')
-    throw new Error(`ARC HTTP ${res.status} — ${body.slice(0, 200)}`)
-  } catch (err) {
-    process.stderr.write(`[MCP] ARC broadcast FAIL: ${err.message} (${Date.now() - t0}ms)\n`)
-    throw err
-  }
-}
+// ── No ARC in the client ──────────────────────────────────────────────
+// The client is SOVEREIGN-ONLY: broadcastTx hands the signed tx to the federation
+// bridge ONLY, and the bridge owns the ARC break-glass internally (node → P2P →
+// ARC → WoC, each txStatus-gated). There is deliberately NO third-party broadcast
+// endpoint in the customer client. See broadcastTx + 6-19.md.
 
 /**
  * Broadcast via federation bridges (fallback path).
@@ -268,7 +253,7 @@ async function broadcastViaBridges(rawTxHex) {
         const result = await res.json()
         recordSuccess(bridge.url)
         process.stderr.write(`[MCP]   ${bridge.name} OK (${elapsed}ms)\n`)
-        return result
+        return { ...result, _bridge: bridge }  // tag winning bridge → sticky affinity + receipt
       }
       const body = await res.text().catch(() => '')
       recordFailure(bridge.url)
@@ -290,32 +275,59 @@ async function broadcastViaBridges(rawTxHex) {
   }
 }
 
+// Read-affinity (g-314): after a broadcast lands on a bridge, pin reads to THAT bridge
+// briefly so an immediate read-back hits the mempool that actually has the tx — instead
+// of racing cross-bridge gossip and mis-reading a fresh tx as missing (false ghost).
+let _stickyBridge = null  // { url, name, until }
+const STICKY_WINDOW_MS = 5000
+function setStickyBridge (b) { _stickyBridge = { url: b.url, name: b.name, until: Date.now() + STICKY_WINDOW_MS } }
+export function getStickyBridge () {
+  if (_stickyBridge && Date.now() < _stickyBridge.until) return _stickyBridge
+  _stickyBridge = null
+  return null
+}
+
 /**
- * Broadcast raw transaction — ARC first (Teranode pipe), bridges as fallback.
+ * Broadcast a raw transaction — SOVEREIGN-FIRST, via the federation bridge ONLY.
  *
- * Primary:  MCP → ARC (GorillaPool) → Teranode propagation → miners
- * Fallback: MCP → Federation bridges → BSV P2P network
+ * The client does NOT call ARC/WhatsOnChain directly. It hands the signed tx to the
+ * bridge, which runs the deployed sovereign waterfall internally:
+ *   our node → P2P → ARC (break-glass) → WoC (last resort), each verified.
+ * If the whole federation is unreachable we FAIL LOUD — sovereign-first means we never
+ * silently route around the fleet to a third party from the client (g-314 / 6-19.md).
+ *
+ * @param {string} rawTxHex - Serialized transaction hex
+ * @returns {Promise<{txid, via, source, federation, confirmed, bridge}>} write-side SaveResult
  */
 export async function broadcastTx(rawTxHex) {
-  const t0 = Date.now()
-
-  // Primary: ARC → Teranode
-  try {
-    const result = await broadcastViaArc(rawTxHex)
-    process.stderr.write(`[MCP] Broadcast complete via ARC in ${Date.now() - t0}ms\n`)
-    return result
-  } catch (arcErr) {
-    process.stderr.write(`[MCP] ARC failed, falling back to bridges...\n`)
-  }
-
-  // Fallback: Federation bridges → BSV P2P
-  try {
-    const result = await broadcastViaBridges(rawTxHex)
-    process.stderr.write(`[MCP] Broadcast complete via bridges in ${Date.now() - t0}ms\n`)
-    return result
-  } catch (bridgeErr) {
-    throw new Error(`Broadcast failed — ARC and all bridges down: ${bridgeErr.message}`)
+  const MAX_RETRIES = 3
+  let lastErr
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    const t0 = Date.now()
+    try {
+      const result = await broadcastViaBridges(rawTxHex)
+      const winner = result._bridge
+      if (winner) setStickyBridge(winner)  // read-affinity for the next reads
+      process.stderr.write(`[MCP] Broadcast complete via federation (source=${result.source || 'bridge'}) in ${Date.now() - t0}ms\n`)
+      return {
+        txid: result.txid,
+        via: 'bridge',
+        source: result.source || null,          // sovereign | arc | woc — which hop the bridge's waterfall used
+        federation: result.federation || null,  // { bridges, totalBsvPeers, confirmations[] }
+        confirmed: !!result.confirmed,
+        bridge: winner ? winner.name : null
+      }
+    } catch (bridgeErr) {
+      lastErr = bridgeErr
+      if (attempt < MAX_RETRIES) {
+        const delay = attempt * 2000
+        process.stderr.write(`[MCP] Federation unreachable (attempt ${attempt}/${MAX_RETRIES}) — retrying in ${delay}ms...\n`)
+        await new Promise(r => setTimeout(r, delay))
+      }
+    }
   }
+  // FAIL LOUD — never fall back to a third party from the client machine.
+  throw new Error(`Save NOT committed — federation unreachable after ${MAX_RETRIES} attempts: ${lastErr ? lastErr.message : 'unknown'}`)
 }
 
 /**
@@ -436,16 +448,22 @@ export async function buildOpReturnTxWithChange(wif, utxos, dataStr) {
   const txId = tx.id('hex')
   const txHex = tx.toHex()
 
-  // Calculate change for UTXO chaining
+  // Read the change the SDK ACTUALLY wrote during tx.fee() — never recompute it. tx.fee() sizes the
+  // change from a PRE-sign estimate; recomputing from the post-sign txHex length diverges by the
+  // signature-size estimate error (~1-2 sat/input), overstating change. The returned changeUtxos.value
+  // would then mismatch the real on-chain output, and the NEXT chained spend signs over a wrong amount
+  // → ARC 461 NULLFAIL. Read tx.outputs[changeIndex].satoshis instead.
   const txSize = txHex.length / 2
-  const fee = Math.ceil(txSize * 1)
-  const changeValue = totalInput - fee
+  let changeIdx = tx.outputs.findIndex(o => o.change)
+  if (changeIdx < 0) changeIdx = 1 // OP_RETURN added at 0, change at 1 (deterministic build order)
+  const changeValue = tx.outputs[changeIdx] ? (tx.outputs[changeIdx].satoshis || 0) : 0
+  const fee = totalInput - tx.outputs.reduce((s, o) => s + (o.satoshis || 0), 0)
 
   const changeUtxos = []
   if (changeValue > 546) {
     changeUtxos.push({
       tx_hash: txId,
-      tx_pos: 1,
+      tx_pos: changeIdx,
       value: changeValue
     })
   }
@@ -492,12 +510,15 @@ export async function buildPaymentTx(wif, utxos, payToAddress, satoshis) {
   const txId = tx.id('hex')
   const txHex = tx.toHex()
   const txSize = txHex.length / 2
-  const fee = Math.ceil(txSize)
-  const changeValue = totalInput - satoshis - fee
+  // Read the SDK's actual change/fee — don't recompute from txHex length (see buildOpReturnTxWithChange).
+  let changeIdx = tx.outputs.findIndex(o => o.change)
+  if (changeIdx < 0) changeIdx = 1 // payment at 0, change at 1 (deterministic build order)
+  const changeValue = tx.outputs[changeIdx] ? (tx.outputs[changeIdx].satoshis || 0) : 0
+  const fee = totalInput - tx.outputs.reduce((s, o) => s + (o.satoshis || 0), 0)
 
   const changeUtxos = []
   if (changeValue > 546) {
-    changeUtxos.push({ tx_hash: txId, tx_pos: 1, value: changeValue })
+    changeUtxos.push({ tx_hash: txId, tx_pos: changeIdx, value: changeValue })
   }
 
   return { txHex, txId, changeUtxos, fee, txSize, satoshis }
@@ -514,24 +535,30 @@ export function extractEncryptedFromTx(tx) {
 }
 
 /**
- * Check if a transaction was confirmed (mined into a block).
- * Uses WoC as the source of truth since it indexes confirmed txs.
+ * Check a tx's lifecycle via the bridge's SOVEREIGN /api/tx/:txid/status (mempool-aware),
+ * NOT a third-party indexer. Returns the full state so callers can tell mempool-pending
+ * from mined and never re-create a false ghost (g-314 / 6-19.md):
+ *   blockHeight > 0              → confirmed (mined)
+ *   blockHeight null + inMempool → pending — do NOT re-broadcast, do NOT ghost
+ *   exists === false             → never seen
  * @param {string} txid
- * @returns {Promise<{confirmed: boolean, blockHeight: number|null}>}
+ * @returns {Promise<{confirmed: boolean, blockHeight: number|null, inMempool: boolean, exists: boolean|null}>}
  */
 export async function checkConfirmation(txid) {
   try {
-    const res = await fetch(`https://api.whatsonchain.com/v1/bsv/main/tx/${txid.trim()}`, {
-      signal: AbortSignal.timeout(8000)
-    })
-    if (!res.ok) return { confirmed: false, blockHeight: null }
-    const tx = await res.json()
-    if (tx.blockheight && tx.blockheight > 0) {
-      return { confirmed: true, blockHeight: tx.blockheight }
+    const res = await spvFetch(`/api/tx/${txid.trim()}/status`)
+    const s = await res.json()
+    const blockHeight = (s.blockHeight === undefined ? null : s.blockHeight)
+    return {
+      confirmed: blockHeight !== null && blockHeight > 0,
+      blockHeight,
+      inMempool: !!s.inMempool,
+      exists: !!s.exists
     }
-    return { confirmed: false, blockHeight: null }
   } catch {
-    return { confirmed: false, blockHeight: null }
+    // Federation unreachable = UNKNOWN, not "unconfirmed". Caller must not treat
+    // this as "never mined" and ghost/re-broadcast on it.
+    return { confirmed: false, blockHeight: null, inMempool: false, exists: null }
   }
 }
 

package/src/lib/summary.js

@@ -0,0 +1,75 @@
+/**
+ * Session summary encryption (g-110).
+ * AES-256-GCM with txId bound as associated data — splice attempts fail tag verify.
+ * Helper returns { ok, text } | { ok: false, reason } so silent fallthrough is impossible.
+ *
+ * MIRROR of mcp-server/lib/summary.js — keep in sync. Difference: imports node:crypto with prefix.
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto'
+import { deriveKey } from './crypto.js'
+
+const TXID_REGEX = /^[0-9a-f]{64}$/i
+
+export const LOCK_PLACEHOLDER = {
+  missing: '🔒 (legacy save)',
+  missing_txid: '🔒 (no txid)',
+  no_wif: '🔒 (wallet locked)',
+  auth_tag: '🔒 (encrypted)',
+  corrupt: '🔒 (decrypt failed)',
+}
+
+export function encryptSummary(plaintext, wif, txId) {
+  if (!txId || typeof txId !== 'string' || !TXID_REGEX.test(txId)) {
+    throw new Error('encryptSummary: txId must be a 64-char hex string')
+  }
+  if (typeof plaintext !== 'string') {
+    throw new Error('encryptSummary: plaintext must be a string')
+  }
+  if (!wif) {
+    throw new Error('encryptSummary: wif required')
+  }
+
+  const key = deriveKey(wif)
+  const iv = randomBytes(12)
+  const cipher = createCipheriv('aes-256-gcm', key, iv)
+  cipher.setAAD(Buffer.from(txId, 'utf8'))
+
+  let encrypted = cipher.update(plaintext, 'utf8', 'base64')
+  encrypted += cipher.final('base64')
+  const tag = cipher.getAuthTag()
+
+  return `${iv.toString('base64')}:${tag.toString('base64')}:${encrypted}`
+}
+
+export function decryptSummaryOrLock(summary_enc, wif, expectedTxId) {
+  if (!summary_enc) return { ok: false, reason: 'missing' }
+  if (!wif) return { ok: false, reason: 'no_wif' }
+  if (!expectedTxId || typeof expectedTxId !== 'string' || !TXID_REGEX.test(expectedTxId)) {
+    return { ok: false, reason: 'missing_txid' }
+  }
+
+  try {
+    const parts = summary_enc.split(':')
+    if (parts.length !== 3) return { ok: false, reason: 'corrupt' }
+    const [ivB64, tagB64, ciphertext] = parts
+
+    const key = deriveKey(wif)
+    const iv = Buffer.from(ivB64, 'base64')
+    const tag = Buffer.from(tagB64, 'base64')
+
+    const decipher = createDecipheriv('aes-256-gcm', key, iv)
+    decipher.setAAD(Buffer.from(expectedTxId, 'utf8'))
+    decipher.setAuthTag(tag)
+
+    let decrypted = decipher.update(ciphertext, 'base64', 'utf8')
+    decrypted += decipher.final('utf8')
+
+    return { ok: true, text: decrypted }
+  } catch (e) {
+    if (/auth|tag|unsupported state/i.test(e.message)) {
+      return { ok: false, reason: 'auth_tag' }
+    }
+    return { ok: false, reason: 'corrupt' }
+  }
+}

package/src/lib/wallet-brc100.js

@@ -0,0 +1,42 @@
+/**
+ * BRC-100 client wallet for Indelible CLI (g-181 Phase 1).
+ *
+ * Mirror of mcp-server/lib/wallet-brc100.js with one difference:
+ * uses `ProtoWallet` instead of `CompletedProtoWallet` for compatibility
+ * with @bsv/sdk 1.10.1 (CLI's pinned version). `ProtoWallet` provides
+ * everything Phase 1 needs (getPublicKey, createSignature, verifySignature).
+ * `CompletedProtoWallet` (2.x+) adds methods we don't use until g-180.
+ *
+ * If the CLI's @bsv/sdk gets bumped to 2.x, this can switch to
+ * `CompletedProtoWallet` to match MCP exactly. No behavioral change either way
+ * for Phase 1 endpoints.
+ */
+import { PrivateKey, ProtoWallet, AuthFetch } from '@bsv/sdk'
+
+// Phase 1 assumption: single-WIF per process lifetime.
+// Pack-V2 fix (Gremlin attack 4): if a different WIF is passed after
+// initialization, throw loudly instead of silently returning wrong client.
+let cached = null
+let cachedWif = null
+
+export function createAuthClient(wif) {
+  if (!wif) throw new Error('createAuthClient: wif required')
+  if (cached) {
+    if (wif !== cachedWif) {
+      throw new Error(
+        'createAuthClient: WIF mismatch — singleton already initialized with a different key. ' +
+        'Wallet-switching is not supported in Phase 1. Restart the process to use a new WIF.'
+      )
+    }
+    return cached
+  }
+  const wallet = new ProtoWallet(PrivateKey.fromWif(wif))
+  const af = new AuthFetch(wallet)
+  cachedWif = wif
+  cached = { fetch: af.fetch.bind(af), wallet }
+  return cached
+}
+
+export function _resetAuthClientCache() {
+  cached = null
+}

package/src/tools/diary_save.js

@@ -12,7 +12,8 @@
 import { loadConfig, saveConfig, getWif } from '../lib/config.js'
 import { encrypt, sha256 } from '../lib/crypto.js'
 import * as spv from '../lib/spv.js'
-import { indexSession, checkProTier } from '../lib/api-client.js'
+import { indexSession, checkProTier, buildReceipt, formatSaveReceipt } from '../lib/api-client.js'
+import { appendReceipt } from '../lib/save-log.js'
 
 /**
  * @param {Object} options
@@ -96,6 +97,10 @@ export async function diarySave({ messages, summary }) {
     const broadcastResult = await spv.broadcastTx(txHex)
     const finalTxId = broadcastResult.txid || txId
 
+    // g-314: Save Receipt — surface "out loud" + log to the ledger.
+    const receipt = buildReceipt(broadcastResult, { txId: finalTxId, fee: null, txSize: txHex.length / 2 })
+    appendReceipt(receipt, { saveType: 'diary', trigger: 'interactive', label: diaryName })
+
     // Index on server for web app retrieval (best effort)
     try {
       await indexSession({
@@ -125,7 +130,8 @@ export async function diarySave({ messages, summary }) {
       prevSessionId,
       messageCount: messages.length,
       source: diaryName,
-      message: `${diaryName} exchange saved! ${messages.length} messages committed to blockchain.`
+      receipt,
+      message: `${diaryName} exchange saved! ${messages.length} messages committed to blockchain.\n\n${formatSaveReceipt(receipt)}`
     }
 
   } catch (error) {

package/src/tools/save_file.js

@@ -11,6 +11,8 @@ import { homedir } from 'node:os'
 import { loadConfig, saveConfig, getWif } from '../lib/config.js'
 import { encrypt, sha256 } from '../lib/crypto.js'
 import * as spv from '../lib/spv.js'
+import { buildReceipt, formatSaveReceipt } from '../lib/api-client.js'
+import { appendReceipt } from '../lib/save-log.js'
 
 const MAX_CHUNK_SIZE = 50000
 
@@ -57,6 +59,7 @@ export async function saveFile(filePath, options = {}) {
   try {
     let masterTxId
     let finalChangeUtxos = null
+    let masterReceipt = null
 
     if (encrypted.length <= MAX_CHUNK_SIZE) {
       const payload = {
@@ -79,6 +82,7 @@ export async function saveFile(filePath, options = {}) {
       cacheTx(txId, payload)
       masterTxId = result.txid || txId
       finalChangeUtxos = changeUtxos
+      masterReceipt = buildReceipt(result, { txId: masterTxId, fee, txSize })
     } else {
       // Chunked upload
       const chunks = []
@@ -145,6 +149,7 @@ export async function saveFile(filePath, options = {}) {
       cacheTx(txId, masterPayload)
       masterTxId = result.txid || txId
       finalChangeUtxos = masterChangeUtxos
+      masterReceipt = buildReceipt(result, { txId: masterTxId, fee: masterFee, txSize: masterTxSize })
     }
 
     // Track in config
@@ -161,6 +166,9 @@ export async function saveFile(filePath, options = {}) {
 
     const chunkCount = encrypted.length <= MAX_CHUNK_SIZE ? 1 : Math.ceil(encrypted.length / MAX_CHUNK_SIZE)
 
+    // g-314: Save Receipt — surface "out loud" + log to the ledger.
+    appendReceipt(masterReceipt, { saveType: 'file', trigger: 'interactive', label: filename })
+
     return {
       success: true,
       txId: masterTxId,
@@ -170,7 +178,8 @@ export async function saveFile(filePath, options = {}) {
       contentHash: `sha256:${contentHash}`,
       chunks: chunkCount,
       changeUtxos: finalChangeUtxos,
-      message: `File "${filename}" saved to blockchain. txId: ${masterTxId}${chunkCount > 1 ? ` (${chunkCount} chunks)` : ''}`
+      receipt: masterReceipt,
+      message: `File "${filename}" saved to blockchain. txId: ${masterTxId}${chunkCount > 1 ? ` (${chunkCount} chunks)` : ''}\n\n${formatSaveReceipt(masterReceipt)}`
     }
   } catch (error) {
     return { success: false, error: `Failed to save file: ${error.message}` }

package/src/tools/save_project.js

@@ -10,6 +10,8 @@ import { homedir } from 'node:os'
 import { loadConfig, saveConfig, getWif } from '../lib/config.js'
 import { encrypt, sha256 } from '../lib/crypto.js'
 import * as spv from '../lib/spv.js'
+import { buildReceipt, formatSaveReceipt } from '../lib/api-client.js'
+import { appendReceipt } from '../lib/save-log.js'
 
 const TX_CACHE_DIR = join(homedir(), '.indelible', 'tx-cache')
 
@@ -145,9 +147,13 @@ export async function saveProject(dirPath, options = {}) {
       wif, utxos, JSON.stringify(payload), 'INDELIBLE_PROJECT_BUNDLE'
     )
     process.stderr.write(`[indelible] save_project "${projectName}": ${fee} sats (${txSize} bytes)\n`)
-    await spv.broadcastTx(txHex)
+    const broadcastResult = await spv.broadcastTx(txHex)
     cacheTx(txId, payload)
 
+    // g-314: Save Receipt — surface "out loud" + log to the ledger.
+    const receipt = buildReceipt(broadcastResult, { txId, fee, txSize })
+    appendReceipt(receipt, { saveType: 'project', trigger: 'interactive', label: projectName })
+
     // Track in config
     const projects = config.project_txids || []
     projects.push({
@@ -165,7 +171,8 @@ export async function saveProject(dirPath, options = {}) {
       name: projectName,
       fileCount: allFiles.length,
       totalSize,
-      message: `Project "${projectName}" saved as single tx bundle. ${allFiles.length} files, ${totalSize} bytes. txId: ${txId}`
+      receipt,
+      message: `Project "${projectName}" saved as single tx bundle. ${allFiles.length} files, ${totalSize} bytes. txId: ${txId}\n\n${formatSaveReceipt(receipt)}`
     }
   } catch (error) {
     return {

package/src/tools/save_session.js

@@ -20,9 +20,11 @@ import { homedir } from 'node:os'
 import { execSync } from 'node:child_process'
 import { loadConfig, saveConfig, getWif } from '../lib/config.js'
 import { encrypt, sha256 } from '../lib/crypto.js'
+import { encryptSummary } from '../lib/summary.js'
 import { findCurrentTranscript, parseTranscript } from '../lib/transcript.js'
 import * as spv from '../lib/spv.js'
-import { indexSession, checkProTier } from '../lib/api-client.js'
+import { indexSession, checkProTier, buildReceipt, formatSaveReceipt } from '../lib/api-client.js'
+import { appendReceipt } from '../lib/save-log.js'
 import { saveFile } from './save_file.js'
 
 const CONTEXT_FILE = join(homedir(), '.indelible', 'indelible-context.jsonl')
@@ -554,6 +556,17 @@ export async function saveSession(transcriptPath, summary) {
     const broadcastResult = await spv.broadcastTx(txHex)
     const finalTxId = broadcastResult.txid || txId
 
+    // g-314: Save Receipt — the full sovereign flow, surfaced "out loud" + logged.
+    const receipt = buildReceipt(broadcastResult, { txId: finalTxId, fee, txSize })
+    appendReceipt(receipt, { saveType: isDelta ? 'delta' : 'full', trigger: 'interactive' })
+
+    // g-260: encrypt the summary with AAD=txId so the web can decrypt it and render a title.
+    // The server drops plaintext summary (g-110 zero-trust) — only summary_enc survives + is shown.
+    let summaryEnc = null
+    try {
+      summaryEnc = encryptSummary(session.summary, wif, finalTxId)
+    } catch { /* proceed without summary_enc — tx is already on chain, indexing is best-effort */ }
+
     // Index session on server for web app retrieval (best effort)
     try {
       await indexSession({
@@ -561,7 +574,7 @@ export async function saveSession(transcriptPath, summary) {
         address: config.address,
         session_id: sessionId,
         prev_session_id: prevSessionId,
-        summary: session.summary,
+        summary_enc: summaryEnc,
         message_count: session.message_count,
         save_type: isDelta ? 'delta' : 'full',
         encrypted,
@@ -575,7 +588,7 @@ export async function saveSession(transcriptPath, summary) {
         txId: finalTxId, address: config.address,
         session_id: sessionId,
         prev_session_id: prevSessionId,
-        summary: session.summary,
+        summary_enc: summaryEnc,
         message_count: session.message_count,
         save_type: isDelta ? 'delta' : 'full',
         timestamp: session.created_at
@@ -701,7 +714,8 @@ export async function saveSession(transcriptPath, summary) {
       summary: session.summary,
       memoryTxId,
       historyTxId,
-      message: `Session saved!${deltaInfo} committed to blockchain.${costInfo}${prevSessionId ? ' Linked to previous session.' : ' (First session)'}${memInfo}`
+      receipt,
+      message: `Session saved!${deltaInfo} committed to blockchain.${costInfo}${prevSessionId ? ' Linked to previous session.' : ' (First session)'}${memInfo}\n\n${formatSaveReceipt(receipt)}`
     }
   } catch (error) {
     return { success: false, error: `Failed to commit: ${error.message}` }

package/src/tools/save_style.js

@@ -14,6 +14,8 @@ import { existsSync } from 'fs'
 import { loadConfig, saveConfig, getWif } from '../lib/config.js'
 import { encrypt, sha256 } from '../lib/crypto.js'
 import * as spv from '../lib/spv.js'
+import { buildReceipt, formatSaveReceipt } from '../lib/api-client.js'
+import { appendReceipt } from '../lib/save-log.js'
 
 // ── Core Infrastructure Rules ────────────────────────────────────────
 // These are baked into EVERY style — presets and custom.
@@ -154,7 +156,11 @@ export async function saveStyle(rulesText, styleName, description) {
     }
 
     const { txHex, txId } = await spv.buildOpReturnTx(wif, utxos, JSON.stringify(payload))
-    await spv.broadcastTx(txHex)
+    const broadcastResult = await spv.broadcastTx(txHex)
+
+    // g-314: Save Receipt — surface "out loud" + log to the ledger.
+    const receipt = buildReceipt(broadcastResult, { txId: broadcastResult.txid || txId, fee: null, txSize: txHex.length / 2 })
+    appendReceipt(receipt, { saveType: 'style', trigger: 'interactive', label: styleName })
 
     // Store style txid in config for quick access
     await saveConfig({
@@ -170,7 +176,8 @@ export async function saveStyle(rulesText, styleName, description) {
       styleId,
       styleName,
       rulesLength: rulesText.length,
-      message: `Style "${styleName}" saved to blockchain. txId: ${txId}`
+      receipt,
+      message: `Style "${styleName}" saved to blockchain. txId: ${txId}\n\n${formatSaveReceipt(receipt)}`
     }
   } catch (error) {
     return { success: false, error: `Failed to broadcast style: ${error.message}` }

package/src/tools/setup_wallet.js

@@ -84,7 +84,7 @@ export async function setupWallet(apiUrl = DEFAULT_API_URL, importWif, pin) {
     address,
     api_key: apiKey,
     api_url: apiUrl,
-    spv_bridges: [{ url: 'http://155.138.238.167:8080', name: 'relay-gateway' }],
+    spv_bridges: [],  // single source of truth = getBridges' always-merged live SEED_BRIDGES (no dead-gateway seed)
     spv_api_key: '',
     created_at: new Date().toISOString()
   }