livybolt 0.1.0 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,88 @@
+# livybolt — agent guide
+
+You are probably an LLM agent running headless. This file is the complete
+recipe for operating `livybolt` without a human at the keyboard, and the rules
+that keep the user's keys safe while you do it.
+
+## The one-time identity setup (macOS)
+
+```bash
+livybolt id new --keychain --json
+```
+
+That generates a strong random password, parks it in the macOS login keychain
+(service `livybolt-cli-identity`), and seals the identity seed encrypted at
+`~/.livybolt/identity.json`. Every later command finds the password by itself —
+you never handle one. On Linux/Windows, generate a password, keep it in the
+platform's secret store, and pass it per-invocation with `--password-stdin` or
+`LIVYBOLT_IDENTITY_PASSWORD`.
+
+**Never use `--insecure-plaintext`.** It stores the seed in cleartext and there
+is no situation where you need it — `--keychain` is equally headless.
+
+**Never print seed words.** Your transcript persists forever. `id new` already
+withholds them from piped output; do not work around that. The human claims
+their backup later by running `livybolt id backup` in their own terminal.
+
+**Tell the user about `seed_backup=pending`.** Until they run `livybolt id
+backup`, losing this machine loses the identity. Relay that state in your
+summary — it is in the output specifically so you will.
+
+## Password resolution (encrypted identities)
+
+Tried in order, for every command that unlocks the seed:
+
+1. `--password <pw>` (avoid: lands in argv and your transcript)
+2. `--password-stdin` (pipe it in)
+3. `LIVYBOLT_IDENTITY_PASSWORD`
+4. macOS Keychain (service `livybolt-cli-identity`, override with
+   `LIVYBOLT_KEYCHAIN_SERVICE`)
+5. Interactive hidden prompt — TTY only; headless runs fail fast instead of
+   hanging.
+
+## The survey lifecycle
+
+```bash
+# 1. Create (phase 1): returns a Lightning invoice + resume handle
+livybolt create survey.json            # -> handle + bolt11 invoice, total sats
+
+# 2. Pay the invoice with whatever wallet you have (e.g. Alby CLI, NWC).
+#    Livybolt never touches wallet secrets — payment happens outside the CLI.
+
+# 3. Create (phase 2): finalize with the payment preimage
+livybolt create --resume <handle> --preimage <hex>   # -> surveyId + public URL
+
+# 4. Accounting / reads
+livybolt balance --survey <id> --json
+livybolt vault read --survey <id> --json             # pull + DECRYPT responses locally
+livybolt vault list
+livybolt vault rebuild                               # recover vault entries from the seed
+
+# 5. Unlock overage responses (same two-phase pay flow as create)
+livybolt unlock --survey <id> --count <n>
+livybolt unlock --resume <handle> --preimage <hex>
+
+# 6. Pair the user's browser dashboard (read-only view credential)
+livybolt pair --pair-password <pw> --no-qr
+```
+
+Prefer `--json` wherever it exists; parse fields, don't scrape prose. The
+pairing blob from `pair` is ciphertext (safe to display); the pairing password
+is not — generate one, store it where the user can retrieve it, never echo it.
+
+## Threat model, bluntly
+
+The keychain protects the identity password **at rest**: disk images, backups,
+other user accounts. It does **not** protect against code already running as
+this user — unattended operation means any same-user process could do what you
+do. That is inherent, not fixable with different storage. The escalation
+ladder when an identity guards real value:
+
+- `--keychain` — unattended, at-rest protection (default for agents)
+- `--keychain-ask` — every keychain read pops a macOS approval dialog: the
+  human approves each use
+- Remote signer / hardware — the key never touches this machine (not yet
+  supported by this CLI)
+
+Everything is end-to-end encrypted; the server never sees plaintext responses,
+private keys, or the seed. Decryption happens locally in `vault read`.

package/README.md

