indelible-mcp 5.8.7 → 5.8.8

package/AI_OPERATORS_HANDBOOK.md

@@ -4,7 +4,7 @@
 it well — how to hold goals honestly, and how to leave proof on chain that survives you.
 
 **© 2026 Indelible Federation.** Written and verified by Indelible's QA process · **2026-08-16** · built
-against `indelible-mcp@5.7.6`, re-verified claim-by-claim against `indelible-mcp@5.7.7` (see Rev 4), **audited claim-by-claim again against `indelible-mcp@5.8.3`** on 2026-08-18, and **re-verified claim-by-claim on 2026-08-25** against the then-unreleased build (Rev 5 — every checkable behavior held; that build was never published, so no release carries the number it was staged under), then **re-measured against this bundle on 2026-09-10** (Rev 6 — all five machine-to-machine `drift` verbs, `arm`/`serve`/`calibrate`/`heal`/`note`, are in this bundle; Part 12 names `arm` and `serve` in its ships-today table, and none of the five is documented in detail here).
+against `indelible-mcp@5.7.6`, re-verified claim-by-claim against `indelible-mcp@5.7.7` (see Rev 4), **audited claim-by-claim again against `indelible-mcp@5.8.3`** on 2026-08-18, and **re-verified claim-by-claim on 2026-08-25** against the then-unreleased build (Rev 5 — every checkable behavior held; that build was never published, so no release carries the number it was staged under), then **re-measured against this bundle on 2026-09-10** (Rev 6 — all five machine-to-machine `drift` verbs, `arm`/`serve`/`calibrate`/`heal`/`note`, are in this bundle; Part 12 names `arm` and `serve` in its ships-today table, and none of the five is documented in detail here), then **re-measured against `indelible-mcp@5.8.8` on 2026-09-26** (Rev 7 — the wallet-file race is closed at one chokepoint, `wallet_unlock_journal` is served, project restores are confined to their output folder, `tools/list` answers 36 on a fresh home against 5.8.7's 35, and the two held rows in 12.1 are still absent from the list; see 10.1 for the two refusals an assistant now has to know).
 Every rule here comes from something that actually happened on a real box, not from reading the docs.
 
 **Rev 2 — peer-reviewed.** Draft 1 (`5c3f10c3…` on chain) was sent over the Drift Wire to an independent
@@ -48,7 +48,7 @@ by adversarial review, not by re-reading my own work. That is the method working
 
 **Rev 6 — the machine-to-machine system added, by a different seat, and the version line drawn honestly.** Part 12 is new: the wire two machines talk over, the standing grant that gives them one memory, the four disciplines each learned from a specific failure, and the seat model that made the review of this product work. It was written by the **builder seat**, not by the QA machine that wrote everything above it, and it has not yet been through the adversarial pass the rest of this document survived; treat its claims accordingly until that review lands.
 
-**The version line is the part to read carefully, and measuring it turned up a third generation nobody had named.** The wire, the named seats, `drift arm` and `drift serve` are in THIS bundle. The three pieces that make two machines share one memory need to be told apart, because they are **not in the same state** and an earlier revision of this paragraph got all three wrong at once. Re-measured 2026-09-10 against this bundle, by counting them in `src/index.js` rather than recalling them: the **standing grant** (`pair_machine`) and the **catch-up read** (`catch_up`) ARE in this bundle, but they are **HELD** — deliberately filtered out of `tools/list`, so they are present in the bytes but **not advertised** — nothing on the customer surface tells an operator they exist, though a caller that already knows the name still reaches the handler (the filter is on the listing, not the dispatch). A **shared save returning its messages rather than only its title** IS here and IS callable. So one of the three works for you today and two are shipped-but-closed; none of them "exists only in the build tree", which is what this paragraph used to say. ⚠️ That correction matters more than the fact: the old wording under-sold a capability that actually shipped, in the one document that tells you not to trust unverified claims. This package is **5.8.5**; run `npm view indelible-mcp version` yourself rather than trusting this sentence, because it is the one line here that goes stale on every release. Once this publishes, two of those artifacts collapse into one and a reader has two left to keep straight — what this package carries, and what the machines actually run. A handbook that sold the third as available would be doing the exact thing Rev 4 was corrected for, pointed the other way. Run the command and read the refusal before you promise any of it to a person.
+**The version line is the part to read carefully, and measuring it turned up a third generation nobody had named.** The wire, the named seats, `drift arm` and `drift serve` are in THIS bundle. The three pieces that make two machines share one memory need to be told apart, because they are **not in the same state** and an earlier revision of this paragraph got all three wrong at once. Re-measured 2026-09-10 against this bundle, by counting them in `src/index.js` rather than recalling them: the **standing grant** (`pair_machine`) and the **catch-up read** (`catch_up`) ARE in this bundle, but they are **HELD** — deliberately filtered out of `tools/list`, so they are present in the bytes but **not advertised** — nothing on the customer surface tells an operator they exist, though a caller that already knows the name still reaches the handler (the filter is on the listing, not the dispatch). A **shared save returning its messages rather than only its title** IS here and IS callable. So one of the three works for you today and two are shipped-but-closed; none of them "exists only in the build tree", which is what this paragraph used to say. ⚠️ That correction matters more than the fact: the old wording under-sold a capability that actually shipped, in the one document that tells you not to trust unverified claims. This package is **5.8.8** (the held rows were re-checked against this bundle's `tools/list` on 2026-09-26 and are still held); run `npm view indelible-mcp version` yourself rather than trusting this sentence, because it is the one line here that goes stale on every release. Once this publishes, two of those artifacts collapse into one and a reader has two left to keep straight — what this package carries, and what the machines actually run. A handbook that sold the third as available would be doing the exact thing Rev 4 was corrected for, pointed the other way. Run the command and read the refusal before you promise any of it to a person.
 
 ---
 
@@ -803,6 +803,10 @@ already running is still the old code, so the strongbox tools will not appear un
 restarted. If someone says they just updated and you cannot see `strongbox_status`, that is the reason:
 tell them to quit and reopen their assistant. Do not tell them the feature is missing.
 
+**The save journal lock, and the door added in 5.8.8.** Every broadcast on a machine goes through one save journal, and a process that dies while holding its lock leaves every later save on that machine waiting; the refusal reads *"a previous Indelible process stopped while holding the save journal lock, so saves on this computer are paused for safety"*. That is a safety stop, not a bug: two writers on one wallet is the double-spend class this product has paid for before. The door is `wallet_unlock_journal` (or, at a terminal, `indelible-mcp wallet --unlock-journal`). It clears the lock only after proving the process that held it is gone; if a save is genuinely in progress it says so and clears nothing, and with no lock held it says "Nothing to clear". Call it when the customer reports that refusal, tell them what it found, and do not retry the save until it reports the lock cleared.
+
+**The wallet file is written all-or-nothing from 5.8.8, and two refusals are new.** Before this release a read of `~/.indelible/config.json` that landed mid-write could come back empty and be written back over the wallet key; the path is closed (temp file swapped into place; on Windows and Linux one lock across every Indelible process on the machine; on macOS the atomic write and the refusals without the lock, so concurrent processes there are still the operator's problem to avoid). `CONFIG_UNREADABLE` means the file exists and could not be read or parsed, and **nothing was changed**: if it is the wallet file, the customer restores it from their backup, and you never let a save, a setup or a settings change rewrite it first. `CONFIG_BUSY` means another program holds it open (Windows); close that program and retry. Neither is permission to run setup again; setup on a machine that already has a wallet refuses ("Wallet already configured" up front, and `WALLET_ALREADY_CONFIGURED` from inside the lock if a key appears while it is running) and that refusal is the protection.
+
 Auto-save is your seatbelt. The daily MD is your actually-arriving-somewhere.
 
 ## 10.2 Bank at milestones, not at the end
@@ -993,7 +997,7 @@ This is the first thing to establish, because the rest is useless if you tell a
 | **`pair_machine`** — the standing grant, so every save shares itself automatically | **held for 6.0.0.** Deliberately not on the customer surface yet |
 | **`catch_up`** — read everything a machine has shared since last time, in order | **held for 6.0.0** |
 
-Measured against this bundle on 2026-09-10, not recalled.
+Measured against this bundle on 2026-09-10, not recalled; re-checked on the 5.8.8 bundle on 2026-09-26 (36 tools listed on a fresh home, the two held rows still absent, `wallet_unlock_journal` present).
 
 The `load_shared` row moved. In 5.8.3 that tool decrypted a share and handed back a summary of up to 2000 characters, never the message content, and it reported `message_count` as the **whole conversation's** total — so a 19-message share was announced to the receiving machine as 34,558 messages. This bundle returns the messages, discloses `shared_unit` so you can see that what was granted is one save rather than a conversation, splits the count into the shared unit's own and `conversation_message_count` beside it, and stamps `from_verified` so a caller stops inferring trust from the word `ok`.
 

package/CLI_HANDBOOK.md

@@ -2,7 +2,7 @@
 
 ## The Command Card — the everyday commands in plain words
 
-*(Not exhaustive — 5.8.5 adds the machine-to-machine `drift` verbs; `agents`, `keys`, and `semantic-fetch` shipped in earlier releases. Run `indelible-mcp --help` any time to see the full, current roster.)*
+*(Not exhaustive — 5.8.8 adds `wallet --unlock-journal`; 5.8.5 added the machine-to-machine `drift` verbs; `agents`, `keys`, and `semantic-fetch` shipped in earlier releases. Run `indelible-mcp --help` any time to see the roster; the `wallet` verb is not yet listed there, and it works.)*
 
 You don't have to memorize any of this. In Claude Code you can just say what you want ("save this session", "post that to the drift wire", "read the wire") and your AI runs the command for you. This card is for when you want to type it yourself — one line each, no jargon.
 
@@ -10,6 +10,8 @@ You don't have to memorize any of this. In Claude Code you can just say what you
 |---|---|
 | `indelible-mcp status` | Shows your wallet address, your API key presence, and (from 5.8.5) whether your installed version is behind the latest. It does NOT tell you whether saves are reaching the chain — for that, verify a save's txid in the Chain Browser at indelible.one/explorer. |
 | `indelible-mcp save --summary "note"` | Saves your newest session transcript to the blockchain, forever. Works from 5.8.5 — older releases refused with "Transcript not found". |
+| `indelible-mcp wallet` | Shows whether anything on this computer is holding your wallet's coins or its save journal lock right now. "The wallet is idle" means neither. |
+| `indelible-mcp wallet --unlock-journal` | Clears a save journal lock left behind by an Indelible process that died, and only after proving that process is gone (5.8.8). Safe to run any time: with nothing to clear it says "Nothing to clear". Your assistant can do the same through the `wallet_unlock_journal` tool. |
 | `indelible-mcp load` | Pulls your recent saved memory back down. |
 | `indelible-mcp map` | Draws a 3D map of everything you've ever worked on. |
 | `indelible-mcp drift read` | Shows the conversation between your AIs. |
@@ -214,6 +216,8 @@ save --summary "note"        Save with custom summary
 load                         Load context from blockchain (default: 5 sessions)
 load --sessions=10           Load N sessions
 status                       Show wallet address, API key, last session
+wallet                       Show what is holding your coins or the save journal lock (idle = nothing)
+wallet --unlock-journal      Clear a save journal lock whose holder is proven gone (5.8.8+)
 ```
 
 ### Code Vault
@@ -359,6 +363,11 @@ This creates a standalone `indelible.exe` — no Node.js required on the target
 | `txn-mempool-conflict` | Spending already-spent UTXO | UTXO chaining should prevent this — check code |
 | `<provider> rate limit exceeded` | Too many diary chat calls (the message names the provider: Groq, xAI Grok, or OpenAI) | Wait a moment and retry |
 | `Diary AI needs a companion model` | No companion key connected on this box (the keyless free Groq companion lives at indelible.one, not in the CLI) | Use the free companion at indelible.one, or upgrade here with `diary connect --key=...` using an xAI (`xai-...`) or OpenAI (`sk-...`) key — Groq (`gsk_`) keys are refused since Groq is already the free default |
+| `saves on this computer are paused for safety` (the save journal lock) | An Indelible process stopped while holding the save journal lock, so every save on this machine waits rather than risk two writers on one wallet (5.8.8) | Run `indelible-mcp wallet --unlock-journal`, or ask your assistant to use `wallet_unlock_journal`. It clears the lock only after proving the process that held it is gone; if a save is genuinely in progress it says so and clears nothing |
+| `CONFIG_UNREADABLE` | `~/.indelible/config.json` exists but could not be read or parsed. Nothing was changed (5.8.8; before this release a failed read could be written back as an empty file over your key) | If it is your wallet file, restore it from your backup. Do not let anything rewrite it first. If you have no backup, contact support at indeliblebsv@gmail.com before touching the file |
+| `CONFIG_BUSY` | `~/.indelible/config.json` is open in another program that does not share it (Windows). Nothing was changed | Close the other program (an editor, a sync client) and retry |
+| `CONFIG_WOULD_DROP_KEY` | A settings write would have removed the wallet key from a file that holds one, and was refused. Nothing was written | Nothing to do; the refusal is the protection. If it repeats, contact support at indeliblebsv@gmail.com |
+| `RESTORE_PATH_ESCAPES` (in a project restore's error list) | A saved project contains a path that would land outside the folder you asked the restore to use (an absolute path, a `..` climb, or a link out). That file is not written (5.8.8) | Restore into an empty folder you chose; the files that fit inside it restore, the ones that would escape are listed in the result's errors and skipped |
 
 ---
 
@@ -381,6 +390,8 @@ This creates a standalone `indelible.exe` — no Node.js required on the target
 | `last_tx_id` | *(auto)* Last committed tx |
 | `diary` | `{ apiKey, provider, model, name }` — companion config (xAI `xai-...` or OpenAI `sk-...` key; Groq is the keyless free default) |
 
+**How this file is written (5.8.8).** Every write is all-or-nothing: a temp file is written and fsynced, then swapped into place, so a crash mid-write leaves the old file intact. On Windows and Linux every Indelible process on the machine takes one lock before it reads, changes and writes this file, so two saves can no longer interleave. A write that cannot read the file refuses (`CONFIG_UNREADABLE`, `CONFIG_BUSY`) instead of treating an unreadable file as an empty one, which is how a wallet key could be lost before this release. On macOS the all-or-nothing write and the refusals apply, but concurrent Indelible processes are not yet serialized there; run one at a time. None of this replaces a backup of the file.
+
 ---
 
 ## Wallet

package/CUSTOMER_AGENT_HANDBOOK.md

@@ -19,7 +19,7 @@ Your day-one roster is small and real: two guards, one companion, and one memory
 
 That is the whole list **for this package**. Your agent crew is a different thing and it lives in the web app: sign in at indelible.one, open the Sanctuary, and birth sixteen agents derived from your own wallet. They are yours today, not a preview. Section 7 walks through it, and section 8 is honest about the two parts that are still unfinished.
 
-### The 32 tools you can call today
+### The 36 tools you can call today
 
 Grouped by what they cost:
 
@@ -33,6 +33,8 @@ Grouped by what they cost:
 - **Starter recipes (free):** `list_agent_recipes` — eight ready-made blueprints you can hire instead of writing one from a blank page: a copy chief, a researcher, a deal reviewer, a code critic, a devil's advocate, a marshal, a ledger clerk, a negotiator. Birth any of them with `birth_custom_agent` and `recipe: '<id>'`. You choose the name, the identity still derives from your own wallet, and anything you set yourself overrides the blueprint. These are the same blueprints the web Forge offers, so an agent you make in the terminal and one you make in the browser are the same being. (Our own citizens' instructions are not among them; those stay with the operator. What travels is a recipe, never a key.)
 - **Your own agents (free, local):** `birth_custom_agent` — create an agent of your own: name it, pick the kind of work it handles, write its instructions. Its identity derives from your wallet, so it is recoverable from that wallet forever and is never random. · `run_custom_agent` — run one and get back advice signed with that agent's own key, so anyone can verify which agent said it. · `convene_chamber` — put three of your agents in a room to decide something: one proposes, one argues against, a third rules, and each signs its own position. · `transmute_agents` — blend two of your agents into a third. Keys never mix; only the written instructions combine.
 - **Sharing:** `share_session` (send one of your saved sessions to another address — Pro, it is a real on-chain write) · `load_shared` (read what someone shared with you — free)
+- **Strongbox (free, local):** `strongbox_status` looks at what your own machine is holding · `strongbox_consent` records your yes · `strongbox_clean` acts, and refuses unless your yes was recorded first (section 2 explains what "safe to remove" means)
+- **Wallet (free, local):** `wallet_unlock_journal` — clears a save journal lock left behind by an Indelible process that died, and only after proving that process is gone. If a save ever says saves on this computer are paused for safety, this is the tool your assistant uses; nothing else is touched, and with nothing to clear it says so
 - **Everything else:** `x402_fetch` (pays real sats to paid endpoints, capped at 10,000 sats per request unless you raise it), `report_bug`
 
 One important nuance on "free": free means no subscription. On-chain writes still cost miner fees, paid in sats from your own wallet. Each save costs less than a cent. Diary and Duo saves are not Pro-gated; they only need a few sats in the wallet.
@@ -71,6 +73,8 @@ removed.) This is what each one does and why it is there.
 
 ⚠️ **Just updated? Restart your assistant before you ask.** Quit and reopen whatever app you run Indelible in — Claude Desktop, Claude Code, Cursor, or any other MCP client. It reads the list of things it can do once, when it starts, so if you updated while it was running it is still holding the old list and will tell you the cleanup does not exist. Restart, then ask again.
 
+**Your wallet file is safer from 5.8.8, and still worth backing up.** The file that holds your key, `~/.indelible/config.json`, used to be rewritten in place on every settings save, so two saves landing at the wrong moment could leave it empty. Now every write of it is all-or-nothing, on Windows and Linux every Indelible process on your machine takes a lock before writing it, and a write that cannot read the file stops and says so (`CONFIG_UNREADABLE`, `CONFIG_BUSY`) rather than writing an empty file over your key. On a Mac the all-or-nothing write is there but two Indelible processes at the same instant are not yet held apart, so run one at a time. If you ever see `CONFIG_UNREADABLE` on that file, restore it from your backup before anything else touches it. Keep the backup; no software makes a lost key recoverable.
+
 Free tier and the hooks: every hook runs for everyone. Restore, the time card, style loading, and Guardrails are fully free. The pre-compaction **save** is the one piece that needs Pro. On a free wallet the hook still fires, but instead of saving it prints the plain notice that saving is a Pro feature. That is not an error. Your reads, diary, and recall keep working.
 
 Hook installation is idempotent. If you ever suspect the hooks are missing, run:

package/README.md

@@ -6,6 +6,8 @@ Blockchain-backed memory for Claude Code **and OpenAI's Codex CLI**. Save your A
 
 **New in 5.3.x — the drift wire: your two pilots talk to each other.** A durable wire on your machine where Claude and Codex hold a real conversation — every message kept in an append-only log on your disk, each reply citing the one it answers. (The local wire log lives and dies with this machine — no save uploads it. What rides Bitcoin is what you save: your sessions, and the machine-to-machine verbs below. Wire messages survive only as far as a pilot read them into a session you then saved.) Deliveries are **polled** in this release — the waiting verb checks the wire every few seconds, and nothing rings a bell between checks (the doorbell machinery ships but no command sends the ring yet; the ringer arrives next release). A **summoner** goes further: when a message sits unanswered, `indelible-mcp drift summon` conjures a *fresh* pilot through its own vendor CLI to read the wire and reply — and because the memory is permanent, it arrives already caught up, then saves its own session back to the chain. Those show up in your Context tab as **Summoned Sessions** — written by a called-up mind, never confused with your own work. And a **brake** only you hold: `indelible-mcp drift pause` freezes both pilots, no wallet needed. Full manual: indelible.one → Docs → The Drift Wire.
 
+**New in 5.8.8 — the wallet file can no longer be wiped by a save race, and a stuck save has a door.** The file that holds your key (`~/.indelible/config.json`) used to be rewritten in place by every settings save, so a read that landed in the middle of another write could come back empty and be written straight back over your key. That path is closed: every write of that file is now all-or-nothing (a temp file swapped into place), on Windows and Linux every Indelible process on the machine takes one lock before it writes, and a write that cannot read the file refuses instead of guessing. The refusals a save may now print are `CONFIG_UNREADABLE` (the file exists but could not be read; nothing was changed; if this is your wallet file, restore it from your backup rather than letting anything rewrite it) and `CONFIG_BUSY` (another program has the file open; close it and retry). On macOS the all-or-nothing write and the refusals are there, but two Indelible processes writing at the same instant are not yet held apart, so run one at a time. Back that file up regardless. Two more things ride along: if an Indelible process dies while holding the save journal lock, saves on that computer pause for safety and the message names the way out, `indelible-mcp wallet --unlock-journal` (or ask your assistant to use `wallet_unlock_journal`), which clears the lock only after proving the process that held it is gone; and a project restore now stays inside the folder you asked for, refusing a saved path that would climb out of it (`RESTORE_PATH_ESCAPES`) instead of writing there. After you restart your assistant it serves 36 tools (5.8.7 served 35); nothing was removed.
+
 > **New here?** Two guides ship with this package: **CUSTOMER_AGENT_HANDBOOK.md** (your agents on day one — the Witness, the Scribe, what runs for you) and **CLI_HANDBOOK.md** (every command + common errors). They are in the package install folder, or on indelible.one/docs.
 
 ## Quick Start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "indelible-mcp",
-  "version": "5.8.7",
+  "version": "5.8.8",
   "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",