keychat-save 1.3.0 → 1.4.1

package/README.md

@@ -44,15 +44,60 @@ keychat-save load --txid <txid>
 keychat-save load --search "keyword"
 ```
 
+## RepoChain — whole git repositories
+
+`save` handles text. **RepoChain** puts an entire repository on chain: git history, working tree,
+untracked and gitignored files, and `node_modules`. Restoring needs nothing but your key — no
+GitHub, no npm registry, no cloud account.
+
+```bash
+# Full snapshot — git history + working tree + node_modules, in ONE transaction
+keychat-save repo backup ~/my-project
+
+# Routine save: only what changed since the last snapshot. Cheap.
+keychat-save repo delta ~/my-project
+
+# Rebuild it anywhere — replays the full chain and verifies every file
+keychat-save repo restore <txid> ./restored
+
+# Size and cost, broadcasts nothing
+keychat-save repo estimate ~/my-project
+
+keychat-save repo list
+```
+
+**Take a delta after every commit.** A full snapshot of a 34 MB repo costs ~7,300 Compute; a delta
+of the same repo after a few commits is ~20 Compute and one transaction. Reach for `backup` only
+when there is no snapshot yet, the chain has grown long, or `node_modules` churned.
+
+Every delta embeds the ordered txids of all its ancestors, so **one txid restores everything** —
+`restore` replays the root and each delta in order, then verifies the rebuilt tree against a hash
+of its full file manifest.
+
+Using an AI agent with terminal access? Just tell it **"save git repo to repochain"** and it runs
+the delta for you.
+
+### Why a whole tarball, not `git bundle`
+
+A bundle carries only committed history. It misses uncommitted work, gitignored files, the stash,
+and `node_modules` — which means a restore depends on the npm registry still serving every package
+at the same version. Packages get unpublished. RepoChain carries the lot.
+
 ## How it works
 
-Content is sealed with your identity key (ECIES) and broadcast as a transaction on BSV via [KeyChat](https://keychat.pro). Only your key can decrypt it. Saves are permanent and portable — load them on any device with your identity key.
+Content is sealed with your identity key (ECIES) and broadcast as a transaction on BSV via
+[KeyChat](https://keychat.pro). Only your key can decrypt it. Saves are permanent and portable —
+load them on any device with your identity key.
 
-Cost: 0.25 Compute (125 sats) minimum, scales with content size.
+Cost: 0.25 Compute (125 sats) minimum, scales with size. Miners charge 100 satoshis per KB, and the
+tool refuses to broadcast anything below that floor — a transaction under it is relayed and
+accepted, then never mined, and disappears hours later with no error.
 
 ## Web UI
 
-You can also save and load from the browser at [keychat.pro](https://keychat.pro) — click **KeyChain** in the sidebar.
+You can also browse this from the browser at [keychat.pro](https://keychat.pro): **KeyChain** in the
+sidebar for saves, **RepoChain** for repositories — including a one-click download that replays the
+whole chain into a `.tar.gz`.
 
 ## License
 

package/check-generated.mjs

@@ -0,0 +1,20 @@
+// Pre-publish guard: refuse to ship a hand-edited repo.mjs.
+//
+// The canonical source is sovereign-messenger/scripts/keychat-repo.mjs, and
+// this file is generated from it by that repo's scripts/sync-npm-package.mjs.
+// A stale copy here means publishing code we have already fixed upstream —
+// which is exactly how a known bug reaches users of `npx keychat-save`.
+import { readFileSync } from 'node:fs'
+
+const marker = 'GENERATED by sovereign-messenger'
+if (!readFileSync(new URL('./repo.mjs', import.meta.url), 'utf8').includes(marker)) {
+  console.error('repo.mjs is not the generated copy.')
+  console.error('Run `npm run sync:npm` in sovereign-messenger, then publish again.')
+  process.exit(1)
+}
+
+if (!readFileSync(new URL('./index.mjs', import.meta.url), 'utf8').includes('100 sats/KB mining floor')) {
+  console.error('index.mjs is missing the 100 sats/KB floor guard.')
+  console.error('Without it an underpaid save is accepted, never mined, and lost hours later.')
+  process.exit(1)
+}

package/index.mjs

@@ -70,10 +70,36 @@ async function getUnspent (address) {
     height: u.height
   }))
 }
+// ONE endpoint, TWO response contracts — normalise here so no caller has to know.
+//
+// The bridge answers in its own shape when our node can serve the tx:
+//     { outputs: [ { satoshis, script, index } ] }
+// When it CANNOT — the node is pruned with no -txindex, so getrawtransaction fails for
+// any confirmed tx in a discarded block — the web proxy falls back to WhatsOnChain and
+// returns WoC's body untouched:
+//     { vout: [ { value, n, scriptPubKey: { hex } } ] }
+//
+// Callers looked only at `tx.outputs`, so on the WoC shape they iterated an empty array
+// and reported "No OP_RETURN in tx." — a claim about the transaction, when the data was
+// right there under a different field name. Measured 2026-08-26: 37 of 66 real saves
+// unreadable. The share only grows, because a save falls to the WoC path once its block
+// is pruned OR once a later save spends its change.
+//
+// Diagnosed 2026-08-24 (pt2) and hot-patched in the npx cache; the patch was never
+// upstreamed, so publishing 1.4.0 replaced the cache with a clean copy and the bug came
+// back. Fix it HERE, in the shared fetch, not at the call sites.
 async function getTx (txid) {
   const res = await fetch(`${BRIDGE}/api/tx/${txid}`)
   if (!res.ok) throw new Error(`tx ${res.status}`)
-  return res.json()
+  const tx = await res.json()
+  if (!Array.isArray(tx.outputs) && Array.isArray(tx.vout)) {
+    tx.outputs = tx.vout.map(o => ({
+      satoshis: Math.round((o.value || 0) * 100_000_000),
+      script: o.scriptPubKey?.hex || '',
+      index: o.n
+    }))
+  }
+  return tx
 }
 async function getRawHex (txid) {
   const res = await fetch(`${BRIDGE}/api/tx/${txid}/hex`)
@@ -179,19 +205,31 @@ async function cmdSave (label, body) {
   const usable = utxos.filter(u => u.satoshis >= 125 && u.satoshis <= 500).sort((a, b) => b.satoshis - a.satoshis)
   if (!usable.length) throw new Error('No Compute UTXOs. Fund your address at keychat.pro and wait for packaging.')
 
-  const estBytes = 150 + cipherHex.length / 2 + 50
-  const rawFee = Math.ceil(estBytes * 100 / 1000)
-  const totalCost = Math.ceil(rawFee / SUB_UNIT_SATS) * SUB_UNIT_SATS
-  console.log(`  Cost: ${totalCost / 500} Compute (${totalCost} sats)`)
-
+  // EVERY INPUT MUST BE COUNTED. This was `150 + cipher + 50`, which ignored the
+  // ~148 bytes each P2PKH input adds — so adding inputs to cover the fee grew the
+  // tx without growing the estimate, and the round-up to 125 sats hid it until a
+  // body got big enough that it couldn't. A save that lands under 100 sats/KB is
+  // relayed, accepted, given a txid — and then NEVER MINED. It ages out of every
+  // mempool hours later and the content is gone. Observed on a 20,188-byte save
+  // that paid 2,000 sats: 99.07 sats/KB, nineteen satoshis short, lost.
+  const INPUT_BYTES = 148   // 36 outpoint + 1 len + ~107 script + 4 sequence
+  const OUTPUT_BYTES = 34   // change output, counted even when it lands at 0
+  const OP_RETURN_BYTES = cipherHex.length / 2 + 60
   const picked = []
   let sum = 0
-  for (const u of usable) {
+  let totalCost = 0
+  for (;;) {
+    const estBytes = 10 + picked.length * INPUT_BYTES + OP_RETURN_BYTES + OUTPUT_BYTES
+    totalCost = Math.ceil(Math.ceil(estBytes * 100 / 1000) / SUB_UNIT_SATS) * SUB_UNIT_SATS
+    if (picked.length > 0 && sum >= totalCost) break
+    if (picked.length >= usable.length) {
+      throw new Error(`Insufficient Compute. Need ${totalCost / 500}, have ${sum / 500}.`)
+    }
+    const u = usable[picked.length]
     picked.push(u)
     sum += u.satoshis
-    if (sum >= totalCost) break
   }
-  if (sum < totalCost) throw new Error(`Insufficient Compute. Need ${totalCost / 500}, have ${sum / 500}.`)
+  console.log(`  Cost: ${totalCost / 500} Compute (${totalCost} sats, ${picked.length} inputs)`)
 
   const tx = new Transaction()
   for (const u of picked) {
@@ -208,7 +246,20 @@ async function cmdSave (label, body) {
   }
   await tx.sign()
 
-  const txid = await broadcast(tx.toHex())
+  // Measure the SIGNED tx, not the estimate. Below 100 sats/KB the save looks
+  // successful and disappears hours later, so refusing here is always kinder
+  // than that silence.
+  const rawHex = tx.toHex()
+  const rate = (sum - changeSats) / (rawHex.length / 2 / 1000)
+  if (rate < 100) {
+    throw new Error(
+      `Fee too low: ${rate.toFixed(2)} sats/KB, under the 100 sats/KB mining floor. ` +
+      `NOT broadcast — a tx this cheap is accepted to mempool but never mined. Re-run.`
+    )
+  }
+  console.log(`  Fee:  ${sum - changeSats} sats / ${rawHex.length / 2} bytes = ${rate.toFixed(2)} sats/KB`)
+
+  const txid = await broadcast(rawHex)
 
   // Prepend new entry to local saves index
   const date = new Date().toISOString().slice(0, 10)
@@ -394,10 +445,14 @@ if (cmd === 'init') {
     if (args.includes('--search')) opts.search = args[args.indexOf('--search') + 1]
     await cmdLoad(opts)
   }
+} else if (cmd === 'repo' || cmd === 'repochain') {
+  // RepoChain — whole git repositories on chain, not just session text.
+  const { runRepo } = await import('./repo.mjs')
+  await runRepo(args)
 } else {
   console.log(`keychat-save — Save to BSV blockchain via KeyChat (keychat.pro)
 