@@ -19,7 +19,8 @@ Requires **Node.js ≥ 20**.
 ## Quick start
 
 ```bash
-livybolt id new --password "<a strong passphrase>"   # self-custody key, shown once
+livybolt id new --keychain                             # self-custody key (macOS: password kept in Keychain)
+#   or: livybolt id new --password "<a strong passphrase>"
 livybolt create survey.json                            # → Lightning invoice + handle
 #   ...pay the invoice with any wallet...
 livybolt create --resume <handle> --preimage <hex>     # → public URL, sealed to your vault
@@ -45,10 +46,12 @@ A minimal `survey.json`:
 ## Self-custody
 
 Your keys live only in `~/.livybolt/`. They are never sent to the server, which
-stores ciphertext and public keys only. **Back up the seed words** printed by
-`livybolt id new` — there is no recovery.
+stores ciphertext and public keys only. **Back up the seed words** — run
+`livybolt id backup` in a terminal to see them once and confirm; until then
+every command reminds you with `seed_backup=pending`. There is no recovery
+without them.
 
 ## Docs
 
 - CLI reference: https://livybolt.com/docs/cli
-- HTTP API reference: https://livybolt.com/docs/api
+- Running headless / as an LLM agent: see `AGENTS.md` in this package

package/package.json

@@ -1,21 +1,25 @@
 {
   "name": "livybolt",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "livybolt — accountless, self-custody, end-to-end-encrypted surveys over Lightning. CLI client for Livybolt (Nostr edition).",
   "type": "module",
   "bin": {
     "livybolt": "scripts/livybolt.mjs"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.11.0"
   },
   "files": [
     "scripts",
     "src",
-    "README.md"
+    "README.md",
+    "AGENTS.md"
   ],
   "dependencies": {
-    "nostr-tools": "^2.23.5"
+    "@noble/hashes": "^2.0.1",
+    "@scure/bip39": "^2.0.1",
+    "nostr-tools": "^2.23.5",
+    "qrcode-terminal": "^0.12.0"
   },
   "scripts": {
     "prepack": "node prepack.mjs"

package/scripts/agent-identity-store.mjs

@@ -12,7 +12,8 @@
 
 import { homedir } from 'node:os'
 import { join } from 'node:path'
-import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from 'node:fs'
+import { readFileSync, existsSync } from 'node:fs'
+import { atomicWriteFileSync } from './atomic-file-store.mjs'
 
 // v2: seed-bearing store (v1 stored the account-0 privkey, which could not derive
 // per-survey keys). Greenfield — no v1 stores exist to migrate.
@@ -29,15 +30,42 @@ export function storePath() {
 export function readStore() {
   const path = storePath()
   if (!existsSync(path)) return null
-  return JSON.parse(readFileSync(path, 'utf8'))
+  const raw = readFileSync(path, 'utf8')
+  try {
+    return JSON.parse(raw)
+  } catch (err) {
+    // A torn/corrupt identity.json (e.g. a pre-atomic-write tear) must fail with
+    // an actionable message, not a bare SyntaxError on every command — this file
+    // holds the seed, so the user needs to know what happened and where.
+    throw new Error(
+      `identity store at ${path} is corrupt and could not be parsed (${err.message}). ` +
+        'If you have your seed words, remove the file and run `livybolt id restore --seed`; ' +
+        'otherwise this identity may be unrecoverable.'
+    )
+  }
 }
 
 export function writeStore(record) {
-  const home = storeHome()
-  mkdirSync(home, { recursive: true, mode: 0o700 })
-  const path = storePath()
-  writeFileSync(path, JSON.stringify(record, null, 2) + '\n', { mode: 0o600 })
-  // writeFileSync only applies mode on create — force it on overwrite too.
-  chmodSync(path, 0o600)
-  return path
+  // Atomic temp-write + rename: this file holds the seed, so a process killed
+  // mid-write (OOM, sleep, disk full) must leave either the old file intact or
+  // the new one fully written — never a torn hybrid. Previously a plain
+  // writeFileSync could tear identity.json, and in headless mode (seed words
+  // never shown) the torn ncryptsec was the only copy → identity lost.
+  return atomicWriteFileSync(storePath(), JSON.stringify(record, null, 2) + '\n', { mode: 0o600 })
+}
+
+// A record is "unbacked" until a human has seen the seed words and confirmed
+// (`livybolt id backup` sets backupConfirmedAt). Records created before this
+// field existed count as unbacked — the nag is how their owners find out.
+export function backupPending(record) {
+  return record != null && !record.backupConfirmedAt
+}
+
+// One stderr line, printed by every command that unlocks the identity while
+// the seed is unbacked. Deliberately on stderr (never corrupts JSON output)
+// and deliberately in the output agents relay to humans: losing this machine
+// while the state is pending loses the identity.
+export function warnIfBackupPending(record) {
+  if (!backupPending(record)) return
+  console.error('⚠ seed not backed up — run `livybolt id backup` in a terminal (lose this machine before then and this identity is unrecoverable)')
 }

package/scripts/agent-identity.mjs

@@ -9,38 +9,66 @@
 // so the CLI and any inline reimplementation produce byte-identical keys.
 //
 // Commands:
-//   new       Generate a fresh identity. Prints npub + seed words ONCE, seals it
-//             to the local store (encrypted by default), prints the ncryptsec backup.
-//   show      Print the stored npub/pubkey (never the secret).
+//   new       Generate a fresh identity, sealed encrypted. On a terminal the
+//             seed words print ONCE; piped/JSON output never carries them
+//             (agents' transcripts persist — run `id backup` to see the words).
+//   show      Print the stored npub/pubkey + backup state (never the secret).
+//   backup    TTY-only ceremony: print the seed words, confirm they are written
+//             down, and clear the seed_backup=pending state.
 //   export    Print the ncryptsec backup blob (for off-machine backup).
 //   restore   Rebuild the store from --seed "<words>" or --ncryptsec <blob>.
 //   unlock    Verify the store opens (password if encrypted); prints npub.
 //
 // Flags:
-//   --plaintext        Store the bare seed words at 0600 instead of an ncryptsec
-//                      (zero-friction for headless agents; secret rests in cleartext).
-//   --password <pw>    Password for the ncryptsec. Else LIVYBOLT_IDENTITY_PASSWORD,
-//                      else an interactive (hidden) prompt.
-//   --seed "<words>"   BIP-39 mnemonic (restore).
-//   --ncryptsec <blob> ncryptsec1… backup blob (restore).
+//   --keychain          (new/restore, macOS) Generate a random password, park it
+//                       in the login keychain, seal encrypted. The zero-setup
+//                       headless path — later commands find the password
+//                       themselves. At-rest protection only: any process running
+//                       as this user can read the entry.
+//   --keychain-ask      Like --keychain, but every keychain read pops a macOS
+//                       allow/deny dialog — per-use human approval.
+//   --password <pw>     Password for the ncryptsec. Else --password-stdin, else
+//                       LIVYBOLT_IDENTITY_PASSWORD, else keychain (unlock only),
+//                       else an interactive (hidden) prompt.
+//   --password-stdin    Read the password from stdin (keeps it out of argv/env).
+//   --insecure-plaintext  Store the bare seed words at 0600. The name is the
+//                       warning; prefer --keychain, which is equally headless.
+//   --json              Machine-readable output (never includes seed words).
+//   --seed "<words>"    BIP-39 mnemonic (restore).
+//   --ncryptsec <blob>  ncryptsec1… backup blob (restore).
 //
 // Store location: ~/.livybolt/identity.json (override LIVYBOLT_IDENTITY_HOME).
+// Keychain service: livybolt-cli-identity (override LIVYBOLT_KEYCHAIN_SERVICE).
 //
 // Usage:
+//   node scripts/agent-identity.mjs new --keychain
 //   node scripts/agent-identity.mjs new --password "hunter2"
-//   node scripts/agent-identity.mjs new --plaintext
-//   node scripts/agent-identity.mjs show
+//   node scripts/agent-identity.mjs backup
 //   node scripts/agent-identity.mjs export > backup.ncryptsec
-//   node scripts/agent-identity.mjs restore --seed "word1 word2 …" --password "hunter2"
+//   node scripts/agent-identity.mjs restore --seed "word1 word2 …" --keychain
 
+import { createInterface } from 'node:readline'
 import {
   generateAgentIdentity,
   agentIdentityFromSeedWords,
   AgentIdentityError,
 } from '../src/lib/crypto/agent-identity.js'
 import { sealSeed, unlockSeed, SeedStoreError } from '../src/lib/crypto/seed-store.js'
-import { readStore, writeStore, storePath, STORE_VERSION } from './agent-identity-store.mjs'
+import {
+  readStore,
+  writeStore,
+  storePath,
+  STORE_VERSION,
+  backupPending,
+  warnIfBackupPending,
+} from './agent-identity-store.mjs'
 import { resolveIdentityPassword } from './cli-prompt.mjs'
+import {
+  keychainAvailable,
+  keychainService,
+  generateKeychainPassword,
+  storeKeychainPassword,
+} from './keychain.mjs'
 
 function fail(msg) {
   console.error(`error: ${msg}`)
@@ -52,8 +80,14 @@ function parseFlags(argv) {
   const flags = {}
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
-    if (a === '--plaintext') flags.plaintext = true
+    if (a === '--insecure-plaintext') flags.insecurePlaintext = true
+    else if (a === '--plaintext')
+      fail('--plaintext is now --insecure-plaintext (the name is the warning). Prefer --keychain: equally headless, encrypted at rest.')
+    else if (a === '--keychain') flags.keychain = true
+    else if (a === '--keychain-ask') flags.keychainAsk = true
     else if (a === '--password') flags.password = argv[++i]
+    else if (a === '--password-stdin') flags.passwordStdin = true
+    else if (a === '--json') flags.json = true
     else if (a === '--seed') flags.seed = argv[++i]
     else if (a === '--ncryptsec') flags.ncryptsec = argv[++i]
     else fail(`unknown argument: ${a}`)
@@ -61,17 +95,66 @@ function parseFlags(argv) {
   return flags
 }
 
-async function resolvePassword(flags, purpose) {
-  const pw = await resolveIdentityPassword(flags, fail, purpose)
+async function resolvePassword(flags, purpose, opts) {
+  const pw = await resolveIdentityPassword(flags, fail, purpose, opts)
   if (!pw) fail('empty password')
   return pw
 }
 
+/**
+ * Choose the password that will seal a NEW secret. --keychain/--keychain-ask
+ * generate one and park it in the macOS keychain (so the identity is usable
+ * headless with zero password handling); otherwise the explicit ladder runs
+ * with the keychain rung OFF — a stale keychain entry must never silently
+ * become the password of a fresh identity.
+ */
+async function passwordForNewSecret(flags, purpose) {
+  const useKeychain = flags.keychain || flags.keychainAsk
+  if (useKeychain && flags.insecurePlaintext) {
+    fail('--keychain seals the seed encrypted — it cannot combine with --insecure-plaintext')
+  }
+  if (flags.insecurePlaintext) return { password: null }
+  if (!useKeychain) return { password: await resolvePassword(flags, purpose, { skipKeychain: true }) }
+  if (flags.password != null || flags.passwordStdin) {
+    fail('--keychain generates its own random password — do not also pass one')
+  }
+  if (!keychainAvailable()) {
+    fail('--keychain needs the macOS keychain. Use --password / --password-stdin / LIVYBOLT_IDENTITY_PASSWORD instead.')
+  }
+  const password = generateKeychainPassword()
+  // Keychain first: a store sealed to a password that never reached the
+  // keychain would be sealed to a password nobody has.
+  storeKeychainPassword(password, { ask: flags.keychainAsk })
+  return { password, keychain: true }
+}
+
+/** Visible-echo confirmation prompt (the backup ceremony's "yes"). EOF on
+ * stdin resolves to '' (→ "not confirmed") instead of leaving the promise —
+ * and the whole process — hanging on an unsettled top-level await. */
+function promptVisible(query) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    let settled = false
+    const settle = (answer) => {
+      if (settled) return
+      settled = true
+      resolve(answer.trim())
+    }
+    rl.question(query, (answer) => {
+      // Settle BEFORE close: rl.close() emits 'close' synchronously, and the
+      // EOF fallback below must not win the race against a real answer.
+      settle(answer)
+      rl.close()
+    })
+    rl.on('close', () => settle(''))
+  })
+}
+
 // --- store sealing + self-check ----------------------------------------------
 // The persisted secret is the SEED, so per-survey keys can derive from it. We
-// store the seed words (plaintext mode) or a NIP-49 ncryptsec of the BIP-39
-// entropy (encrypted default). `secretKind` tags the payload so the seed entropy
-// is never misread as an nsec.
+// store the seed words (insecure-plaintext mode) or a NIP-49 ncryptsec of the
+// BIP-39 entropy (encrypted default). `secretKind` tags the payload so the seed
+// entropy is never misread as an nsec.
 function sealRecord(id, { plaintext, password }) {
   if (!id.seedWords) {
     fail('cannot store a seed-bearing identity without seed words (use restore --seed or --ncryptsec)')
@@ -119,35 +202,127 @@ async function cmdNew(flags) {
     fail(`an identity already exists at ${storePath()} — refusing to overwrite. Move it aside first.`)
   }
   const id = generateAgentIdentity()
-  const password = flags.plaintext ? null : await resolvePassword(flags, 'encrypt the new identity')
-  const record = sealRecord(id, { plaintext: flags.plaintext, password })
+  const sealed = await passwordForNewSecret(flags, 'encrypt the new identity')
+  const record = sealRecord(id, { plaintext: flags.insecurePlaintext, password: sealed.password })
+  // Verify the seal round-trips BEFORE persisting — a mis-sealed identity must
+  // never reach disk, where `id new` would then refuse to overwrite it (it
+  // "exists") and leave the user stuck with an unusable store.
+  selfCheck(record, sealed.password)
   writeStore(record)
-  selfCheck(record, password)
 
-  console.error('')
-  console.error('  ⚠  BACK UP THESE SEED WORDS NOW — shown once, never sent to the server.')
-  console.error('     They are the canonical recovery for this identity.')
-  console.error(`     Stored ${flags.plaintext ? 'in CLEARTEXT (--plaintext)' : 'encrypted'} at ${storePath()} (0600).`)
-  console.error('')
+  // Seed words print ONLY to a terminal a human is watching. Piped/JSON output
+  // (agents — whose transcripts persist forever) gets seed_backup=pending and
+  // the `id backup` pointer instead.
+  const humanTerminal = process.stdout.isTTY && !flags.json
+
+  // The scrypt-sealed ncryptsec is safe to print to a persistent transcript ONLY
+  // when sealed with a keychain-generated RANDOM password (infeasible to grind).
+  // With a user-supplied password the ncryptsec is offline-grindable — and the
+  // password is often on the same invocation line — so leaking it to a piped/JSON
+  // transcript is a master-seed compromise. Gate it like the seed words: emit to
+  // a human terminal or a keychain seal; otherwise withhold and point at `id
+  // export` (the deliberate retrieval path, run in a terminal).
+  const canEmitNcryptsec = !!record.ncryptsec && (sealed.keychain || humanTerminal)
+
+  if (flags.json) {
+    console.log(
+      JSON.stringify({
+        npub: id.npub,
+        pubkey: id.pubkeyHex,
+        mode: flags.insecurePlaintext ? 'plaintext' : 'encrypted',
+        store: storePath(),
+        seed_backup: 'pending',
+        ...(sealed.keychain ? { keychain_service: keychainService() } : {}),
+        ...(canEmitNcryptsec ? { ncryptsec: record.ncryptsec } : {}),
+      })
+    )
+    return
+  }
 
   console.log(`npub=${id.npub}`)
   console.log(`pubkey=${id.pubkeyHex}`)