-Commands:
+SAVES — text, sessions, notes:
   init                          Create identity (~/.keychat/identity.wif)
   save "label" "content"        Save content to chain
   save "label" --file path      Save file to chain
@@ -407,5 +462,15 @@ Commands:
   load --search "keyword"       Search saves
   load --txid <txid>            Load a specific save by txid (instant, no scan)
 
+REPOCHAIN — whole git repositories:
+  repo backup <path>            Full snapshot: git history, working tree, node_modules
+  repo delta <path>             Only what changed since the last snapshot (cheap, routine)
+  repo restore <txid> <dest>    Rebuild the repo — replays the whole chain
+  repo estimate <path>          Size and cost, broadcasts nothing
+  repo list                     Snapshots taken from this machine
+
+  Each snapshot is ONE transaction. A delta continues the chain automatically and
+  carries the ordered txids of every ancestor, so a single txid restores everything.
+
 Your data. Your key. Permanent on BSV.`)
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "keychat-save",
-  "version": "1.3.0",
-  "description": "Save and load files to BSV blockchain via KeyChat",
+  "version": "1.4.1",
+  "description": "Save sessions, files and whole git repositories to the BSV blockchain via KeyChat",
   "type": "module",
   "bin": {
     "keychat-save": "index.mjs"
@@ -12,11 +12,24 @@
   "dependencies": {
     "@bsv/sdk": "^1.0.0"
   },
-  "keywords": ["bsv", "blockchain", "keychat", "save", "encrypt", "bitcoin"],
+  "keywords": [
+    "bsv",
+    "blockchain",
+    "keychat",
+    "save",
+    "encrypt",
+    "bitcoin",
+    "git",
+    "backup",
+    "repochain"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/avaziri93/keychat-save"
   },
-  "homepage": "https://keychat.pro"
+  "homepage": "https://keychat.pro",
+  "scripts": {
+    "prepublishOnly": "node check-generated.mjs"
+  }
 }

package/repo.mjs

@@ -0,0 +1,680 @@
+// WHOLE-REPO SNAPSHOTS TO CHAIN — history, working tree and node_modules, in ONE transaction.
+//
+//   node scripts/keychat-repo.mjs delta    ~/dxs-bot          # DEFAULT — continues the chain
+//   node scripts/keychat-repo.mjs backup   ~/dxs-bot          # full snapshot, milestones only
+//   node scripts/keychat-repo.mjs estimate ~/dxs-bot          # sizes and cost, broadcasts nothing
+//   node scripts/keychat-repo.mjs restore  <txid> /tmp/restored
+//   node scripts/keychat-repo.mjs list
+//
+// DELTA IS THE ROUTINE SAVE. `delta` with no base txid continues the repo's chain from its
+// newest entry in ~/.keychat/repos.json. Full snapshot of sovereign-messenger is 33.87 MB and
+// 7,320 Compute; a delta of the same repo is ~96 KB and ~20 Compute in one transaction. Reach
+// for `backup` at milestones, or when a delta chain gets long or node_modules churns.
+//
+// WHY A TARBALL OF THE WHOLE DIRECTORY AND NOT `git bundle`. A bundle carries only committed
+// history. It misses (a) anything uncommitted, and these repos deploy straight from the working
+// tree, (b) gitignored files — `whitepaper.md` was invisible to git for four months, and (c) the
+// stash, which `--all` does not include. Tarring the directory captures .git, the worktree,
+// node_modules and the stash in one artifact.
+//
+// WHY node_modules IS INCLUDED. Arash's call, and it follows the sovereign-data-path rule:
+// needing `npm install` to rebuild puts the npm registry in the recovery path. Packages get
+// unpublished. Carrying them costs ~$2 a snapshot, which is not a reason to depend on a third
+// party.
+//
+// ONE TRANSACTION, NO CHUNKING. Genesis restored the protocol limits; there is no size cap to
+// design around. GorillaPool and TAAL both publish maxtxsizepolicy=100,000,000, and the bridge
+// fans every broadcast out to both in parallel, so a 34 MB repo goes to a miner whole. Our own
+// bitcoind still runs maxscriptsizepolicy=6000000 — a leftover sized for 5 MB attachment chunks —
+// so it will not relay these itself; ARC carries them and the node picks them up when mined.
+// Raising the node to match is a config edit plus a restart, deliberately not done here because
+// a bitcoind restart costs hours of message-relay lag.
+//
+// NO base64. keychat-save's encrypt path is UTF-8 only, which forces binary through base64 at
+// +33%. Here the tar bytes are encrypted directly, so the chain carries the archive itself.
+//
+// A REPO TX IS NOT A SESSION SAVE. It uses its own KREP prefix, so `keychat-save load` skips it:
+// otherwise every load would decrypt 34 MB into ~/.keychat/saves.json and every future save would
+// carry the snapshot in its bootstrap table.
+//
+// FUNDING IS A SEPARATE TX ON PURPOSE. The fee for a 34 MB tx is ~3.5M sats, which is ~7,100
+// Compute UTXOs at 500 sats each. Signing is O(inputs x output bytes) in the SDK — it rehashes
+// the whole output set per input — so paying that fee directly costs ~55 minutes of signing.
+// Consolidating into one exact-value output first and spending that makes the repo tx a
+// single-input tx: two broadcasts, ~30 seconds. The payload is never split.
+import { PrivateKey, Transaction, P2PKH, Script, EncryptedMessage, PublicKey, Utils } from '@bsv/sdk'
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const CONFIG_DIR = path.join(os.homedir(), '.keychat')
+const WIF_PATH = path.join(CONFIG_DIR, 'identity.wif')
+const BRIDGE = 'https://www.keychat.pro/api/bridge'
+const REPO_PREFIX = '4b524550' // "KREP" — deliberately not KSAV
+const VERSION = '01'
+const SATS_PER_COMPUTE = 500
+const SUB_UNIT = SATS_PER_COMPUTE / 4 // 125 sats = 0.25 Compute
+const FEE_PER_KB = 100
+const TMP = process.env.TMPDIR || '/tmp'
+
+const sh = (cmd, args, opts = {}) =>
+  execFileSync(cmd, args, { encoding: 'utf8', maxBuffer: 1 << 30, ...opts })
+
+const hex = bytes => Buffer.from(bytes).toString('hex')
+const feeFor = bytes => Math.ceil((bytes * FEE_PER_KB) / 1000)
+const roundToSubUnit = sats => Math.ceil(sats / SUB_UNIT) * SUB_UNIT
+
+function key () {
+  if (!fs.existsSync(WIF_PATH)) {
+    console.error(`no identity at ${WIF_PATH}`)
+    process.exit(1)
+  }
+  return PrivateKey.fromWif(fs.readFileSync(WIF_PATH, 'utf8').trim())
+}
+
+// ── bridge ───────────────────────────────────────────────────────
+async function getUnspent (address) {
+  const res = await fetch(`${BRIDGE}/api/address/${address}/unspent`)
+  if (!res.ok) throw new Error(`unspent ${res.status}`)
+  return (await res.json()).map(u => ({
+    txid: u.tx_hash || u.txid,
+    vout: u.tx_pos ?? u.vout,
+    satoshis: u.value ?? u.satoshis
+  }))
+}
+
+async function broadcast (rawHex) {
+  const res = await fetch(`${BRIDGE}/api/broadcast`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ rawTx: rawHex })
+  })
+  const text = await res.text()
+  if (!res.ok) throw new Error(`broadcast ${res.status}: ${text.slice(0, 300)}`)
+  try {
+    const p = JSON.parse(text)
+    return p.txid || p.hash || text
+  } catch { return text.replace(/"/g, '').trim() }
+}
+
+// `?raw=1` first: server.js caches /api/tx/:txid/hex FOREVER in memory, and pinning
+// 68 MB of hex in the live web server to satisfy a restore is not worth it. A query
+// string makes its isTxBody regex miss, so the request passes straight through.
+//
+// But that same regex miss also skips its WhatsOnChain fallback, which is the only
+// second source we have once a tx is mined. So fall back to the plain path on
+// failure — retrievability beats keeping the proxy cache tidy.
+async function getRawHex (txid) {
+  // Three sources, in order of sovereignty:
+  //   1. bridge ?raw=1  — our node, bypassing the web proxy's forever-cache.
+  //   2. bridge plain   — same node, but with the proxy's WoC fallback behind it.
+  //   3. WoC direct     — last resort, and it earns its place: our node is PRUNED
+  //      with no -txindex, so getrawtransaction CANNOT return a confirmed tx at
+  //      all. Every mined snapshot is therefore unfetchable from us, and with
+  //      only the first two sources a rate-limited proxy made the whole delta
+  //      chain unreplayable — which breaks restore, not just new deltas.
+  // 429 gets a backoff rather than being treated as absence; hammering a closed
+  // limiter is what turned a transient failure into a hard one.
+  const urls = [
+    `${BRIDGE}/api/tx/${txid}/hex?raw=1`,
+    `${BRIDGE}/api/tx/${txid}/hex`,
+    `https://api.whatsonchain.com/v1/bsv/main/tx/${txid}/hex`
+  ]
+  let wait = 500
+  for (let attempt = 0; attempt < 3; attempt++) {
+    for (const url of urls) {
+      let res
+      try { res = await fetch(url) } catch { continue }
+      if (res.status === 429) { await new Promise(r => setTimeout(r, wait)); continue }
+      if (!res.ok) continue
+      const ct = res.headers.get('content-type') || ''
+      const data = ct.includes('json') ? await res.json() : await res.text()
+      const h = (typeof data === 'string' ? data.replace(/"/g, '').trim() : data.hex)
+      if (h && /^[0-9a-f]+$/i.test(h)) return h
+    }
+    wait = Math.min(wait * 4, 8000)
+    await new Promise(r => setTimeout(r, wait))
+  }
+  throw new Error(`cannot fetch raw tx ${txid} from node, bridge or WoC`)
+}
+
+// ── OP_RETURN ────────────────────────────────────────────────────
+function buildOpReturn (parts) {
+  let s = '006a'
+  for (const part of parts) {
+    const len = part.length / 2
+    if (len < 76) s += len.toString(16).padStart(2, '0')
+    else if (len < 256) s += '4c' + len.toString(16).padStart(2, '0')
+    else if (len < 65536) {
+      s += '4d' + (len & 0xff).toString(16).padStart(2, '0') +
+        ((len >> 8) & 0xff).toString(16).padStart(2, '0')
+    } else {
+      s += '4e' +
+        (len & 0xff).toString(16).padStart(2, '0') +
+        ((len >> 8) & 0xff).toString(16).padStart(2, '0') +
+        ((len >> 16) & 0xff).toString(16).padStart(2, '0') +
+        ((len >>> 24) & 0xff).toString(16).padStart(2, '0')
+    }
+    s += part
+  }
+  return s
+}
+
+function extractParts (scriptHex) {
+  let pos = scriptHex.startsWith('006a') ? 4 : scriptHex.startsWith('6a') ? 2 : -1
+  if (pos < 0) return null
+  const parts = []
+  while (pos < scriptHex.length) {
+    const op = parseInt(scriptHex.substr(pos, 2), 16)
+    pos += 2
+    let len
+    if (op <= 75) len = op
+    else if (op === 0x4c) { len = parseInt(scriptHex.substr(pos, 2), 16); pos += 2 } else if (op === 0x4d) {
+      len = parseInt(scriptHex.substr(pos, 2), 16) |
+        (parseInt(scriptHex.substr(pos + 2, 2), 16) << 8)
+      pos += 4
+    } else if (op === 0x4e) {
+      len = parseInt(scriptHex.substr(pos, 2), 16) |
+        (parseInt(scriptHex.substr(pos + 2, 2), 16) << 8) |
+        (parseInt(scriptHex.substr(pos + 4, 2), 16) << 16) |
+        (parseInt(scriptHex.substr(pos + 6, 2), 16) << 24)
+      pos += 8
+    } else break
+    parts.push(scriptHex.substr(pos, len * 2))
+    pos += len * 2
+  }
+  return parts
+}
+
+// ── payload ──────────────────────────────────────────────────────
+function tarball (repoPath) {
+  const abs = path.resolve(repoPath.replace(/^~/, os.homedir()))
+  if (!fs.existsSync(abs)) throw new Error(`no such repo: ${abs}`)
+  const name = path.basename(abs)
+  const out = path.join(TMP, `keychat-repo-${name}.tgz`)
+  // -C so the archive holds `<name>/...` and restores into a directory, never loose files.
+  // COPYFILE_DISABLE keeps macOS from larding the archive with ._ AppleDouble entries.
+  sh('tar', ['czf', out, '-C', path.dirname(abs), name], {
+    env: { ...process.env, COPYFILE_DISABLE: '1' }
+  })
+  return { out, name, abs }
+}
+
+/** Refuse to inscribe anything secret-shaped — a repo tx is permanent and public. */
+function assertNoSecrets (abs) {
+  const bad = sh('find', [abs, '-maxdepth', '4', '-type', 'f',
+    '(', '-name', '*.wif', '-o', '-name', '*.pem', '-o', '-name', '.env',
+    '-o', '-name', 'seed.txt', '-o', '-name', '*.p12', '-o', '-name', '.platform-wallet.key',
+    '-o', '-name', '.testwallet.key', '-o', '-name', '.recipient.key', ')',
+    '-not', '-path', '*/node_modules/*'])
+    .split('\n').filter(Boolean)
+  if (bad.length) {
+    console.error('REFUSING TO SNAPSHOT — secret-shaped files inside the repo:')
+    for (const f of bad) console.error('   ' + f)
+    console.error('Secrets live in ~/.dxs-bot and ~/.keychat. Move them out and retry.')
+    process.exit(1)
+  }
+}
+
+/** [4-byte BE meta length][meta JSON][tar bytes] — meta rides inside the encryption. */
+function framePayload (meta, tar) {
+  const metaBuf = Buffer.from(JSON.stringify(meta), 'utf8')
+  const len = Buffer.alloc(4)
+  len.writeUInt32BE(metaBuf.length, 0)
+  return Buffer.concat([len, metaBuf, tar])
+}
+
+function unframePayload (buf) {
+  const metaLen = buf.readUInt32BE(0)
+  const meta = JSON.parse(buf.subarray(4, 4 + metaLen).toString('utf8'))
+  return { meta, tar: buf.subarray(4 + metaLen) }
+}
+
+// ── manifests ────────────────────────────────────────────────────
+// A manifest is `mode sha256 path` per file, sorted by path. It is NEVER stored
+// on chain: sovereign-messenger has 7,934 files, so a full manifest is ~1.01 MB —
+// recording a 3.6 KB change would cost ~200 Compute in overhead alone. Only the
+// sha256 OF the manifest travels (manifestRoot, 32 bytes), and restore recomputes
+// the manifest from the tree it rebuilt to check it. That verifies every file,
+// not just the archive, and catches a delta applied out of order.
+function buildManifest (dir) {
+  const entries = []
+  const walk = rel => {
+    const abs = path.join(dir, rel)
+    for (const name of fs.readdirSync(abs)) {
+      const r = rel ? path.join(rel, name) : name
+      const st = fs.lstatSync(path.join(abs, name))
+      if (st.isDirectory()) walk(r)
+      else if (st.isSymbolicLink()) entries.push([r, 'l', createHash('sha256').update(fs.readlinkSync(path.join(abs, name))).digest('hex')])
+      else if (st.isFile()) {
+        entries.push([r, (st.mode & 0o111) ? 'x' : 'f',
+          createHash('sha256').update(fs.readFileSync(path.join(abs, name))).digest('hex')])
+      }
+    }
+  }
+  walk('')
+  entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+  const map = new Map(entries.map(([p, m, s]) => [p, m + ' ' + s]))
+  const root = createHash('sha256')
+    .update(entries.map(([p, m, s]) => `${m} ${s} ${p}`).join('\n')).digest('hex')
+  return { map, root }
+}
+
+function diffManifest (base, cur) {
+  const changed = []
+  const deleted = []
+  for (const [p, v] of cur) if (base.get(p) !== v) changed.push(p)
+  for (const p of base.keys()) if (!cur.has(p)) deleted.push(p)
+  return { changed: changed.sort(), deleted: deleted.sort() }
+}
+
+// ── tx building ──────────────────────────────────────────────────
+// Inputs carry sourceTXID + explicit satoshis/lockingScript instead of a
+// sourceTransaction. Fetching parents would mean one bridge round-trip per input,
+// and 19,865 of this wallet's UTXOs share a single ~6.8 MB 200k-output splitter tx —
+// re-downloading it thousands of times is what made the first version unrunnable.
+function addP2PKHInput (tx, k, lockingScript, utxo) {
+  tx.addInput({
+    sourceTXID: utxo.txid,
+    sourceOutputIndex: utxo.vout,
+    unlockingScriptTemplate: new P2PKH().unlock(k, 'all', false, utxo.satoshis, lockingScript)
+  })
+}
+
+const INPUT_BYTES = 148 // 36 outpoint + 1 len + ~107 script + 4 sequence
+const OUTPUT_P2PKH_BYTES = 34
+
+/**
+ * Consolidate small Compute UTXOs into one output worth exactly `target` sats.
+ * Its own miner fee grows with each input added, so the pick converges rather
+ * than being solved in one shot.
+ */
+function planFunding (utxos, target) {
+  let n = 0
+  let sum = 0
+  for (;;) {
+    const bytes = 10 + n * INPUT_BYTES + OUTPUT_P2PKH_BYTES * 2
+    const need = target + roundToSubUnit(feeFor(bytes))
+    if (sum >= need && n > 0) return { picked: utxos.slice(0, n), sum, need }
+    if (n >= utxos.length) {
+      throw new Error(`insufficient Compute: need ~${(need / SATS_PER_COMPUTE).toFixed(2)}, ` +
+        `have ${(sum / SATS_PER_COMPUTE).toFixed(2)}`)
+    }
+    sum += utxos[n].satoshis
+    n++
+  }
+}
+
+// Above this many inputs, signing the payload tx directly gets expensive — the SDK
+// rehashes the whole output set per input — so the fee moves to a funding tx and the
+// payload tx becomes single-input. Below it, one tx is simpler AND safer: the funding
+// output is the only raceable step in the design (see the splitter incident), so a
+// delta small enough to skip it has nothing to lose.
+const DIRECT_MAX_INPUTS = 60
+
+/** Broadcast one OP_RETURN payload, funding it whichever way is cheaper. */
+async function publish (scriptHex, k, address, lockingScript, { dry = false } = {}) {
+  const opReturn = Script.fromHex(scriptHex)
+  const scriptBytes = scriptHex.length / 2
+  const utxos = (await getUnspent(address))
+    .filter(u => u.satoshis >= SUB_UNIT && u.satoshis <= SATS_PER_COMPUTE)
+    .sort((a, b) => b.satoshis - a.satoshis)
+
+  // Try single-tx first: n inputs, the OP_RETURN, and change.
+  let n = 0
+  let sum = 0
+  let fee = 0
+  while (n < DIRECT_MAX_INPUTS) {
+    fee = roundToSubUnit(feeFor(10 + n * INPUT_BYTES + 9 + scriptBytes + OUTPUT_P2PKH_BYTES))
+    if (sum >= fee && n > 0) break
+    if (n >= utxos.length) throw new Error('insufficient Compute')
+    sum += utxos[n].satoshis
+    n++
+  }
+
+  if (sum >= fee && n > 0 && n < DIRECT_MAX_INPUTS) {
+    const tx = new Transaction()
+    for (const u of utxos.slice(0, n)) addP2PKHInput(tx, k, lockingScript, u)
+    tx.addOutput({ lockingScript: opReturn, satoshis: 0 })
+    if (sum - fee > 0) tx.addOutput({ lockingScript, satoshis: sum - fee })
+    await tx.sign()
+    console.log(`payload tx    ${(tx.toHex().length / 2 / 1024).toFixed(1)} KB, ${n} inputs, ` +
+      `fee ${fee} sats = ${fee / SATS_PER_COMPUTE} Compute (single tx)`)
+    if (dry) return { txid: tx.id('hex'), funding: null, cost: fee / SATS_PER_COMPUTE, dry: true }
+    process.stdout.write('broadcasting ... ')
+    const txid = await broadcast(tx.toHex())
+    console.log(txid)
+    return { txid, funding: null, cost: fee / SATS_PER_COMPUTE }
+  }
+
+  // Too many inputs to sign against this payload — consolidate the fee first.
+  //
+  // This output is exactly the payload's fee, on a clean 125-sat boundary. An earlier
+  // version made it fee+1 to push it off that boundary, on the theory that isComputeUtxo()
+  // (`satoshis % 125 === 0`) would hide it from the splitter. That was wrong: the splitter
+  // triggers on `satoshis >= 1000` and never consulted isComputeUtxo, so the extra satoshi
+  // bought nothing and it ate two repo snapshots anyway. What actually protects this output
+  // is the splitter being deposits-only (src/messages/split.js) — it reads the parent tx,
+  // sees we signed it, and leaves our change alone.
+  const payloadFee = roundToSubUnit(feeFor(10 + INPUT_BYTES + 9 + scriptBytes))
+  const fundingValue = payloadFee
+  const { picked, sum: fsum, need } = planFunding(utxos, fundingValue)
+  const fundFee = need - fundingValue
+  console.log(`payload tx    ${((10 + INPUT_BYTES + 9 + scriptBytes) / 1048576).toFixed(2)} MB, ` +
+    `fee ${payloadFee} sats = ${payloadFee / SATS_PER_COMPUTE} Compute`)
+  console.log(`funding tx    ${picked.length} inputs, fee ${fundFee} sats`)
+  console.log(`total cost    ${(fundingValue + fundFee) / SATS_PER_COMPUTE} Compute\n`)
+
+  const fundTx = new Transaction()
+  for (const u of picked) addP2PKHInput(fundTx, k, lockingScript, u)
+  fundTx.addOutput({ lockingScript, satoshis: fundingValue })
+  if (fsum - fundingValue - fundFee > 0) {
+    fundTx.addOutput({ lockingScript, satoshis: fsum - fundingValue - fundFee })
+  }
+  process.stdout.write('signing funding tx ... ')
+  let t = Date.now()
+  await fundTx.sign()
+  console.log(`${((Date.now() - t) / 1000).toFixed(1)}s`)
+
+  const payTx = new Transaction()
+  addP2PKHInput(payTx, k, lockingScript, { txid: fundTx.id('hex'), vout: 0, satoshis: fundingValue })
+  payTx.addOutput({ lockingScript: opReturn, satoshis: 0 })
+  process.stdout.write('signing payload tx ... ')
+  t = Date.now()
+  await payTx.sign()
+  console.log(`${((Date.now() - t) / 1000).toFixed(1)}s`)
+
+  if (dry) {
+    return { txid: payTx.id('hex'), funding: fundTx.id('hex'), cost: (fundingValue + fundFee) / SATS_PER_COMPUTE, dry: true }
+  }
+  process.stdout.write('broadcasting funding tx ... ')
+  const ftx = await broadcast(fundTx.toHex())
+  console.log(ftx)
+  process.stdout.write('broadcasting payload tx ... ')
+  const ptx = await broadcast(payTx.toHex())
+  console.log(ptx)
+  return { txid: ptx, funding: ftx, cost: (fundingValue + fundFee) / SATS_PER_COMPUTE }
+}
+
+function recordSnapshot (rec) {
+  const idx = path.join(CONFIG_DIR, 'repos.json')
+  let all = []
+  try { all = JSON.parse(fs.readFileSync(idx, 'utf8')) } catch {}
+  all.push(rec)
+  fs.writeFileSync(idx, JSON.stringify(all, null, 2), 'utf8')
+}
+
+// ── commands ─────────────────────────────────────────────────────
+function measure (repoPath) {
+  const { out, name, abs } = tarball(repoPath)
+  const tar = fs.readFileSync(out)
+  fs.unlinkSync(out)
+  // ECIES adds an ephemeral pubkey, IV, PKCS#7 padding and an HMAC.
+  const cipherBytes = tar.length + 200
+  const scriptBytes = cipherBytes + 60
+  const repoTxBytes = 10 + INPUT_BYTES + 9 + scriptBytes
+  const repoFee = roundToSubUnit(feeFor(repoTxBytes))
+  return { name, abs, tar, repoTxBytes, repoFee }
+}
+
+function estimate (repoPath) {
+  const m = measure(repoPath)
+  console.log(m.name)
+  console.log(`  tar          ${(m.tar.length / 1048576).toFixed(2)} MB`)
+  console.log(`  repo tx      ${(m.repoTxBytes / 1048576).toFixed(2)} MB  (1 transaction, no chunking)`)
+  console.log(`  fee          ${m.repoFee} sats = ${m.repoFee / SATS_PER_COMPUTE} Compute`)
+  console.log(`  miner policy 100 MB — headroom ${(100 - m.repoTxBytes / 1048576).toFixed(1)} MB`)
+}
+
+function gitState (abs) {
+  let head = 'nogit'
+  let dirty = 0
+  try { head = sh('git', ['-C', abs, 'rev-parse', 'HEAD']).trim().slice(0, 12) } catch {}
+  try { dirty = sh('git', ['-C', abs, 'status', '--short']).split('\n').filter(Boolean).length } catch {}
+  return { head, dirty }
+}
+
+function sealPayload (meta, tar, k, pubHex) {
+  process.stdout.write('encrypting ... ')
+  const t = Date.now()
+  const cipher = EncryptedMessage.encrypt(
+    Array.from(framePayload(meta, tar)), k, PublicKey.fromString(pubHex)
+  )
+  console.log(`${((Date.now() - t) / 1000).toFixed(1)}s`)
+  const timestamp = Math.floor(Date.now() / 1000).toString(16).padStart(8, '0')
+  return buildOpReturn([REPO_PREFIX, VERSION, pubHex, hex(cipher), timestamp])
+}
+
+/** Fetch one KREP tx and return its decrypted { meta, tar }. */
+async function fetchPayload (txid, k, pubHex) {
+  const rawHex = await getRawHex(txid)
+  const tx = Transaction.fromHex(rawHex)
+  let parts = null
+  for (const o of tx.outputs) {
+    const s = o.lockingScript.toHex()
+    if (s.startsWith('006a') || s.startsWith('6a')) { parts = extractParts(s); break }
+  }
+  if (!parts || parts[0] !== REPO_PREFIX) throw new Error(`${txid} is not a KREP repo transaction`)
+  if (parts[2] !== pubHex) throw new Error(`${txid} is not encrypted to this identity`)
+  const plain = Buffer.from(EncryptedMessage.decrypt(Array.from(Buffer.from(parts[3], 'hex')), k))
+  return unframePayload(plain)
+}
+
+/**
+ * Every delta carries the ORDERED txid list of all its ancestors, oldest first —
+ * the same trick keychat-save's bootstrap table uses. One txid therefore yields
+ * the whole history in a single fetch. Walking back link-by-link was the
+ * alternative and it dead-ends the moment one link predates the format.
+ */
+function chainOf (txid, meta) {
+  return (meta.kind === 'delta') ? [...meta.chain, txid] : [txid]
+}
+
+/** Untar a payload over `dest`, then remove whatever the delta deleted. */
+function applyPayload (meta, tar, dest, repoName) {
+  const tmp = path.join(TMP, `apply-${meta.repo}-${Math.random().toString(36).slice(2)}.tgz`)
+  fs.writeFileSync(tmp, tar)
+  sh('tar', ['xzf', tmp, '-C', dest])
+  fs.unlinkSync(tmp)
+  for (const rel of (meta.deleted || [])) {
+    const p = path.join(dest, repoName, rel)
+    try { fs.rmSync(p, { force: true }) } catch {}
+  }
+}
+
+async function backup (repoPath, { dry = false } = {}) {
+  const k = key()
+  const address = k.toPublicKey().toAddress()
+  const pubHex = k.toPublicKey().toString()
+  const lockingScript = new P2PKH().lock(address)
+
+  const { out, name, abs } = tarball(repoPath)
+  assertNoSecrets(abs)
+  const tar = fs.readFileSync(out)
+  fs.unlinkSync(out)
+  const sha = createHash('sha256').update(tar).digest('hex')
+  const { root: manifestRoot } = buildManifest(abs)
+  const { head, dirty } = gitState(abs)
+
+  console.log(`${name}  ${(tar.length / 1048576).toFixed(2)} MB tar  HEAD ${head}  ${dirty} uncommitted`)
+  console.log(`sha256   ${sha}`)
+  console.log(`manifest ${manifestRoot}`)
+
+  const meta = {
+    v: 2, kind: 'full', repo: name, head, dirty,
+    sha256: sha, manifestRoot, tarSize: tar.length, at: Math.floor(Date.now() / 1000)
+  }
+  const scriptHex = sealPayload(meta, tar, k, pubHex)
+  const res = await publish(scriptHex, k, address, lockingScript, { dry })
+  if (dry) {
+    console.log(`\n--dry: nothing broadcast\n  payload ${res.txid}` +
+      (res.funding ? `\n  funding ${res.funding}` : ''))
+    return
+  }
+  recordSnapshot({ txid: res.txid, funding: res.funding, ...meta, cost: res.cost })
+  console.log(`\nSNAPSHOT ${name} @ ${head} -> ${res.txid}`)
+  console.log(`restore with: node scripts/keychat-repo.mjs restore ${res.txid} <dest>`)
+}
+
+/**
+ * Record only what changed since <baseTxid>. Cost tracks the change, not the repo:
+ * a code-only edit to sovereign-messenger is single-digit KB against 33.87 MB for
+ * a full snapshot.
+ *
+ * The base tree is rebuilt from chain rather than trusted from disk — that is the
+ * whole point. Diffing against the local working tree would record a delta against
+ * whatever this Mac happens to hold, which is exactly the assumption a backup
+ * exists to avoid.
+ */
+async function delta (repoPath, baseTxid, { dry = false } = {}) {
+  const k = key()
+  const address = k.toPublicKey().toAddress()
+  const pubHex = k.toPublicKey().toString()
+  const lockingScript = new P2PKH().lock(address)
+
+  const abs = path.resolve(repoPath.replace(/^~/, os.homedir()))
+  const name = path.basename(abs)
+  assertNoSecrets(abs)
+
+  // No base given: continue this repo's chain from its newest recorded snapshot.
+  // Routine saves are deltas, so needing to look a txid up by hand every time is
+  // friction on the path we want taken by default.
+  if (!baseTxid) {
+    let all = []
+    try { all = JSON.parse(fs.readFileSync(path.join(CONFIG_DIR, 'repos.json'), 'utf8')) } catch {}
+    const mine = all.filter(r => r.repo === name).sort((a, b) => b.at - a.at)
+    if (!mine.length) {
+      throw new Error(`no snapshot of ${name} in ~/.keychat/repos.json — run \`backup\` first`)
+    }
+    baseTxid = mine[0].txid
+    console.log(`base (latest ${name}) ${baseTxid}`)
+  }
+
+  process.stdout.write(`base ${baseTxid.slice(0, 16)}… `)
+  const basePayload = await fetchPayload(baseTxid, k, pubHex)
+  if (basePayload.meta.repo !== name) {
+    throw new Error(`base is a snapshot of ${basePayload.meta.repo}, not ${name}`)
+  }
+  const chain = chainOf(baseTxid, basePayload.meta)
+  console.log(`${basePayload.meta.repo} @ ${basePayload.meta.head}, chain of ${chain.length}`)
+
+  // Materialise the base tree by replaying its whole chain.
+  const work = fs.mkdtempSync(path.join(TMP, 'keychat-base-'))
+  for (const [i, t] of chain.entries()) {
+    const p = (t === baseTxid) ? basePayload : await fetchPayload(t, k, pubHex)
+    applyPayload(p.meta, p.tar, work, name)
+    console.log(`  replayed ${i + 1}/${chain.length} ${t.slice(0, 12)}… (${p.meta.kind || 'full'})`)
+  }
+
+  const baseM = buildManifest(path.join(work, name))
+  const curM = buildManifest(abs)
+  const { changed, deleted } = diffManifest(baseM.map, curM.map)
+  fs.rmSync(work, { recursive: true, force: true })
+
+  if (!changed.length && !deleted.length) {
+    console.log('no changes since base — nothing to save')
+    return
+  }
+  console.log(`${changed.length} changed/added, ${deleted.length} deleted`)
+
+  const listFile = path.join(TMP, `keychat-delta-${name}.list`)
+  fs.writeFileSync(listFile, changed.map(p => path.join(name, p)).join('\n') + '\n')
+  const out = path.join(TMP, `keychat-delta-${name}.tgz`)
+  sh('tar', ['czf', out, '-C', path.dirname(abs), '-T', listFile],
+    { env: { ...process.env, COPYFILE_DISABLE: '1' } })
+  const tar = fs.readFileSync(out)
+  fs.unlinkSync(out)
+  fs.unlinkSync(listFile)
+
+  const { head, dirty } = gitState(abs)
+  console.log(`delta    ${(tar.length / 1024).toFixed(1)} KB  HEAD ${head}  ${dirty} uncommitted`)
+  console.log(`manifest ${curM.root}`)
+
+  const meta = {
+    v: 2, kind: 'delta', repo: name, head, dirty,
+    base: baseTxid, chain,
+    deleted, changedCount: changed.length,
+    sha256: createHash('sha256').update(tar).digest('hex'),
+    manifestRoot: curM.root, tarSize: tar.length, at: Math.floor(Date.now() / 1000)
+  }
+  const scriptHex = sealPayload(meta, tar, k, pubHex)
+  const res = await publish(scriptHex, k, address, lockingScript, { dry })
+  if (dry) {
+    console.log(`\n--dry: nothing broadcast\n  payload ${res.txid}`)
+    return
+  }
+  recordSnapshot({ txid: res.txid, funding: res.funding, ...meta, cost: res.cost })
+  console.log(`\nDELTA ${name} @ ${head} -> ${res.txid}  (chain of ${chain.length + 1})`)
+  console.log(`restore with: node scripts/keychat-repo.mjs restore ${res.txid} <dest>`)
+}
+
+async function restore (txid, dest) {
+  const k = key()
+  const pubHex = k.toPublicKey().toString()
+
+  process.stdout.write(`fetching ${txid.slice(0, 16)}… `)
+  const head = await fetchPayload(txid, k, pubHex)
+  const name = head.meta.repo
+  console.log(`${name} @ ${head.meta.head} (${head.meta.kind || 'full'})`)
+
+  const chain = chainOf(txid, head.meta)
+  fs.mkdirSync(dest, { recursive: true })
+  for (const [i, t] of chain.entries()) {
+    const p = (t === txid) ? head : await fetchPayload(t, k, pubHex)
+    const got = createHash('sha256').update(p.tar).digest('hex')
+    if (p.meta.sha256 && got !== p.meta.sha256) {
+      throw new Error(`SHA MISMATCH on ${t} — expected ${p.meta.sha256}, got ${got}`)
+    }
+    applyPayload(p.meta, p.tar, dest, name)
+    console.log(`  applied ${i + 1}/${chain.length} ${t.slice(0, 12)}… ` +
+      `(${p.meta.kind || 'full'}, ${(p.tar.length / 1024).toFixed(0)} KB)`)
+  }
+
+  // The manifest is never stored, so recompute it and compare roots. This checks
+  // every file in the rebuilt tree, and fails loudly if a delta went on out of order.
+  if (head.meta.manifestRoot) {
+    const got = buildManifest(path.join(dest, name)).root
+    if (got !== head.meta.manifestRoot) {
+      throw new Error(`MANIFEST MISMATCH — expected ${head.meta.manifestRoot}, got ${got}`)
+    }
+    console.log(`manifest verified (${head.meta.manifestRoot.slice(0, 16)}…)`)
+  } else {
+    console.log('manifest not recorded (v1 snapshot) — tar sha256 verified only')
+  }
+  console.log(`restored to ${path.join(dest, name)}`)
+}
+
+function list () {
+  let all = []
+  try { all = JSON.parse(fs.readFileSync(path.join(CONFIG_DIR, 'repos.json'), 'utf8')) } catch {}
+  if (!all.length) return console.log('no snapshots recorded locally')
+  for (const r of all.sort((a, b) => b.at - a.at)) {
+    console.log(`${new Date(r.at * 1000).toISOString().slice(0, 10)}  ${r.repo.padEnd(20)} ` +
+      `${r.head}  ${(r.tarSize / 1048576).toFixed(1)} MB  ${r.cost}C  ${r.txid}`)
+  }
+}
+
+/**
+ * CLI entry for the repo/repochain commands, called from index.mjs.
+ *
+ * GENERATED by sovereign-messenger/scripts/sync-npm-package.mjs — do not edit
+ * this file. Edit scripts/keychat-repo.mjs and re-run the sync.
+ */
+export async function runRepo (argv) {
+  const [sub, a, ...rest] = argv
+  const dry = rest.includes('--dry') || a === '--dry'
+  if (sub === 'estimate') return estimate(a)
+  if (sub === 'backup') return backup(a, { dry })
+  if (sub === 'delta') return delta(a, rest.find(x => /^[0-9a-f]{64}$/.test(x)), { dry })
+  if (sub === 'restore') return restore(a, rest.find(x => !x.startsWith('--')) || '.')
+  if (sub === 'list') return list()
+  console.log('usage:')
+  console.log('  keychat-save repo backup   <repoPath>            full snapshot')
+  console.log('  keychat-save repo delta    <repoPath> [baseTxid] routine save')
+  console.log('  keychat-save repo restore  <txid> <dest>         replays the whole chain')
+  console.log('  keychat-save repo estimate <repoPath>')
+  console.log('  keychat-save repo list')
+  process.exitCode = 1
+}