-  console.log(`seed_words=${id.seedWords}`)
-  if (record.ncryptsec) console.log(`ncryptsec=${record.ncryptsec}`)
+  if (humanTerminal) {
+    console.error('')
+    console.error('  ⚠  BACK UP THESE SEED WORDS NOW — shown once, never sent to the server.')
+    console.error('     They are the canonical recovery for this identity.')
+    console.error(`     Stored ${flags.insecurePlaintext ? 'in CLEARTEXT (--insecure-plaintext)' : 'encrypted'} at ${storePath()} (0600).`)
+    console.error('')
+    console.log(`seed_words=${id.seedWords}`)
+    console.error('')
+    console.error('  Run `livybolt id backup` once they are written down to confirm the backup.')
+  } else {
+    console.log('seed_backup=pending')
+    console.error('seed words withheld from non-terminal output — run `livybolt id backup` in a terminal to see them once and confirm the backup')
+  }
+  if (sealed.keychain) console.log(`keychain_service=${keychainService()}`)
+  if (record.ncryptsec) {
+    if (canEmitNcryptsec) {
+      console.log(`ncryptsec=${record.ncryptsec}`)
+    } else {
+      console.error('ncryptsec (encrypted seed backup) withheld from non-terminal output — run `livybolt id export` in a terminal to retrieve it')
+    }
+  }
 }
 
-function cmdShow() {
+function cmdShow(flags) {
   const rec = readStore()
-  if (!rec) fail(`no identity at ${storePath()}. Run: node scripts/agent-identity.mjs new`)
+  if (!rec) fail(`no identity at ${storePath()}. Run: livybolt id new`)
+  const backup = backupPending(rec) ? 'pending' : `confirmed ${rec.backupConfirmedAt}`
+  if (flags.json) {
+    console.log(
+      JSON.stringify({
+        npub: rec.npub,
+        pubkey: rec.pubkey,
+        mode: rec.secretKind === 'seed-plaintext' ? 'plaintext' : 'encrypted',
+        created: rec.createdAt,
+        store: storePath(),
+        seed_backup: backupPending(rec) ? 'pending' : 'confirmed',
+        ...(backupPending(rec) ? {} : { backup_confirmed_at: rec.backupConfirmedAt }),
+      })
+    )
+    return
+  }
   console.log(`npub=${rec.npub}`)
   console.log(`pubkey=${rec.pubkey}`)
   console.log(`mode=${rec.secretKind === 'seed-plaintext' ? 'plaintext' : 'encrypted'}`)
   console.log(`created=${rec.createdAt}`)
+  console.log(`seed_backup=${backup}`)
+}
+
+// The one sanctioned way to see the seed words after creation: a terminal-only
+// ceremony that ends by recording the human's confirmation, which clears the
+// seed_backup=pending nag everywhere.
+async function cmdBackup(flags) {
+  const rec = readStore()
+  if (!rec) fail(`no identity at ${storePath()}. Run: livybolt id new`)
+  if (!process.stdout.isTTY || !process.stdin.isTTY) {
+    fail('refusing to print seed words to a non-terminal (transcripts persist). Run `livybolt id backup` in an interactive terminal.')
+  }
+  const password =
+    rec.secretKind === 'seed-plaintext'
+      ? undefined
+      : await resolvePassword(flags, 'unlock the identity')
+  const words = seedFromRecord(rec, password)
+
+  console.log('')
+  console.log('  Your seed words — the canonical recovery for this identity.')
+  console.log('  Write them down somewhere that is not this machine.')
+  console.log('')
+  console.log(`      ${words}`)
+  console.log('')
+  const answer = await promptVisible('  Type "yes" once they are written down: ')
+  if (answer.toLowerCase() !== 'yes') {
+    fail('not confirmed — seed backup is still pending')
+  }
+  rec.backupConfirmedAt = new Date().toISOString()
+  writeStore(rec)
+  console.log(`seed_backup=confirmed ${rec.backupConfirmedAt}`)
 }
 
 async function cmdExport(flags) {
   const rec = readStore()
-  if (!rec) fail(`no identity at ${storePath()}. Run: node scripts/agent-identity.mjs new`)
+  if (!rec) fail(`no identity at ${storePath()}. Run: livybolt id new`)
+  warnIfBackupPending(rec)
   // The exported blob is a NIP-49 ncryptsec of the seed entropy — restore it with
   // `restore --ncryptsec`. It is NOT a portable nsec; the seed words are the
   // canonical cross-tool backup.
@@ -156,7 +331,7 @@ async function cmdExport(flags) {
     return
   }
   // Plaintext store: derive an encrypted seed backup on demand.
-  const password = await resolvePassword(flags, 'encrypt the backup')
+  const password = await resolvePassword(flags, 'encrypt the backup', { skipKeychain: true })
   console.log(sealSeed(rec.seedWords, password))
 }
 
@@ -174,16 +349,20 @@ async function cmdRestore(flags) {
   } else {
     fail('restore needs --seed "<words>" or --ncryptsec <blob>')
   }
-  const password = flags.plaintext ? null : await resolvePassword(flags, 'encrypt the restored identity')
-  const record = sealRecord(id, { plaintext: flags.plaintext, password })
+  const sealed = await passwordForNewSecret(flags, 'encrypt the restored identity')
+  const record = sealRecord(id, { plaintext: flags.insecurePlaintext, password: sealed.password })
+  // The human restoring from a backup self-evidently holds that backup.
+  record.backupConfirmedAt = new Date().toISOString()
   writeStore(record)
-  selfCheck(record, password)
+  selfCheck(record, sealed.password)
   console.log(`npub=${id.npub}`)
+  if (sealed.keychain) console.log(`keychain_service=${keychainService()}`)
 }
 
 async function cmdUnlock(flags) {
   const rec = readStore()
-  if (!rec) fail(`no identity at ${storePath()}. Run: node scripts/agent-identity.mjs new`)
+  if (!rec) fail(`no identity at ${storePath()}. Run: livybolt id new`)
+  warnIfBackupPending(rec)
   const password =
     rec.secretKind === 'seed-plaintext'
       ? undefined
@@ -204,7 +383,10 @@ try {
       await cmdNew(flags)
       break
     case 'show':
-      cmdShow()
+      cmdShow(flags)
+      break
+    case 'backup':
+      await cmdBackup(flags)
       break
     case 'export':
       await cmdExport(flags)
@@ -218,8 +400,8 @@ try {
     default:
       fail(
         `unknown command: ${command ?? '(none)'}\n` +
-          '  commands: new | show | export | restore | unlock\n' +
-          '  e.g. node scripts/agent-identity.mjs new --password "hunter2"'
+          '  commands: new | show | backup | export | restore | unlock\n' +
+          '  e.g. node scripts/agent-identity.mjs new --keychain'
       )
   }
 } catch (err) {

package/scripts/atomic-file-store.mjs

@@ -0,0 +1,72 @@
+// Shared local at-rest file helpers for the CLI's JSON stores (vault,
+// pending-create, survey-index counter): atomic writes and a same-machine
+// advisory lock. Extracted because all three stores need the identical fix
+// for the identical failure mode — a process killed mid-write (OOM, container
+// eviction, laptop sleep, disk full) leaving a torn file, or two concurrent
+// CLI invocations racing a read-modify-write.
+
+import { writeFileSync, renameSync, chmodSync, unlinkSync, mkdirSync, openSync, closeSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { randomBytes } from 'node:crypto'
+
+/**
+ * Write `data` to `path` atomically: write to a uniquely-named temp file in
+ * the same directory, then rename(2) over the target. rename is atomic on a
+ * given filesystem, so a process killed mid-write leaves either the old file
+ * intact or the new one fully written — never a torn hybrid that a JSON
+ * parser chokes on.
+ */
+export function atomicWriteFileSync(path, data, { mode = 0o600 } = {}) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+  const tmpPath = `${path}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`
+  writeFileSync(tmpPath, data, { mode })
+  chmodSync(tmpPath, mode)
+  renameSync(tmpPath, path)
+  return path
+}
+
+/** Synchronous blocking sleep (Atomics.wait on a throwaway SharedArrayBuffer)
+ *  — fine for a short-lived CLI's lock-retry backoff; never use this in a
+ *  long-running server process. */
+function sleepSyncMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+}
+
+/**
+ * Run `fn` while holding a same-machine advisory lock at `${path}.lock`,
+ * serializing concurrent CLI invocations that read-modify-write the same
+ * file. The lock file is created with the exclusive `wx` flag, so only one
+ * of two racing processes can create it; the loser retries with a fixed
+ * backoff until the lock is released or `timeoutMs` elapses.
+ *
+ * Not a general-purpose distributed lock — it assumes a single machine and a
+ * cooperative process that always reaches the `finally` (a SIGKILL mid-`fn`
+ * leaves a stale lock file; a human deleting it, or waiting for the next
+ * `livybolt vault rebuild`, are the recovery paths).
+ */
+export function withFileLockSync(path, fn, { timeoutMs = 5000, retryMs = 20 } = {}) {
+  const lockPath = `${path}.lock`
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    try {
+      closeSync(openSync(lockPath, 'wx'))
+      break
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err
+      if (Date.now() > deadline) {
+        throw new Error(`timed out waiting for lock at ${lockPath} — held by another livybolt process?`)
+      }
+      sleepSyncMs(retryMs)
+    }
+  }
+  try {
+    return fn()
+  } finally {
+    try {
+      unlinkSync(lockPath)
+    } catch {
+      // Already released (or never fully created) — nothing to clean up.
+    }
+  }
+}