@blockula/mcp 0.5.1 → 1.0.2

package/dist/index.js

@@ -1,25 +1,27 @@
 #!/usr/bin/env node
 // 🧛 Blockula MCP server. Add to Claude Code with:
-//   claude mcp add blockula -- npx -y @blockula/mcp                      (the public testnet)
-//   claude mcp add blockula -- npx -y @blockula/mcp --network local      (a `blockula dev` chain)
+//   claude mcp add blockula -- npx -y @blockula/mcp                      (a `blockula dev` chain)
+//   claude mcp add blockula -e BLOCKULA_RPC=https://<node> -- npx -y @blockula/mcp   (a chain you launched)
 //
 // Env:
-//   BLOCKULA_NETWORK    mainnet, testnet (default), local or custom (same as --network)
-//   BLOCKULA_RPC        node URL (default: the network's public RPC; required for custom, and for
-//                       mainnet until public RPCs are built in)
-//   BLOCKULA_CHAIN_ID / BLOCKULA_GENESIS_HASH   pin the chain the node must be on
+//   BLOCKULA_NETWORK    local (default), testnet or custom (same as --network)
+//   BLOCKULA_RPC        node URL (default: http://localhost:7070 for local; required for testnet,
+//                       whose public node was retired, and for custom)
+//   BLOCKULA_CHAIN_ID / BLOCKULA_GENESIS_HASH   pin the chain the node must be on (a node that says
+//                       it's on blockula-1 is refused unless BLOCKULA_CHAIN_ID=blockula-1)
 //   BLOCKULA_WITNESSES  other nodes of the same chain (comma-separated URLs): .boo names that get
 //                       signed (send, stake, unstake, use_account) are proven against them, and the
 //                       height each tx is signed against must not be ahead of their heads (nor, in
 //                       any case, past what the chain's genesis clock allows). Without
 //                       them a send signs the name itself (the chain resolves it when it runs), and
 //                       where an address is needed (stake, unstake, use_account) a name is the
-//                       node's word: on mainnet (any node on blockula-1, however it was configured)
-//                       the address must be confirmed first.
+//                       node's word: on blockula-1 (BLOCKULA_CHAIN_ID=blockula-1) the address must be
+//                       confirmed first. Unset, no node is a witness (no chain has public RPCs
+//                       built in); `none` says so explicitly.
 //   BLOCKULA_HOME       where the agent wallet lives (default ~/.blockula)
 //   BLOCKULA_MAX_SEND   max FANG one call moves (sent, staked, escrowed, paid for a name, bonded; default 100)
-//   BLOCKULA_MAX_DAILY  max FANG leaving the account per UTC day through this MCP, fees included
-//                       (default BLOCKULA_MAX_SEND + 1 FANG for fees, so one full-size call fits)
+//   BLOCKULA_MAX_DAILY  max FANG leaving the account per UTC day through this MCP on each chain, fees
+//                       included (default BLOCKULA_MAX_SEND + 1 FANG for fees, so one full-size call fits)
 //   BLOCKULA_TIMEOUT_MS how long one request to the node may take (default 15000, at most 2147483647)
 //   BLOCKULA_TX_WAIT_MS how long a tx tool waits for finality before answering "pending" (default 15000)
 //   BLOCKULA_BIN        path to the `blockula` binary (default: of ~/.blockula/bin/blockula from `blockula release
@@ -29,43 +31,38 @@
 //   BLOCKULA_RELEASE_KEY_ID     the release signing key id to trust (until it's built in; it must
 //                       agree with the built-in one and with ~/.blockula/release-key-id, if pinned)
 // The network never changes while the server runs (WAL-4): see network.ts. Spending caps: see
-// spend.ts (reserved before a tx is sent). Chain text is untrusted: see untrusted.ts. When acting
-// for a user's account via a session key, the chain also enforces that key's limit.
+// spend.ts (reserved before a tx is sent) and budget.ts (the caps, and what's refused before
+// signing). Chain text is untrusted: see untrusted.ts. When acting for a user's account via a
+// session key, the chain also enforces that key's limit. The account acted for is kept per chain
+// (accounts.ts), and one tx at a time is built per account (locks.ts).
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { ApiError, Client, HeightAheadError, MAINNET_CHAIN_ID, NAMESPACES, RequestTimeoutError, TxFailedError, TxPendingError, Wallet, bareName, checkTimeoutMs, decodeAccount, describeKind, encodeKeyGrant, isAddress, proposalDigest, formatFang, paramsOf, parseFang, proposalSummary, stakeSummary, txDropped, txId } from "@blockula/sdk";
+import { ApiError, Client, HeightAheadError, NAMESPACES, RequestTimeoutError, TxFailedError, TxPendingError, Wallet, addressPrefix, bareName, baseFee, decodeAccount, describeKind, encodeKeyGrant, isAddress, proposalDigest, formatFang, paramsOf, proposalSummary, stakeSummary, txDropped, txId } from "@blockula/sdk";
 import { spawn, spawnSync, execFileSync } from "node:child_process";
 import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { z } from "zod";
-import { KNOWN_CLOCKS, KNOWN_GENESIS, KnownChains, clockFrom, completePin, effectivePin, mismatch, mismatchError, resolveNetwork } from "./network.js";
+import { BLOCKULA_1, KNOWN_CLOCKS, KNOWN_GENESIS, KnownChains, clockFrom, completePin, defaultWitnesses, effectivePin, mismatch, mismatchError, networkLabel, resolveNetwork, unpinnedBlockula1, unusableChain } from "./network.js";
+import { WALLET_URLS, actingFor, checkCode, createWalletFile, ignoredNote, newWalletFile, readWalletFile, secretOf, setActingFor, writeWalletFile } from "./accounts.js";
+import { aboutBlocks, allowanceOf, amountArg, capsFrom, configError, dropsOf, keyOn, msFrom, preflight, spendableNow } from "./budget.js";
+import { AccountLocks, NonceTracker } from "./locks.js";
 import { PIN_FILE, REPO, RELEASE_KEY_ID, binPaths, checkBinaryVersion, fetchVerifiedRelease, latestTagFrom, pickNodeBinary, readReleasePin, releaseKeyIdFrom } from "./release.js";
 import { SignedTxs, onChain } from "./signed.js";
-import { SpendLedger } from "./spend.js";
-import { SERVER_INSTRUCTIONS, UNTRUSTED_NOTE, chainData, clean } from "./untrusted.js";
+import { SpendLedger, chainKey } from "./spend.js";
+import { PROGRAM_NOTE, SERVER_INSTRUCTIONS, UNTRUSTED_NOTE, chainData, clean, codeView, programView, provenDifferences, viewView } from "./untrusted.js";
 const HOME = process.env.BLOCKULA_HOME ?? join(homedir(), ".blockula");
 const WALLET_FILE = join(HOME, "agent-wallet.json");
-const MAX_SEND = parseFang(process.env.BLOCKULA_MAX_SEND ?? "100");
+const SPEND_FILE = join(HOME, "agent-spend.json");
 /**
- * Fees count toward BLOCKULA_MAX_DAILY (they leave the account too), so by default the daily cap
- * is the per-call cap plus this much for fees: one call of BLOCKULA_MAX_SEND fits in a day, with
- * room for the fees of many more small txs (audit review-fix-clients-3).
+ * The caps' and durations' variables, parsed once inside a try (AGENT-15): a bad one is reported by
+ * every tool, as a bad network is, instead of exiting before the client can be told why (the
+ * defaults stand in meanwhile, and nothing uses them).
  */
-const DAILY_FEE_ALLOWANCE = parseFang("1");
-const MAX_DAILY = process.env.BLOCKULA_MAX_DAILY ? parseFang(process.env.BLOCKULA_MAX_DAILY) : MAX_SEND + DAILY_FEE_ALLOWANCE;
-const MAX_DAILY_TEXT = process.env.BLOCKULA_MAX_DAILY ? `BLOCKULA_MAX_DAILY=${process.env.BLOCKULA_MAX_DAILY} FANG` : `BLOCKULA_MAX_DAILY, by default BLOCKULA_MAX_SEND + 1 FANG for fees = ${formatFang(MAX_DAILY)}`;
-const SPEND_FILE = join(HOME, "agent-spend.json");
-const msEnv = (name, fallback) => {
-    const v = process.env[name];
-    if (v === undefined || v === "")
-        return fallback;
-    if (!/^\d+$/.test(v))
-        throw new Error(`${name} must be a positive number of milliseconds`);
-    return checkTimeoutMs(Number(v), name);
-};
-const TIMEOUT_MS = msEnv("BLOCKULA_TIMEOUT_MS", 15_000);
-const TX_WAIT_MS = msEnv("BLOCKULA_TX_WAIT_MS", 15_000);
+const CONFIG_ERROR = configError(process.env);
+const CAPS = capsFrom(CONFIG_ERROR ? {} : process.env);
+const TIMEOUT_MS = CONFIG_ERROR ? 15_000 : msFrom(process.env, "BLOCKULA_TIMEOUT_MS", 15_000);
+const TX_WAIT_MS = CONFIG_ERROR ? 15_000 : msFrom(process.env, "BLOCKULA_TX_WAIT_MS", 15_000);
 const KNOWN_CHAINS = new KnownChains(join(HOME, "known-chains.json"));
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 // install_node's binary has a path of its own: it never replaces the one `blockula release install`
@@ -89,8 +86,8 @@ function nodeBinary() {
 }
 /** Says which binary ran, and when it isn't this MCP's version. */
 const ranWith = (b) => `Ran ${b.path}${b.version ? ` (${b.version})` : ""}${b.matches === false && b.path !== "blockula" ? `, not this MCP's version (${VERSION}): install_node v${VERSION} (or \`blockula release install v${VERSION}\`) gets one that is.` : "."}`;
-/** Testnet economics, said wherever Hunts and the contribution pool come up. */
-const NO_VALUE = "Testnet FANG, Hunts and Soul have no monetary value and come with no promise of any mainnet allocation.";
+/** Said wherever Hunts and the contribution pool come up: on every chain, FANG, Hunts and Soul have no value. */
+const NO_VALUE = "FANG, Hunts and Soul have no value.";
 function releaseTarget() {
     const key = `${process.platform}-${process.arch}`;
     return { "darwin-arm64": "aarch64-apple-darwin", "darwin-x64": "x86_64-apple-darwin", "linux-x64": "x86_64-unknown-linux-gnu", "linux-arm64": "aarch64-unknown-linux-gnu" }[key] ?? null;
@@ -105,14 +102,34 @@ catch (e) {
     NET_ERROR = e;
 }
 const RPC = NET?.rpc ?? "";
+/** A Hunt or contribution tool's description: `text`, then NO_VALUE. */
+const described = (text) => `${text} ${NO_VALUE}`;
 let pinned = null;
 /** The chain `pinned` is held to (tx_status reads a signed tx's record only on the chain it was signed for). */
 let pinnedChain = {};
+/** The witnesses `pinned` checks names and heights against: configured, or the public RPCs for your own node. */
+let activeWitnesses = [];
+/** Why this MCP can't run as configured (the network, a cap or a duration), or null. */
+const BAD_CONFIG = NET_ERROR ?? CONFIG_ERROR;
 function network() {
-    if (!NET)
-        throw new Error(`The Blockula MCP isn't configured correctly: ${NET_ERROR?.message}`);
+    if (!NET || BAD_CONFIG)
+        throw new Error(`The Blockula MCP isn't configured correctly: ${BAD_CONFIG?.message}`);
     return NET;
 }
+/**
+ * The pinned chain as the ledger, the key file and the nonce tracker key it: `<chain_id>
+ * <genesis_hash>`. `chain()` refused a chain id or genesis hash that doesn't fit, so this is
+ * undefined only for a node that reports no genesis hash (and can't sign).
+ */
+function chainNow() {
+    const { chainId, genesisHash } = pinnedChain;
+    try {
+        return chainId && genesisHash ? chainKey(chainId, genesisHash) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * The client for the configured network, pinned to its chain. The first call checks the node's
  * chain id, genesis hash and prefix against the network's pins (and what was remembered for it);
@@ -124,17 +141,30 @@ async function chain() {
     const net = network();
     const pin = effectivePin(net, KNOWN_CHAINS.get(net));
     const status = await new Client(net.rpc, { timeoutMs: TIMEOUT_MS }).status();
+    // A chain id or genesis hash this MCP can't key its ledger, locks and grant files by is refused
+    // here, once, so nothing later has to check what a node named (audit MCK-3).
+    const unusable = unusableChain(status);
+    if (unusable)
+        throw mismatchError(net, unusable, KNOWN_CHAINS.file, false);
     const why = mismatch(pin, status);
     if (why)
         throw mismatchError(net, why, KNOWN_CHAINS.file);
+    // blockula-1 only where the user pinned it: forgetting what was remembered wouldn't help.
+    const unpinned = unpinnedBlockula1(pin, status);
+    if (unpinned)
+        throw mismatchError(net, unpinned, KNOWN_CHAINS.file, false);
     const full = completePin(pin, status);
     KNOWN_CHAINS.save(net, full);
     const pins = { chainId: full.chainId, genesisHash: full.genesisHash, prefix: full.prefix, timeoutMs: TIMEOUT_MS };
     // Witnesses are held to the same chain; with them, names are proven (Client.resolution) and a
     // height ahead of their heads is refused. The chain's genesis clock bounds the height too.
+    // Unset, your own node of a public network (its chain known only now, for a local or custom
+    // node) is checked against that network's public RPCs (OPERATOR-6).
     const genesisClock = await clockOf(net, full);
-    pinned = new Client(net.rpc, { ...pins, genesisClock, witnesses: net.witnesses.map((w) => new Client(w, pins)) });
+    const witnesses = net.witnessesSet || net.witnesses.length ? net.witnesses : defaultWitnesses(full.chainId, net.rpc);
+    pinned = new Client(net.rpc, { ...pins, genesisClock, witnesses: witnesses.map((w) => new Client(w, pins)) });
     pinnedChain = { chainId: full.chainId, genesisHash: full.genesisHash, prefix: full.prefix };
+    activeWitnesses = witnesses;
     return pinned;
 }
 /**
@@ -181,91 +211,194 @@ async function moduleRead(what, read) {
         throw e;
     }
 }
-// ---- spending caps (BLOCKULA_MAX_SEND per call, BLOCKULA_MAX_DAILY per UTC day) ----
-const LEDGER = new SpendLedger(SPEND_FILE, MAX_DAILY, MAX_DAILY_TEXT);
+// ---- spending caps (BLOCKULA_MAX_SEND per call, BLOCKULA_MAX_DAILY per UTC day and chain) ----
+const LEDGER = new SpendLedger(SPEND_FILE, CAPS.maxDaily, CAPS.dailyText);
 /** The txs this MCP signed (their valid_until, for tx_status): see signed.ts. */
 const SIGNED = new SignedTxs(join(HOME, "agent-txs.json"));
+/** One tx at a time per account, and the last nonce signed while it's pending: see locks.ts. */
+const LOCKS = new AccountLocks(join(HOME, "nonces"));
+const NONCES = new NonceTracker(join(HOME, "nonces"));
 /**
- * Whether this is real money: the configured network is mainnet, or the chain the client is
- * pinned to is (audit gap-7-1, R1 bypass): BLOCKULA_RPC alone pointing at a node on blockula-1 is
- * a "custom" network, and gets mainnet's rules all the same. The client is pinned to the chain id
- * of its first status, and refuses any later status that reports another, so this is the chain
- * every signature it makes is for.
+ * Whether this is blockula-1, where an address that was resolved from a name by one node isn't
+ * signed until the user confirms it (audit gap-7-1, R1 bypass): decided by the chain the client is
+ * pinned to, not by what the configuration calls the network, so BLOCKULA_RPC alone at a node on
+ * blockula-1 gets the same rule. The client is pinned to the chain id of its first status, and
+ * refuses any later status that reports another, so this is the chain every signature it makes is
+ * for.
  */
-async function realMoney(client) {
-    return network().mainnet || (await client.status()).chain_id === MAINNET_CHAIN_ID;
+async function onBlockula1(client) {
+    return (await client.status()).chain_id === BLOCKULA_1;
 }
 const isInFlight = (r) => typeof r === "object" && r !== null && "tx_id" in r && ["pending", "unknown", "dropped"].includes(r.status);
-/**
- * Signs `action`, reserves what it can cost (the spend plus the tx's max fee) against today's
- * budget under its (account, nonce) slot, and only then submits it. Final: the unused part of the
- * max fee is given back and the tx is returned. Everything else stays counted: failed in a block
- * (its fee was charged), dropped, pending, timed out, unknown, and refused too, since the node's
- * refusal is only its word and it may relay the signed tx anyway (audit F68, F72, F74). A refused
- * tx stops counting twice once this MCP signs another tx with its nonce (the next send, after an
- * honest refusal): see spend.ts.
- */
-async function submitCapped(w, action, spend, memo = "") {
-    const perCall = spend.perCall ?? spend.amount;
-    if (perCall > MAX_SEND)
-        throw new Error(`${spend.what ?? "amount"} (${formatFang(perCall)}) exceeds this agent's per-call limit (BLOCKULA_MAX_SEND=${process.env.BLOCKULA_MAX_SEND ?? "100"} FANG)`);
-    const tx = await w.build(action, memo, { resolutions: spend.resolutions ?? [] });
-    const id = txId(tx);
-    const maxFee = BigInt(tx.fee);
-    const slot = { account: tx.from, nonce: tx.nonce };
-    const reservation = LEDGER.reserve(spend.amount + (spend.extra ?? 0n) + maxFee, slot);
-    const counted = formatFang(LEDGER.held(slot));
-    // Before it can reach any node: tx_status reads its valid_until from here (review-fix-clients-2).
+/** What a result's tx cost (the fee charged, once final) or can cost (its max fee, in flight). Kept out of the result's JSON. */
+const COST = new WeakMap();
+/** The fee `w.build` will set for this action (base fee for its size + tip), or undefined when it can't be priced here. */
+function feeFor(w, status, action, memo, fees) {
     try {
-        SIGNED.add(id, { valid_until: tx.valid_until, account: tx.from, nonce: tx.nonce, chain_id: tx.chain_id, genesis_hash: tx.genesis_hash });
+        if (typeof status?.chain_id !== "string" || typeof status?.genesis_hash !== "string")
+            return undefined;
+        // Every number in the signing bytes is fixed width, so a draft prices the same as the tx.
+        const draft = { chain_id: status.chain_id, genesis_hash: status.genesis_hash, from: w.account, nonce: 0, fee: "0", tip: w.tip.toString(), valid_until: 0, action, memo };
+        return baseFee(draft, fees?.suggested) + w.tip;
     }
     catch {
-        /* informational only: tx_status then says valid_until is unknown */
-    }
-    const inFlight = (status, why) => ({
-        status,
-        tx_id: id,
-        valid_until: tx.valid_until,
-        counted_toward_daily_limit: counted,
-        next: `${why} It can still execute until block ${tx.valid_until}, so it already counts toward the daily limit. Do NOT send it again: check it with tx_status (tx_id ${id}) and tell the user it isn't confirmed yet.`,
-        explorer: explorer(`tx/${id}`),
-    });
-    try {
-        await w.client.submit(tx, false);
+        return undefined;
     }
-    catch (e) {
-        // The node says it refused it. An honest node then never relayed it, but a lying one can say
-        // so and relay it anyway, so the reservation stays: the next tx this MCP signs with the same
-        // nonce (after a real refusal, the node's next nonce didn't move) takes the slot over.
-        if (e instanceof ApiError && e.status >= 400 && e.status < 500) {
-            throw new Error(`${e.message} (the node refused tx ${id}; it still counts toward today's limit until another tx reuses its nonce ${tx.nonce}, since a node could refuse a tx and relay it anyway)`);
+}
+/** The same tx with another nonce, signed again: the nonce is fixed width, so its size and fee don't change. */
+function withNonce(w, tx, nonce) {
+    const { public_key: _key, signature: _sig, ...unsigned } = tx;
+    return w.sign({ ...unsigned, nonce });
+}
+/** A node's "bad nonce" refusal: the nonce it expects and the one it got. */
+const BAD_NONCE = /bad nonce: expected (\d+), got (\d+)/i;
+/**
+ * Submits a signed tx. A node that says it expects a later nonce than this tx's may be mid-block:
+ * while a block persists, admission can count the txs it just ran twice and refuse the next
+ * correct nonce (PERF-1; seen here against a dev chain). #62 fixes it in the node, but nodes
+ * from before it still do it. The same signed tx is offered again a few times, which is safe:
+ * it's one tx, so at most one copy runs. A nonce another tx really took gets the same refusal
+ * each time, and that one is answered.
+ */
+async function submitPatiently(client, tx) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await client.submit(tx, false);
+        }
+        catch (e) {
+            const m = e instanceof ApiError && e.status >= 400 && e.status < 500 ? BAD_NONCE.exec(e.message) : null;
+            if (!m || Number(m[2]) !== tx.nonce || Number(m[1]) <= tx.nonce || attempt >= 4)
+                throw e;
+            await new Promise((r) => setTimeout(r, 300 * attempt));
         }
-        // Admitted, but the first read of its status failed: wait for it below like any other.
-        if (!(e instanceof TxPendingError))
-            return inFlight("unknown", `The node didn't answer clearly (${clean(String(e?.message ?? e), 200)}), so the tx (${id}) may or may not have arrived.`);
     }
+}
+/**
+ * Signs `action`, reserves what it can cost (the spend plus the tx's max fee) against today's
+ * budget under its (chain, account, nonce) slot, and only then submits it. Final: the unused part
+ * of the max fee is given back and the tx is returned. Everything else stays counted: failed in a
+ * block (its fee was charged), dropped, pending, timed out, unknown, and refused too, since the
+ * node's refusal is only its word and it may relay the signed tx anyway (audit F68, F72, F74). A
+ * refused tx stops counting twice once this MCP signs another tx with its nonce (the next send,
+ * after an honest refusal): see spend.ts.
+ *
+ * Before anything is signed, what the chain would refuse by the node's own reads is refused here
+ * (budget.ts `preflight`: a session key's limits, what the account can move, a key that isn't on
+ * the account; AGENT-6), and so is what wouldn't fit today's budget. Building, signing and
+ * submitting hold the account's lock (locks.ts; AGENT-10), so parallel calls and other sessions
+ * take nonces one after another; waiting for finality doesn't.
+ */
+async function submitCapped(w, action, spend, memo = "") {
+    const perCall = spend.perCall ?? spend.amount;
+    if (perCall > CAPS.maxSend)
+        throw new Error(`${spend.what ?? "amount"} (${formatFang(perCall)}) exceeds this agent's per-call limit (${CAPS.sendText})`);
+    await w.client.addressPrefix();
+    const chainId = chainNow();
+    const lockKey = `${chainId ?? "unknown-chain"} ${w.account}`;
+    const sent = await LOCKS.run(lockKey, async () => {
+        const [status, account, fees] = await Promise.all([w.client.status(), w.client.account(w.account).catch(() => null), w.client.fees().catch(() => null)]);
+        const height = safeInt(status.height) ?? 0;
+        const fee = feeFor(w, status, action, memo, fees);
+        preflight({ account, keyId: w.keyId, actingFor: w.account, action: action.type, outflow: spend.outflow ?? 0n, opening: spend.extra ?? 0n, fee: fee ?? 0n, height: height + 1, blockTimeMs: w.client.genesisClock?.blockTimeMs });
+        // Today's budget, before signing: what the tx's slot would add (a nonce already used today counts once).
+        if (fee !== undefined && safeInt(account?.next_nonce) !== undefined) {
+            const need = spend.amount + (spend.extra ?? 0n) + fee;
+            const held = LEDGER.held({ account: w.account, nonce: account.next_nonce, chain: chainId });
+            const adds = need > held ? need - held : 0n;
+            const today = LEDGER.spent(chainId);
+            if (today + adds > CAPS.maxDaily)
+                throw new Error(`this would exceed the agent's daily limit (${CAPS.dailyText}; ${formatFang(today)} already spent or in flight today on this chain, and this needs ${formatFang(adds)} more including fees). Nothing was signed.`);
+        }
+        let tx = await w.build(action, memo, { resolutions: spend.resolutions ?? [] });
+        // A node whose view lags (its mempool, or a block that just ran) mustn't hand out a nonce this MCP already used.
+        const floor = NONCES.floor(lockKey, height);
+        const bumped = floor !== undefined && tx.nonce < floor;
+        if (bumped)
+            tx = withNonce(w, tx, floor);
+        const id = txId(tx);
+        const slot = { account: tx.from, nonce: tx.nonce, chain: chainId };
+        const reservation = LEDGER.reserve(spend.amount + (spend.extra ?? 0n) + BigInt(tx.fee), slot);
+        // Before it can reach any node: tx_status reads its valid_until from here (review-fix-clients-2).
+        try {
+            SIGNED.add(id, { valid_until: tx.valid_until, account: tx.from, nonce: tx.nonce, chain_id: tx.chain_id, genesis_hash: tx.genesis_hash });
+        }
+        catch {
+            /* informational only: tx_status then says valid_until is unknown */
+        }
+        try {
+            await submitPatiently(w.client, tx);
+        }
+        catch (e) {
+            // The node says it refused it. An honest node then never relayed it, but a lying one can say
+            // so and relay it anyway, so the reservation stays: the next tx this MCP signs with the same
+            // nonce (after a real refusal, the node's next nonce didn't move) takes the slot over.
+            if (e instanceof ApiError && e.status >= 400 && e.status < 500) {
+                NONCES.settled(lockKey, tx.nonce);
+                // Signed past the node's nonce, and refused for it: the node is behind, or a tx this MCP
+                // counted on was dropped. Its view is used next time.
+                const lag = bumped && /bad nonce/i.test(e.message);
+                if (lag)
+                    NONCES.forget(lockKey);
+                const why = lag ? ` This MCP signed it with nonce ${tx.nonce}, past the last nonce it used; the node expects an earlier one, so the node is behind or that tx was dropped: check the last tx with tx_status, then try again.` : "";
+                throw new Error(`${e.message} (the node refused tx ${id}; it still counts toward today's limit until another tx reuses its nonce ${tx.nonce}, since a node could refuse a tx and relay it anyway)${why}`);
+            }
+            // Admitted, but the first read of its status failed: wait for it below like any other.
+            if (!(e instanceof TxPendingError))
+                return { tx, id, reservation, unclear: clean(String(e?.message ?? e), 200) };
+        }
+        NONCES.pending(lockKey, tx.nonce, tx.valid_until);
+        return { tx, id, reservation };
+    });
+    const { tx, id, reservation } = sent;
+    const maxFee = BigInt(tx.fee);
+    const counted = formatFang(LEDGER.held({ account: tx.from, nonce: tx.nonce, chain: chainId }));
+    // What became of its nonce: spent for good once it ran in a block; free again if it was dropped.
+    const ran = () => LOCKS.run(lockKey, async () => NONCES.ran(lockKey, tx.nonce)).catch(() => undefined);
+    const settle = () => LOCKS.run(lockKey, async () => NONCES.settled(lockKey, tx.nonce)).catch(() => undefined);
+    const inFlight = (status, why) => {
+        const r = {
+            status,
+            tx_id: id,
+            valid_until: tx.valid_until,
+            counted_toward_daily_limit: counted,
+            next: `${why} It can still execute until block ${tx.valid_until}, so it already counts toward the daily limit. Do NOT send it again: check it with tx_status (tx_id ${id}) and tell the user it isn't confirmed yet.`,
+            explorer: explorer(`tx/${id}`),
+        };
+        COST.set(r, { fee: maxFee, final: false });
+        return r;
+    };
+    if ("unclear" in sent)
+        return inFlight("unknown", `The node didn't answer clearly (${sent.unclear}), so the tx (${id}) may or may not have arrived.`);
     try {
         const done = await w.client.waitForTx(id, TX_WAIT_MS, tx.valid_until);
+        await ran();
         // Only a whole number of drops below the max fee gives anything back (audit gap-7-4).
         const charged = /^\d+$/.test(String(done.fee ?? "")) ? BigInt(done.fee) : maxFee;
         if (charged < maxFee)
             LEDGER.release(reservation, maxFee - charged);
+        if (done && typeof done === "object")
+            COST.set(done, { fee: charged < maxFee ? charged : maxFee, final: true });
         return done;
     }
     catch (e) {
         // Dropped from this node's mempool unrun: nothing was charged, but it isn't dead (audit review-fix-clients-2).
-        if (e instanceof TxFailedError && e.dropped)
+        if (e instanceof TxFailedError && e.dropped) {
+            await settle();
             return inFlight("dropped", `This node dropped tx ${id} from its mempool without running it (${clean(e.reason, 200)}), so nothing was charged yet, but another node may still include it.`);
-        if (e instanceof TxFailedError)
+        }
+        if (e instanceof TxFailedError) {
+            await ran();
             throw new Error(`tx ${id} failed${typeof e.tx?.height === "number" ? ` in block ${e.tx.height}` : ""}: ${clean(e.reason, 300)}. It ran, so its fee was charged, and it stays counted toward the daily limit (${counted}).`);
+        }
         return inFlight("pending", `Submitted (tx ${id}), but not final after ${Math.round(TX_WAIT_MS / 1000)} s.`);
     }
 }
 /**
- * What opening `to`'s account would burn on top of a transfer (0 if it exists). `/api/account`
- * answers for any address, with a zero balance and the address's own "original key" when it has
- * no account, so an account counts as existing only by what a missing one can't have: a balance
- * or a nonce. An existing account with neither is counted as new: the cap errs high, never low.
+ * What opening `to`'s account would burn on top of a transfer (0 if it exists): the node's
+ * `exists` and `creation_fee`. A node too old to say answers for any address, with a zero
+ * balance and the address's own "original key" when it has no account, so there an account
+ * counts as existing only by what a missing one can't have: a balance or a nonce. An existing
+ * account with neither is counted as new: the cap errs high, never low.
  */
 async function openingFee(client, to) {
     let a = null;
@@ -276,6 +409,9 @@ async function openingFee(client, to) {
         if (!(e instanceof ApiError && e.status === 404))
             throw e;
     }
+    // Nodes since protocol v1 say it outright: whether the account exists, and what opening it burns.
+    if (typeof a?.exists === "boolean" && /^\d+$/.test(String(a?.creation_fee ?? "")))
+        return a.exists ? 0n : BigInt(a.creation_fee);
     const exists = (/^\d+$/.test(String(a?.balance ?? "")) && BigInt(a.balance) > 0n) || (Number.isSafeInteger(a?.nonce) && a.nonce > 0);
     return exists ? 0n : reported((await client.fees()).account_creation_fee, "the account creation fee");
 }
@@ -303,14 +439,14 @@ async function namePrices(client, name) {
 /**
  * A name or address resolved for a field that needs an address (staking's validator, the account
  * use_account acts for; audit gap-7-1). With BLOCKULA_WITNESSES a name is proven against them
- * (`Client.resolution`). Without, it's the node's word: on mainnet that's not enough to sign real
- * money to, so the tool answers with the address for the user to confirm instead (the agent then
- * passes the address); elsewhere it signs and says it's unproven. Payments don't come here: they
- * sign the name (`Client.recipient`), which the chain resolves itself.
+ * (`Client.resolution`). Without, it's the node's word: on blockula-1 that's not enough to sign, so
+ * the tool answers with the address for the user to confirm instead (the agent then passes the
+ * address); elsewhere it signs and says it's unproven. Payments don't come here: they sign the
+ * name (`Client.recipient`), which the chain resolves itself.
  */
 async function resolved(client, input, role) {
     const res = await client.resolution(input);
-    if (!res.proven && (await realMoney(client))) {
+    if (!res.proven && (await onBlockula1(client))) {
         return {
             confirm: {
                 status: "not_sent",
@@ -318,7 +454,7 @@ async function resolved(client, input, role) {
                 [role]: clean(input, 100),
                 resolves_to: res.address,
                 resolved_by: clean(res.how, 300),
-                next: `Nothing was signed. This is real money, and ${clean(input, 100)} was resolved by one node without proof: a node can point a name anywhere. Show the user the address ${res.address}; only if they confirm it's the right ${role}, call this tool again with that address instead of the name. (With BLOCKULA_WITNESSES configured, names are proven and this step isn't needed.)`,
+                next: `Nothing was signed. ${clean(input, 100)} was resolved by one node without proof, and on ${BLOCKULA_1} that isn't signed: a node can point a name anywhere. Show the user the address ${res.address}; only if they confirm it's the right ${role}, call this tool again with that address instead of the name. (With BLOCKULA_WITNESSES configured, names are proven and this step isn't needed.)`,
             },
         };
     }
@@ -332,34 +468,61 @@ const recipientView = (r, role) => r.name === null ? {} : r.byChain ? { [`${role
 const txResult = (r, extra = {}) => isInFlight(r) ? r : { summary: clean(String(r.summary ?? "")), fee: r.fee_display, tx_id: r.id, block: r.height, ...extra, explorer: explorer(`tx/${r.id}`) };
 const server = new McpServer({ name: "blockula", version: VERSION }, { instructions: SERVER_INSTRUCTIONS });
 const text = (v) => ({ content: [{ type: "text", text: typeof v === "string" ? v : JSON.stringify(v, (_, x) => (typeof x === "bigint" ? x.toString() : x), 2) }] });
-function readWalletFile() {
-    return existsSync(WALLET_FILE) ? JSON.parse(readFileSync(WALLET_FILE, "utf8")) : null;
-}
-async function loadWallet() {
-    const f = readWalletFile();
+/** The agent's key and who it acts for, on the pinned chain (accounts.ts). Null before create_wallet. */
+async function walletState() {
+    const client = await chain();
+    const f = readWalletFile(WALLET_FILE);
     if (!f)
         return null;
-    const w = Wallet.fromSeed(f.seed, await chain());
-    if (f.account)
-        w.account = f.account;
-    return w;
+    const w = Wallet.fromSeed(secretOf(f), client);
+    const prefix = await client.addressPrefix();
+    const key = chainNow();
+    const acting = key ? actingFor(f, key, prefix) : { changed: false };
+    // A 0.5.1 account moved to this chain: written back whole, key included.
+    if (acting.changed)
+        writeWalletFile(WALLET_FILE, f);
+    if (acting.account)
+        w.account = acting.account;
+    return { w, f, acting, chain: key };
+}
+async function loadWallet() {
+    return (await walletState())?.w ?? null;
 }
 async function requireWallet() {
     const w = await loadWallet();
     if (!w)
-        throw new Error("No agent wallet yet — call create_wallet first.");
+        throw new Error("No agent wallet yet: call create_wallet first.");
     return w;
 }
+/** How clients show and gate each tool (AGENT-9): reads are read-only; what signs moves FANG (fees at least) on a public chain. */
+const READS = new Set(["status", "tx_status", "wallet_info", "check_name", "lookup", "latest_blocks", "my_stake", "list_proposals", "list_hunts", "contribution_pool", "my_contributions", "program_show", "program_view", "program_code"]);
+const MOVES = new Set(["send", "stake", "unstake", "withdraw_stake", "vote", "register_name", "renew_name", "fund_hunt", "submit_contribution", "link_github"]);
+const TITLES = {
+    status: "Network status", tx_status: "Transaction status", start_dev_node: "Start a dev chain", install_node: "Install the node", summon_chain: "Create a chain",
+    create_wallet: "Create the agent wallet", use_account: "Act for an account", wallet_info: "Wallet and budget", faucet: "Get test FANG", send: "Send FANG",
+    check_name: "Check a name", register_name: "Register a name", renew_name: "Renew a name", lookup: "Look up", latest_blocks: "Latest blocks",
+    stake: "Stake FANG", unstake: "Unstake FANG", withdraw_stake: "Withdraw unbonded stake", my_stake: "My stake", list_proposals: "Governance proposals", vote: "Vote",
+    list_hunts: "Hunts", link_github: "Link GitHub", fund_hunt: "Fund a Hunt", contribution_pool: "Contribution pool", submit_contribution: "Claim a contribution", my_contributions: "My contributions",
+    program_show: "Show a program", program_view: "Run a program's view", program_code: "Show a program's code",
+};
+const annotationsOf = (name) => READS.has(name)
+    ? { readOnlyHint: true, destructiveHint: false, openWorldHint: true }
+    : MOVES.has(name)
+        ? { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }
+        : { readOnlyHint: false, destructiveHint: false, openWorldHint: true };
 function tool(name, description, shape, run) {
-    server.registerTool(name, { description, inputSchema: shape }, (async (args) => {
+    server.registerTool(name, { title: TITLES[name], description, inputSchema: shape, annotations: { title: TITLES[name], ...annotationsOf(name) } }, (async (args) => {
         try {
+            // A bad configuration (the network, a cap, a duration) is every tool's answer (AGENT-15).
+            if (BAD_CONFIG)
+                throw new Error(`The Blockula MCP isn't configured correctly: ${BAD_CONFIG.message}`);
             return text(await run(args));
         }
         catch (e) {
             // Node errors are relayed, so they're cleaned like any chain text.
             const msg = clean(String(e?.message ?? e), 1000);
             const hint = /fetch failed|ECONNREFUSED/.test(msg)
-                ? ` (no node at ${RPC}${NET?.key === "local" ? " — call start_dev_node" : ""})`
+                ? ` (no node at ${RPC}${NET?.key === "local" ? " — call start_dev_node" : ""}${activeWitnesses.length ? `, or a witness isn't answering: ${activeWitnesses.join(", ")}; BLOCKULA_WITNESSES=none opts out` : ""})`
                 : e instanceof RequestTimeoutError
                     ? ` (the node at ${RPC} isn't answering)`
                     : e instanceof HeightAheadError
@@ -369,7 +532,7 @@ function tool(name, description, shape, run) {
         }
     }));
 }
-tool("status", "Blockula network status: which network and node you're connected to (and the chain it's pinned to), chain id, height, supply, fees burned, and the crypto in use. The network, its pins and how to change them are this MCP's own facts; `node_reports` is what the node says.", {}, async () => {
+tool("status", "Blockula network status: which network and node you're connected to (and the chain it's pinned to), the witnesses names are proven against, chain id, height, supply, fees burned, and the crypto in use. The network, its pins and how to change them are this MCP's own facts; `node_reports` is what the node says.", {}, async () => {
     const net = network();
     const client = await chain();
     const s = await client.status();
@@ -377,11 +540,13 @@ tool("status", "Blockula network status: which network and node you're connected
     // this MCP states about the network (audit F73).
     const pick = ["chain_id", "height", "finalized_height", "syncing", "epoch", "active_validators", "supply_display", "burned_display", "version", "protocol_version", "head_age_ms", "crypto"];
     return {
-        network: net.label,
-        real_money: net.mainnet || s.chain_id === MAINNET_CHAIN_ID,
+        network: networkLabel(net, pinnedChain.chainId),
         rpc: net.rpc,
+        // OPERATOR-6: who checks this node's answers about names and heights.
+        witnesses: activeWitnesses,
+        names: activeWitnesses.length ? `proven against ${activeWitnesses.length} node${activeWitnesses.length === 1 ? "" : "s"} (${activeWitnesses.join(", ")})` : `UNPROVEN: one node's word (${net.rpc}). BLOCKULA_WITNESSES lists other nodes to prove them against.`,
         pinned: chainData({ chain_id: s.chain_id, genesis_hash: s.genesis_hash, address_prefix: s.address_prefix }),
-        how_to_change: "The network is fixed while this MCP runs. The user changes it in the MCP's configuration (--network mainnet|testnet|local|custom, or BLOCKULA_RPC).",
+        how_to_change: "The network is fixed while this MCP runs. The user changes it in the MCP's configuration (--network local|testnet|custom, or BLOCKULA_RPC).",
         explorer: net.rpc,
         mcp_version: VERSION,
         node_reports: chainData(Object.fromEntries(pick.filter((k) => k in s).map((k) => [k, s[k]]))),
@@ -656,7 +821,7 @@ tool("start_dev_node", "Start a local Blockula dev chain (faucet + built-in expl
     }
     throw new Error(`node didn't start. See ${join(HOME, "dev-node.log")}`);
 });
-tool("install_node", "Download the prebuilt `blockula` node + CLI for this machine from the official GitHub release and install it to ~/.blockula/mcp-bin (never over the binary `blockula release install` keeps in ~/.blockula/bin), after the same checks as scripts/install.sh: the release must be the version asked for (`latest` is resolved to its tag first), SHA-256 against the release checksums, build provenance from that tag with a logged-in GitHub CLI, and the offline ML-DSA-65 release signature. Once the release key id is known (pinned in ~/.blockula/release-key-id by `blockula release install`, built in, or BLOCKULA_RELEASE_KEY_ID, which must all agree), a release without a valid signature is refused. It says which checks passed; with BLOCKULA_REQUIRE_VERIFY=1 it also requires provenance and refuses a release it can only checksum. Needed for start_dev_node and summon_chain; nothing else needs it.", { version: z.string().regex(/^(latest|v\d+\.\d+\.\d+)$/).default("latest") }, async ({ version }) => {
+tool("install_node", "Download the prebuilt `blockula` node + CLI for this machine from the official GitHub release into ~/.blockula/mcp-bin, after the same checks as scripts/install.sh (the version asked for, its checksum, provenance and release signature; the result says which passed). Needed for start_dev_node and summon_chain; nothing else needs it.", { version: z.string().regex(/^(latest|v\d+\.\d+\.\d+)$/).default("latest") }, async ({ version }) => {
     const target = releaseTarget();
     if (!target)
         throw new Error(`No prebuilt node for ${process.platform}/${process.arch}. Build from source: https://github.com/${REPO}`);
@@ -719,91 +884,194 @@ tool("install_node", "Download the prebuilt `blockula` node + CLI for this machi
         rmSync(tmp, { recursive: true, force: true });
     }
 });
-tool("summon_chain", "Create a brand-new Blockula chain (fresh genesis + validator key) that you can run as your own network.", { chain_id: z.string().regex(/^[a-z0-9-]{3,40}$/), faucet: z.boolean().default(true) }, async ({ chain_id, faucet }) => {
+tool("summon_chain", "Create a brand-new Blockula chain (fresh genesis + validator key) that you can run as your own network. `name`, `description` and `token` (its ticker) are what wallets and explorers show; the genesis hash binds them. A person launching one by hand runs `blockula launch`.", {
+    chain_id: z.string().regex(/^[a-z0-9-]{3,40}$/),
+    faucet: z.boolean().default(true),
+    name: z.string().min(1).max(48).optional(),
+    description: z.string().max(280).optional(),
+    token: z.string().regex(/^[A-Z][A-Z0-9]{1,7}$/).optional(),
+}, async ({ chain_id, faucet, name, description, token }) => {
     const bin = nodeBinary();
-    const out = execFileSync(bin.path, ["summon", chain_id, ...(faucet ? [] : ["--no-faucet"])], { encoding: "utf8" });
+    const brand = [...(name ? ["--name", name] : []), ...(name && description ? ["--description", description] : []), ...(token ? ["--token", token] : [])];
+    const out = execFileSync(bin.path, ["summon", chain_id, ...(faucet ? [] : ["--no-faucet"]), ...brand], { encoding: "utf8" });
     return `${out.trim()}\n${ranWith(bin)}`;
 });
-tool("create_wallet", "Create this agent's post-quantum (ML-DSA-65) wallet, stored locally. Returns the existing one if it already exists.", {}, async () => {
-    let w = await loadWallet();
-    const existed = !!w;
-    if (!w) {
-        w = Wallet.generate(await chain());
-        await w.client.addressPrefix();
-        mkdirSync(HOME, { recursive: true });
-        writeFileSync(WALLET_FILE, JSON.stringify({ address: w.address, key_id: w.keyId, seed: w.seedHex }, null, 2), { mode: 0o600 });
+/**
+ * What the agent can spend for an account now (AGENT-7), from its `/api/account` answer: what it
+ * can move, what's locked and until when, the session key's allowance this window, this MCP's
+ * caps, and the smallest of them. wallet_info and use_account return it.
+ */
+async function budgetOf(w, a) {
+    const client = w.client;
+    const head = safeInt((await client.status()).height) ?? 0;
+    // As of the next block, the first a tx can run in.
+    const height = head + 1;
+    const blockTimeMs = client.genesisClock?.blockTimeMs ?? 1000;
+    const key = keyOn(a, w.keyId);
+    const allowance = allowanceOf(key ?? undefined, height);
+    const transferable = dropsOf(a?.transferable);
+    const locked = dropsOf(a?.locked);
+    const today = LEDGER.spent(chainNow());
+    const dailyLeft = CAPS.maxDaily > today ? CAPS.maxDaily - today : 0n;
+    const spendable = spendableNow({ transferable, allowance, height, blockTimeMs, dailyLeft, caps: CAPS });
+    const locks = (Array.isArray(a?.locks) ? a.locks : []).filter((l) => safeInt(l?.until) !== undefined && dropsOf(l?.amount) !== undefined);
+    const lastEnd = locks.reduce((m, l) => Math.max(m, l.until), 0);
+    return {
+        ...(transferable !== undefined ? { transferable: formatFang(transferable) } : {}),
+        ...(locked !== undefined && locked > 0n
+            ? {
+                locked: formatFang(locked),
+                ...(lastEnd > 0 ? { locked_until_block: lastEnd, locked_until: lastEnd > head ? `${aboutBlocks(lastEnd - head, blockTimeMs)} from now` : "now" } : {}),
+                locks: locks.slice(0, 10).map((l) => ({ id: clean(String(l.id ?? ""), 60), amount: formatFang(dropsOf(l.amount)), until_block: l.until, ends_in: l.until > head ? aboutBlocks(l.until - head, blockTimeMs) : "now", vesting: l.vesting === true })),
+            }
+            : {}),
+        spendable_now: formatFang(spendable.amount),
+        spendable_now_limited_by: spendable.limitedBy,
+        spending_limits: spendable.limits,
+        ...(allowance
+            ? {
+                session_key: {
+                    limit: `${formatFang(allowance.limit)} per ${aboutBlocks(allowance.periodBlocks, blockTimeMs).replace(/^about /, "")}`,
+                    spent_this_period: formatFang(allowance.spent),
+                    left: formatFang(allowance.expired ? 0n : allowance.left),
+                    ...(allowance.resetsAt !== undefined ? { resets_at_block: allowance.resetsAt, resets_in: aboutBlocks(allowance.resetsAt - head, blockTimeMs) } : {}),
+                    expires_at_block: allowance.expiresAt,
+                    expires_in: allowance.expired ? "expired" : aboutBlocks(allowance.expiresAt - head, blockTimeMs),
+                },
+            }
+            : {}),
+        caps: { per_call: formatFang(CAPS.maxSend), per_day: formatFang(CAPS.maxDaily) },
+        spent_today: `${formatFang(today)} of ${formatFang(CAPS.maxDaily)} (${CAPS.dailyText}; on this chain; txs that are pending, dropped or refused still count until they're final or their nonce is reused)`,
+    };
+}
+/** An address of another network's prefix gets a clear answer (AGENT-14), not "isn't a valid address". */
+function otherNetwork(input, prefix) {
+    const p = addressPrefix(input.trim());
+    if (p === undefined || p === prefix)
+        return;
+    const which = p === "tboo" ? "a testnet address" : "another network's address";
+    throw new Error(`${clean(input, 100)} is ${which} (${p}1…), and this MCP is on ${networkLabel(network(), pinnedChain.chainId)}, whose addresses start with ${prefix}1. Nothing was signed.`);
+}
+/** What a payment cost (AGENT-1): the amount, the fee charged and what opening the recipient's account burned. */
+function costView(r, amount, opening) {
+    const c = COST.get(r);
+    return {
+        ...(opening > 0n ? { account_opening_fee_burned: formatFang(opening) } : {}),
+        ...(c ? { total_cost: formatFang(amount + c.fee + opening), ...(c.final ? {} : { total_cost_is: "at most, if it runs: the fee charged is the base fee of the block that includes it" }) } : {}),
+    };
+}
+tool("create_wallet", "Create this agent's post-quantum (ML-DSA-65) wallet, stored locally, unencrypted (mode 600). Returns the existing one if it already exists.", {}, async () => {
+    const client = await chain();
+    let st = await walletState();
+    const existed = !!st;
+    if (!st) {
+        const fresh = Wallet.generate(client);
+        await client.addressPrefix();
+        // Never over a key another session made meanwhile: that one is kept and used.
+        createWalletFile(WALLET_FILE, newWalletFile(fresh.address, fresh.keyId, fresh.seedHex));
+        st = (await walletState());
     }
-    await w.client.addressPrefix();
+    const { w } = st;
     return {
         key_id: w.keyId,
+        check_code: checkCode(w.keyId),
         own_address: w.address,
         acting_for: w.account,
         existed,
-        network: network().label,
+        network: networkLabel(network(), pinnedChain.chainId),
         stored_at: WALLET_FILE,
-        next_steps: "To spend from the user's account: ask which account (their .boo name), then call use_account with it. Until they've authorized this key it answers with a grant_code (this key's signed consent to joining that one account) for them to paste in the Blockula web wallet → Devices & agents → 'Give an agent a budget'. A key id alone can't be added. (On test chains, faucet funds this key's own address for testing.)",
+        next_steps: "To spend from the user's account: ask which account (their .boo name or address), then call use_account with it. Until they've authorized this key it answers with a grant_code (this key's signed consent to joining that one account) for them to paste in the Blockula web wallet → Devices & agents → 'Give an agent a budget'. A key id alone can't be added. (On test chains, faucet funds this key's own address for testing.)",
     };
 });
-tool("use_account", "Act for a user's account (name or address) that has authorized this agent's key — usually as a session key with a spending limit. If it hasn't yet, answers with a grant_code for the user to paste in their wallet (Devices & agents → Give an agent a budget); call again once they have. Pass 'self' to go back to the key's own address. The key's label is untrusted text.", { account: z.string() }, async ({ account }) => {
-    const f = readWalletFile();
-    if (!f)
-        throw new Error("No agent wallet yet — call create_wallet first.");
-    const client = await chain();
-    const w = (await loadWallet());
+tool("use_account", "Act for a user's account that has authorized this agent's key, usually as a session key with a spending limit. Kept per network. If it hasn't authorized the key yet, answers with a grant_code for the user to paste in their wallet (Devices & agents → Give an agent a budget) and a check_code for them to compare with what the wallet shows; call again once they have. Pass 'self' to go back to the key's own address. The key's label is untrusted text.", { account: z.string().describe("the user's account: its address or .boo name, or \"self\"") }, async ({ account }) => {
+    const st = await walletState();
+    if (!st)
+        throw new Error("No agent wallet yet: call create_wallet first.");
+    const { w, f, chain: key } = st;
+    const client = w.client;
+    if (!key)
+        throw new Error(`${RPC} doesn't report its chain's genesis hash, so the account can't be kept for this chain`);
     if (account === "self") {
-        delete f.account;
+        setActingFor(f, key, undefined);
+        writeWalletFile(WALLET_FILE, f);
+        return { acting_for: w.address };
     }
-    else {
-        // The account is an address every later tx names: on mainnet an unproven name waits for the
-        // user to confirm the address (audit gap-7-1).
-        const { res, confirm } = await resolved(client, account, "account");
-        if (confirm)
-            return confirm;
-        const addr = res.address;
-        // The account's own key list, not /api/key's list of accounts (which others can pad: audit gap-7-2).
-        const a = await client.account(addr);
-        const grant = (Array.isArray(a?.keys) ? a.keys : []).find((k) => k.key_id === w.keyId);
-        if (!grant) {
-            // Adding a key needs its consent to the account (audit gap-7-2): this key signs it for this
-            // one address, and the user's wallet refuses a code made for any other account.
-            return {
-                status: "not_authorized_yet",
-                account: clean(account, 100),
-                address: addr,
-                ...(res.name === null ? {} : { name_resolution: res.proven ? clean(res.how, 300) : `UNPROVEN: ${clean(res.how, 300)}` }),
-                key_id: w.keyId,
-                // The resolution itself, so the SDK refuses it too if it's unproven on mainnet.
-                grant_code: encodeKeyGrant(await w.keyGrant(res)),
-                next: `Nothing was signed on-chain. Give the user the grant_code (this agent key's consent to joining ${addr} only; it holds no secret and can't spend anything). They paste it in the Blockula web wallet → Devices & agents → 'Give an agent a budget' and choose a limit and an expiry. Then call use_account again.`,
-            };
+    otherNetwork(account, await client.addressPrefix());
+    // The account is an address every later tx names: on blockula-1 an unproven name waits for the
+    // user to confirm the address (audit gap-7-1).
+    const { res, confirm } = await resolved(client, account, "account");
+    if (confirm)
+        return confirm;
+    const addr = res.address;
+    const resolution = res.name === null ? {} : { name_resolution: res.proven ? clean(res.how, 300) : `UNPROVEN: ${clean(res.how, 300)}` };
+    // The account's own key list, not /api/key's list of accounts (which others can pad: audit gap-7-2).
+    const a = await client.account(addr);
+    // An address with no account can't add a key (that takes a tx, and a tx takes FANG): no grant to hand out.
+    if (a?.exists === false) {
+        return { status: "no_account", account: clean(account, 100), address: addr, ...resolution, next: `There's no account at ${addr} on ${networkLabel(network(), pinnedChain.chainId)}: nothing was signed. Check the address with the user (their wallet shows it under Devices & agents). An account exists once it has received FANG.` };
+    }
+    const grant = keyOn(a, w.keyId);
+    if (!grant) {
+        // Adding a key needs its consent to the account (audit gap-7-2): this key signs it for this
+        // one address, and the user's wallet refuses a code made for any other account.
+        const wallet = pinnedChain.chainId ? WALLET_URLS[pinnedChain.chainId] : undefined;
+        // The resolution itself, so the SDK refuses it too if it's unproven on blockula-1.
+        const grantCode = encodeKeyGrant(await w.keyGrant(res));
+        // AGENT-5: thousands of characters are easy to mangle when retyped; a file can be copied whole.
+        // Its name is a chain id `chain()` checked (no path separator can be in it) and an address.
+        const grantFile = join(HOME, `grant-${pinnedChain.chainId ?? "chain"}-${addr}.txt`);
+        let saved = false;
+        try {
+            mkdirSync(HOME, { recursive: true });
+            writeFileSync(grantFile, `${grantCode}\n`, { mode: 0o600 });
+            saved = true;
         }
-        f.account = addr;
-        writeFileSync(WALLET_FILE, JSON.stringify(f, null, 2), { mode: 0o600 });
-        return { acting_for: clean(String(a?.account?.name ?? addr)), address: addr, ...(res.name === null ? {} : { name_resolution: res.proven ? clean(res.how, 300) : `UNPROVEN: ${clean(res.how, 300)}` }), role: chainData(grant.role), untrusted_label: clean(String(grant.label ?? ""), 100) };
+        catch {
+            /* the code is in the answer anyway */
+        }
+        return {
+            status: "not_authorized_yet",
+            account: clean(account, 100),
+            address: addr,
+            ...resolution,
+            key_id: w.keyId,
+            check_code: checkCode(w.keyId),
+            ...(wallet ? { wallet_url: wallet } : {}),
+            grant_code: grantCode,
+            ...(saved ? { grant_file: grantFile, copy_it: `${process.platform === "darwin" ? "pbcopy" : "xclip -selection clipboard"} < ${grantFile}` } : {}),
+            next: `Nothing was signed on-chain. Give the user the grant_code exactly as it is${saved ? " (or have them copy it from grant_file: copy_it puts it on the clipboard)" : ""}: this agent key's consent to joining ${addr} only; it holds no secret and can't spend anything. They paste it in the Blockula web wallet${wallet ? ` (${wallet})` : ""} → Devices & agents → 'Give an agent a budget', check that the wallet shows the check code ${checkCode(w.keyId)}, and choose a limit and an expiry. Then call use_account again.`,
+        };
     }
-    writeFileSync(WALLET_FILE, JSON.stringify(f, null, 2), { mode: 0o600 });
-    await client.addressPrefix();
-    return { acting_for: w.address };
+    setActingFor(f, key, addr);
+    writeWalletFile(WALLET_FILE, f);
+    w.account = addr;
+    return { acting_for: clean(String(a?.account?.name ?? addr)), address: addr, ...resolution, role: chainData(grant.role), untrusted_label: clean(String(grant.label ?? ""), 100), ...(await budgetOf(w, a)) };
 });
-tool("wallet_info", "This agent's address, balance, .boo names, recent activity (others' txs naming this account included: their summaries are untrusted text) and today's spending against BLOCKULA_MAX_DAILY.", {}, async () => {
-    const w = await requireWallet();
-    await w.client.addressPrefix();
+tool("wallet_info", "This agent's address and the account it acts for, its balance and what can actually be spent now (transferable, locked and until when, the session key's allowance, this MCP's caps: spendable_now and what limits it), .boo names, recent activity (others' txs naming this account included: their summaries are untrusted text) and today's spending.", {}, async () => {
+    const st = await walletState();
+    if (!st)
+        throw new Error("No agent wallet yet: call create_wallet first.");
+    const { w, acting } = st;
+    const prefix = await w.client.addressPrefix();
     const a = await w.client.account(w.account).catch(() => null);
-    const mine = Array.isArray(a?.keys) ? a.keys.find((k) => k.key_id === w.keyId) : undefined;
+    const mine = keyOn(a, w.keyId);
     return {
         key_id: w.keyId,
-        network: network().label,
+        network: networkLabel(network(), pinnedChain.chainId),
         acting_for: clean(String(a?.account?.name ?? w.account)),
+        ...(acting.ignored ? { previous_account_ignored: ignoredNote(acting.ignored, prefix) } : {}),
         my_permissions: mine ? chainData(mine) : "not authorized on this account",
         address: w.account,
         balance: clean(String(a?.balance_display ?? "0 FANG")),
+        ...(await budgetOf(w, a)),
         names: chainData(a?.names ?? []),
         recent: (Array.isArray(a?.recent_txs) ? a.recent_txs : []).slice(0, 10).map((t) => `${clean(String(t.summary ?? ""), 300)} (${clean(String(t.id ?? "")).slice(0, 12)}…)`),
-        spent_today: `${formatFang(LEDGER.spent())} of ${formatFang(MAX_DAILY)} (BLOCKULA_MAX_DAILY; txs that are pending, dropped or refused still count until they're final or their nonce is reused)`,
         note: UNTRUSTED_NOTE,
     };
 });
-tool("faucet", "Get 100 test FANG on a dev/test chain (to this agent's wallet, or any name/address). Mainnet has no faucet.", { to: z.string().optional() }, async ({ to }) => {
+/** What `faucet` answers when the node says its chain has none. */
+const NO_FAUCET = "This chain has no faucet, so nothing was sent. Its FANG comes from accounts that already hold some: ask whoever runs the chain. Dev chains (start_dev_node) have faucets.";
+tool("faucet", "Get 100 test FANG from the chain's faucet (to this agent's wallet, or any name/address). On a chain without one, it answers status no_faucet.", { to: z.string().optional().describe("a name or address; default: the account this agent acts for") }, async ({ to }) => {
     const client = await chain();
     let target = to;
     if (!target) {
@@ -811,57 +1079,118 @@ tool("faucet", "Get 100 test FANG on a dev/test chain (to this agent's wallet, o
         await w.client.addressPrefix();
         target = w.account;
     }
-    const tx = await client.faucet(target);
-    return { summary: clean(String(tx.summary ?? "")), tx_id: tx.id, explorer: explorer(`tx/${tx.id}`) };
+    try {
+        const tx = await client.faucet(target);
+        return { summary: clean(String(tx.summary ?? "")), tx_id: tx.id, explorer: explorer(`tx/${tx.id}`) };
+    }
+    catch (e) {
+        // The node's answer on a chain whose genesis has no faucet (node/src/api.rs `faucet`).
+        if (e instanceof ApiError && e.status === 400 && /no faucet/i.test(e.message))
+            return { status: "no_faucet", summary: NO_FAUCET };
+        throw e;
+    }
 });
-tool("send", "Send FANG to a .boo name or address. Amounts are in FANG, e.g. \"1.5\". A name is signed as the name (the chain pays whoever owns it when the tx runs) unless BLOCKULA_WITNESSES proved its owner. Counts toward BLOCKULA_MAX_SEND / BLOCKULA_MAX_DAILY (with the fee, and what opening a new account burns). If it comes back \"pending\", it was submitted: check tx_status, never send it again.", { to: z.string(), amount: z.string(), memo: z.string().max(256).optional() }, async ({ to, amount, memo }) => {
-    const drops = parseFang(amount);
+tool("send", "Send FANG to a .boo name or address. Amounts are in FANG, e.g. \"1.5\". A name is signed as the name (the chain pays whoever owns it when the tx runs) unless BLOCKULA_WITNESSES proved its owner. Paying an address that has no account yet also burns the account creation fee (0.1 FANG on today's chains) to open it: the result reports account_opening_fee_burned and total_cost (amount, fee and burn). Counts toward BLOCKULA_MAX_SEND / BLOCKULA_MAX_DAILY (with the fee and that burn). What the chain would refuse (a session key's limit, FANG that's locked) is refused before signing. If it comes back \"pending\", it was submitted: check tx_status, never send it again.", {
+    to: z.string().describe("a .boo name or an address of this network"),
+    amount: z.string().describe("FANG, e.g. \"1.5\" (up to 9 decimals)"),
+    memo: z.string().max(256).optional().describe("public and permanent: anyone can read it, forever. Never put personal data in it"),
+}, async ({ to, amount, memo }) => {
+    const drops = amountArg(amount);
     if (drops <= 0n)
         throw new Error("send more than 0");
     const w = await requireWallet();
-    await w.client.addressPrefix();
+    otherNetwork(to, await w.client.addressPrefix());
     // With witnesses a name's proven owner is signed; without, the name itself, which the chain
     // resolves when the tx runs: a lying node can't point it at another account now, though one
     // holding the signed tx could release it later in its validity window (audit gap-7-1,
     // review-r3-clients-2).
     const rc = await w.client.recipient(to);
+    if (rc.address === w.account)
+        throw new Error(`${clean(to, 100)} is the account this agent acts for (${w.account}): a payment to itself only pays a fee. Nothing was signed.`);
     const opening = await openingFee(w.client, rc.address);
-    const r = await submitCapped(w, { type: "transfer", to: rc.signed, amount: drops.toString() }, { amount: drops, extra: opening }, memo ?? "");
-    return isInFlight(r) ? { ...r, ...recipientView(rc, "recipient") } : txResult(r, recipientView(rc, "recipient"));
+    const r = await submitCapped(w, { type: "transfer", to: rc.signed, amount: drops.toString() }, { amount: drops, extra: opening, outflow: drops }, memo ?? "");
+    const view = { ...recipientView(rc, "recipient"), ...costView(r, drops, opening) };
+    return isInFlight(r) ? { ...r, ...view } : txResult(r, view);
 });
 tool("check_name", "Check whether a .boo name is available and what it costs, or who owns it and when it expires.", { name: z.string() }, async ({ name }) => chainData(await (await chain()).name(name)));
-tool("register_name", "Claim a .boo name for the account this agent acts for (3–32 chars, a-z 0-9 -). Shorter names cost more (the price is burned); names are registered for a year at a time. The price counts toward BLOCKULA_MAX_SEND / BLOCKULA_MAX_DAILY. Session keys can't register names.", { name: z.string() }, async ({ name }) => {
+tool("register_name", "Claim a .boo name for the account this agent acts for (3–32 chars, a-z 0-9 -). Shorter names cost more; the price is paid to the treasury. Names are registered for a year at a time, are public, and go to whoever asks first. The price counts toward BLOCKULA_MAX_SEND / BLOCKULA_MAX_DAILY. Session keys can't register names (refused before signing).", { name: z.string().describe("e.g. \"vlad\" or \"vlad.boo\"") }, async ({ name }) => {
     const w = await requireWallet();
     const n = bareName(name);
     const { price } = await namePrices(w.client, n);
-    return txResult(await submitCapped(w, { type: "register_name", name: n }, { amount: price, what: "the name's price" }), { price: formatFang(price) });
+    return txResult(await submitCapped(w, { type: "register_name", name: n }, { amount: price, outflow: price, what: "the name's price" }), { price: formatFang(price), paid_to: "the treasury" });
 });
-tool("renew_name", "Extend a .boo name the account this agent acts for owns, by 1–10 years (paid at the chain's renewal price per year, which is burned; counts toward BLOCKULA_MAX_SEND / BLOCKULA_MAX_DAILY). Names that aren't renewed expire after a grace period and anyone can register them.", { name: z.string(), years: z.number().int().min(1).max(10).default(1) }, async ({ name, years }) => {
+tool("renew_name", "Extend a .boo name the account this agent acts for owns, by 1–10 years (at the chain's renewal price per year, paid to the treasury; counts toward BLOCKULA_MAX_SEND / BLOCKULA_MAX_DAILY). Names that aren't renewed expire after a grace period and anyone can register them. Session keys can't renew names.", { name: z.string().describe("e.g. \"vlad.boo\""), years: z.number().int().min(1).max(10).default(1) }, async ({ name, years }) => {
     const w = await requireWallet();
     const n = bareName(name);
     const { renewal, info } = await namePrices(w.client, n);
     const cost = renewal * BigInt(years);
-    return txResult(await submitCapped(w, { type: "renew_name", name: n, years }, { amount: cost, what: "the renewal" }), { cost: formatFang(cost), ...(typeof info?.expires_at === "number" ? { expired_at_before: info.expires_at } : {}) });
+    return txResult(await submitCapped(w, { type: "renew_name", name: n, years }, { amount: cost, outflow: cost, what: "the renewal" }), { cost: formatFang(cost), paid_to: "the treasury", ...(typeof info?.expires_at === "number" ? { expired_at_before: info.expires_at } : {}) });
 });
-const LOOKUP_TYPES = new Set(["block", "tx", "account", "name"]);
-tool("lookup", `Look up anything — a .boo name, address, block number/hash or tx id — and get a plain-English explanation. ${UNTRUSTED_NOTE}`, { query: z.string() }, async ({ query }) => {
+const LOOKUP_TYPES = new Set(["block", "tx", "account", "name", "program", "code"]);
+tool("lookup", `Look up anything — a .boo name, address, block number/hash, tx id, program address or stored code hash — and get a plain-English explanation. ${UNTRUSTED_NOTE}`, { query: z.string() }, async ({ query }) => {
     const client = await chain();
     const hit = await client.search(query);
     const type = String(hit?.type ?? "");
     const id = String(hit?.id ?? "");
     if (!LOOKUP_TYPES.has(type))
         throw new Error(`nothing found for ${clean(query, 100)}`);
+    // A program or a stored code is read by the SDK, which checks it, and shown through untrusted.ts (never the node's JSON as is).
+    if (type === "program" || type === "code") {
+        const data = type === "program" ? await programShown(client, id) : codeView(await client.code(id));
+        return { type, ...(type === "program" ? { explorer: explorer(`program/${encodeURIComponent(id)}`) } : {}), data, note: PROGRAM_NOTE };
+    }
     const data = type === "block" ? await client.block(id) : type === "tx" ? await client.tx(id) : type === "account" ? await client.account(id) : await client.name(id);
     // The node's JSON is nested (it can't override `type` or `explorer`), cleaned and labeled.
     return { type, explorer: explorer(`${type}/${encodeURIComponent(id)}`), data: chainData(data), note: UNTRUSTED_NOTE };
 });
+// ---- programs (docs/PROGRAMS-V0.md §8.5): third-party WebAssembly, read only. No tool here signs a program transaction: an agent's
+// calls need the confirmation flow of PRG 11.5 (the user is asked, an allowlist), a later release. What a program or its deployer
+// chose reaches the agent only as untrusted_* (untrusted.ts), and no description below holds any of it. ----
+/**
+ * A program as `program_show` shows it. With BLOCKULA_WITNESSES its record is proven (its Merkle proof against the witnesses' state
+ * roots), and so is its account's balance: the result is built from what was proven, and the node's own reading must agree with the
+ * proof on every field no transaction changes (`provenDifferences`), else it's refused. What isn't proven (methods and types, the code's
+ * size, the names beside addresses) is the node's word, and the result says so. Without witnesses it's all one node's word, checked
+ * for consistency by the SDK (its version digest is the one its own code, interface and version compute), and says so.
+ */
+async function programShown(client, address) {
+    const info = await client.program(address);
+    if (!client.witnesses.length)
+        return programView(info);
+    const witnesses = client.witnesses;
+    const record = await client.provenProgram(address, { witnesses });
+    if (!record)
+        throw new Error(`${address} isn't a program: its record is provably absent against ${witnesses.length} witness(es), whatever ${RPC} says`);
+    const odd = provenDifferences(info, record);
+    if (odd.length)
+        throw new Error(`${RPC} and its witnesses disagree about the program at ${address}: ${odd.join("; ")}. Nothing it said was used`);
+    // The balance, proven at its own block (a program holds an account from its create on; none proves 0).
+    const account = await client.provenRecord(NAMESPACES.ACCOUNTS, address, { witnesses });
+    return programView(info, { record, balance: { drops: (account.value === null ? 0n : decodeAccount(account.value).balance).toString(), height: account.height }, witnesses: witnesses.length });
+}
+tool("program_show", "A program on this chain by its address (never a .boo name): its record (who created it and when, its code and interface hashes, its version), who could upgrade it, what it holds and stores, its methods (kinds and types as the chain enforces them; the names are the deployer's) and the version digest a call binds. Read only: this MCP signs no program transaction. Every program-chosen name is an untrusted_* field. " + PROGRAM_NOTE, { address: z.string().describe("the program's address (boo1… or tboo1…)") }, async ({ address }) => {
+    const client = await chain();
+    return { ...(await programShown(client, address)), explorer: explorer(`program/${encodeURIComponent(address)}`) };
+});
+tool("program_view", "Run a program's read-only (`view`) method on the node, as of its newest block: nothing is signed, sent or paid. Returns what the method returned as the program's own claim (untrusted_return_data, hex), or how it failed (numbers, never engine text). A method that changes state is a transaction, which this MCP doesn't sign. Some nodes serve no views (403) and each client may run 60 a minute (429). " + PROGRAM_NOTE, {
+    address: z.string().describe("the program's address (boo1… or tboo1…)"),
+    method: z.string().regex(/^[a-z][a-z0-9_]{0,31}$/).describe("a `view` method of its interface (see program_show)"),
+    input: z.string().regex(/^([0-9a-f]{2})*$/).max(65536).default("").describe("what the method reads, lowercase hex of whole bytes (default none)"),
+    bindings: z.array(z.object({ program: z.string(), version_digest: z.string().regex(/^[0-9a-f]{64}$/).optional() })).max(16).default([]).describe("other programs the view may reach, by address and the version digest they must be at (none: any version, which a read may take)"),
+    fuel: z.number().int().min(1).optional().describe("the most fuel the view may use (the node caps it too)"),
+}, async ({ address, method, input, bindings, fuel }) => {
+    const client = await chain();
+    const v = await client.view(address, method, input, { bindings: bindings.map((b) => ({ program: b.program, versionDigest: b.version_digest })), fuel });
+    return viewView(address, method, v, RPC);
+});
+tool("program_code", "A stored program code by its hash (a program's `code.wasm_hash`): its size, the methods its exported functions carry (untrusted_exports: the deployer's names), who uploaded it and for what deposit, how many programs use it and from which block it's usable. Read only. The code's bytes aren't returned. " + PROGRAM_NOTE, { hash: z.string().regex(/^[0-9a-f]{64}$/).describe("64 lowercase hex characters") }, async ({ hash }) => codeView(await (await chain()).code(hash)));
 tool("latest_blocks", "The most recent blocks, summarized.", { limit: z.number().int().min(1).max(50).default(10) }, async ({ limit }) => {
     const blocks = await (await chain()).blocks(limit);
     return (Array.isArray(blocks) ? blocks : []).map((b) => `${clean(String(b.summary ?? ""), 200)} · ${clean(String(b.hash ?? "")).slice(0, 12)}…`);
 });
 // ---- staking ----
-tool("stake", "Stake (delegate) FANG from the account this agent acts for in a validator's pool. Staked FANG earns a share of issuance, is slashed if the validator misbehaves, and takes the unbonding period (21 days on mainnet) to come back after unstake. Session keys can't stake. Counts toward BLOCKULA_MAX_SEND / BLOCKULA_MAX_DAILY.", { validator: z.string().describe("validator address (or a .boo name its account holds)"), amount: z.string().describe("FANG, e.g. \"10\"") }, async ({ validator, amount }) => {
-    const drops = parseFang(amount);
+tool("stake", "Stake (delegate) FANG from the account this agent acts for in a validator's pool. Staked FANG earns a share of issuance, is slashed if the validator misbehaves, and takes the chain's unbonding period (21 days by default) to come back after unstake. Session keys can't stake. Counts toward BLOCKULA_MAX_SEND / BLOCKULA_MAX_DAILY.", { validator: z.string().describe("validator address (or a .boo name its account holds)"), amount: z.string().describe("FANG, e.g. \"10\"") }, async ({ validator, amount }) => {
+    const drops = amountArg(amount);
     if (drops <= 0n)
         throw new Error("delegate more than 0");
     const w = await requireWallet();
@@ -872,7 +1201,7 @@ tool("stake", "Stake (delegate) FANG from the account this agent acts for in a v
     return isInFlight(r) ? { ...r, ...resolvedView(res, "validator") } : txResult(r, { ...resolvedView(res, "validator"), next: "my_stake shows the stake and its value" });
 });
 tool("unstake", "Start unbonding stake from a validator's pool: an amount in FANG (signed as that amount: the chain converts it to pool shares at its own price when the tx runs) or \"all\". It stops earning now and can be withdrawn with withdraw_stake once the unbonding period is over.", { validator: z.string(), amount: z.string().default("all").describe("FANG, or \"all\"") }, async ({ validator, amount }) => {
-    const drops = amount === "all" ? null : parseFang(amount);
+    const drops = amount === "all" ? null : amountArg(amount);
     if (drops !== null && drops <= 0n)
         throw new Error("unstake more than 0 FANG, or \"all\"");
     const w = await requireWallet();
@@ -950,8 +1279,8 @@ tool("list_proposals", `On-chain governance proposals (parameter changes, treasu
     const list = (Array.isArray(res.proposals) ? res.proposals : []);
     return { proposals: list.slice(0, limit).map((p) => proposalView(proposalSummary(p, res.params))), note: UNTRUSTED_NOTE };
 });
-tool("vote", "Vote on a governance proposal for the account this agent acts for. Pass the proposal_digest list_proposals returned with what you showed the user: the vote binds exactly that content, and is refused (nothing signed) if the proposal reads differently now. `amount` FANG of its unlocked holdings is locked: conviction 0 locks nothing and counts 0.1×; 1–6 lock for 1, 2, 4, 8, 16 or 32 lock periods (a week each on mainnet) after voting ends and count 1×–6×. Voting again replaces the vote. Session keys can't vote. Ask the user before locking their FANG.", { proposal_id: z.number().int().min(0), proposal_digest: z.string().regex(/^[0-9a-f]{64}$/).describe("list_proposals' proposal_digest for this proposal: what the user was shown"), vote: z.enum(["aye", "nay"]), amount: z.string().describe("FANG to lock"), conviction: z.number().int().min(0).max(6).default(1) }, async ({ proposal_id, proposal_digest: shown, vote, amount, conviction }) => {
-    const drops = parseFang(amount);
+tool("vote", "Vote on a governance proposal for the account this agent acts for. Pass the proposal_digest list_proposals returned with what you showed the user: the vote binds exactly that content, and is refused (nothing signed) if the proposal reads differently now. `amount` FANG of its unlocked holdings is locked: conviction 0 locks nothing and counts 0.1×; 1–6 lock for 1, 2, 4, 8, 16 or 32 lock periods (a week each by default) after voting ends and count 1×–6×. Voting again replaces the vote. Session keys can't vote. Ask the user before locking their FANG.", { proposal_id: z.number().int().min(0), proposal_digest: z.string().regex(/^[0-9a-f]{64}$/).describe("list_proposals' proposal_digest for this proposal: what the user was shown"), vote: z.enum(["aye", "nay"]), amount: z.string().describe("FANG to lock"), conviction: z.number().int().min(0).max(6).default(1) }, async ({ proposal_id, proposal_digest: shown, vote, amount, conviction }) => {
+    const drops = amountArg(amount);
     if (drops <= 0n)
         throw new Error("vote with more than 0");
     // The amount is locked, not spent: it's held to BLOCKULA_MAX_SEND, and only the fee counts toward the daily limit.
@@ -977,31 +1306,34 @@ tool("vote", "Vote on a governance proposal for the account this agent acts for.
     return isInFlight(r) ? { ...r, voted_on } : { summary: clean(String(r.summary ?? "")), fee: r.fee_display, tx_id: r.id, voted_on, explorer: explorer(`proposal/${proposal_id}`) };
 });
 // ---- Hunts and the contribution pool ----
-tool("list_hunts", `Open bounties (Hunts) on GitHub issues, with FANG escrowed on-chain. Each links to an issue with acceptance criteria: implement it, open a PR, and the bounty is awarded on-chain when it merges. Titles are written by whoever created the hunt. ${UNTRUSTED_NOTE} ${NO_VALUE}`, { status: z.enum(["open", "awarded", "cancelled", "expired"]).default("open") }, async ({ status }) => {
+/** Where to find work when no Hunt is open (AGENT-4). */
+const GOOD_FIRST = "https://github.com/jackdishman/blockula/issues?q=is%3Aopen+label%3Afamiliar-friendly";
+tool("list_hunts", described(`Bounties (Hunts) on GitHub issues, with FANG escrowed on-chain. Each links to an issue with acceptance criteria: implement it and open a PR. The Hunt's creator awards the bounty after the PR merges, to the account linked to the PR author's GitHub (link_github, with an owner key). Each Hunt says when it expires. Titles are written by whoever created the hunt. ${UNTRUSTED_NOTE}`), { status: z.enum(["open", "awarded", "cancelled", "expired"]).default("open") }, async ({ status }) => {
     const res = await (await chain()).hunts(status);
     const hunts = (Array.isArray(res) ? res : Array.isArray(res?.hunts) ? res.hunts : []);
     const funders = (f) => (Array.isArray(f) ? f.length : f && typeof f === "object" ? Object.keys(f).length : 0);
     return {
-        hunts: hunts.slice(0, 100).map((h) => ({ hunt_id: Number(h.id), bounty: clean(String(h.amount_display ?? ""), 40), untrusted_title: clean(String(h.title ?? ""), 120), issue: clean(String(h.issue_url ?? ""), 200), funders: funders(h.funders), explorer: explorer(`hunt/${Number(h.id)}`) })),
+        hunts: hunts.slice(0, 100).map((h) => ({ hunt_id: Number(h.id), bounty: clean(String(h.amount_display ?? ""), 40), untrusted_title: clean(String(h.title ?? ""), 120), issue: clean(String(h.issue_url ?? ""), 200), funders: funders(h.funders), ...(safeInt(h.expires_at) !== undefined ? { expires_at_block: safeInt(h.expires_at) } : {}), explorer: explorer(`hunt/${Number(h.id)}`) })),
+        ...(hunts.length === 0 ? { next: `No ${status} Hunts right now. Merged PRs to the contribution pool's repos can earn from the pool without a Hunt: contribution_pool lists them. Issues labeled familiar-friendly are a good start: ${GOOD_FIRST}` } : {}),
         note: `${UNTRUSTED_NOTE} ${NO_VALUE}`,
     };
 });
-tool("link_github", "Link a GitHub handle to the account this agent acts for, so Hunt awards show up on its profile. First create a PUBLIC gist (as that GitHub user) containing the account's address, then pass the gist id here.", { handle: z.string().regex(/^[A-Za-z0-9-]{1,39}$/), gist_id: z.string().regex(/^[0-9a-f]{20,40}$/) }, async ({ handle, gist_id }) => {
+tool("link_github", "Link a GitHub handle to the account this agent acts for, so Hunt awards and pool claims credit it. It needs an owner key: when this agent acts through a session key, ask the user to link GitHub in their wallet instead. First create a PUBLIC gist (as that GitHub user) containing the account's address, then pass the gist id here.", { handle: z.string().regex(/^[A-Za-z0-9-]{1,39}$/).describe("the GitHub username"), gist_id: z.string().regex(/^[0-9a-f]{20,40}$/).describe("the public gist's id (from its URL)") }, async ({ handle, gist_id }) => {
     const w = await requireWallet();
     const r = await submitCapped(w, { type: "link_github", handle, gist_id }, { amount: 0n });
     if (isInFlight(r))
         return r;
     const check = await w.client.github(handle).catch(() => null);
-    return { summary: clean(String(r.summary ?? "")), verified: check?.verified === true, explorer: explorer(`tx/${r.id}`) };
+    return { summary: clean(String(r.summary ?? "")), tx_id: r.id, verified: check?.verified === true, ...(check?.verified === true ? {} : { next: `The link is on chain, but this node can't verify the gist yet${check?.reason ? ` (${clean(String(check.reason), 200)})` : ""}. Validators check it for every contribution claim, so fix it before submit_contribution.` }), explorer: explorer(`tx/${r.id}`) };
 });
-tool("fund_hunt", `Add FANG to an open Hunt's bounty (crowdfunding). Refunded to you if the hunt is cancelled. ${NO_VALUE}`, { hunt_id: z.number().int().min(0), amount: z.string() }, async ({ hunt_id, amount }) => {
-    const drops = parseFang(amount);
+tool("fund_hunt", described(`Add FANG to an open Hunt's bounty (crowdfunding). Refunded to you if the hunt is cancelled.`), { hunt_id: z.number().int().min(0), amount: z.string() }, async ({ hunt_id, amount }) => {
+    const drops = amountArg(amount);
     if (drops <= 0n)
         throw new Error("fund more than 0");
-    const r = await submitCapped(await requireWallet(), { type: "fund_hunt", hunt_id, amount: drops.toString() }, { amount: drops });
+    const r = await submitCapped(await requireWallet(), { type: "fund_hunt", hunt_id, amount: drops.toString() }, { amount: drops, outflow: drops });
     return isInFlight(r) ? r : { summary: clean(String(r.summary ?? "")), fee: r.fee_display, tx_id: r.id, explorer: explorer(`hunt/${hunt_id}`) };
 });
-tool("contribution_pool", `Blockula's contribution pool (Proof of Contribution): its balance, which GitHub repos earn from it, the rules, and the Séance (review jury) that's open now. Merged PRs to pool repos can be claimed for a share; payouts are judged by human juries, rate a sponsor's claims in a Séance together (one pooled win rate; each next a quarter of the one before), and vest over ~90 days. ${NO_VALUE}`, {}, async () => {
+tool("contribution_pool", described(`Blockula's contribution pool (Proof of Contribution): its balance, which GitHub repos earn from it, the rules, and the Séance (review jury) that's open now. Merged PRs to pool repos can be claimed for a share; payouts are judged by human juries, rate a sponsor's claims in a Séance together (one pooled win rate; each next a quarter of the one before), and vest over ~90 days.`), {}, async () => {
     const c = await (await chain()).contributions();
     return {
         pool: chainData(c.pool?.balance_display),
@@ -1015,21 +1347,30 @@ tool("contribution_pool", `Blockula's contribution pool (Proof of Contribution):
         explorer: explorer("contribute"),
     };
 });
-tool("submit_contribution", `Claim a merged PR for the contribution pool, for the account this agent acts for. The PR's author must be that account's linked GitHub handle. Costs a small refundable bond (lost if the jury marks it spam). If you act for a user through a session key, they must first register that key as a Familiar (wallet.registerFamiliar), or the chain refuses the claim; the claim then credits you as their Familiar. ${NO_VALUE}`, { repo: z.string().regex(/^[A-Za-z0-9-]{1,39}\/[A-Za-z0-9._-]{1,100}$/), pr: z.number().int().min(1) }, async ({ repo, pr }) => {
+tool("submit_contribution", described(`Claim a merged PR for the contribution pool, for the account this agent acts for. The PR's author must be that account's linked GitHub handle, verified by its gist (checked first: refused when it isn't, unless force is true). Costs a bond (1 FANG, more with open claims): it's returned unless validators refute the claim (an unmerged PR, another author, a gist that doesn't verify) or the jury marks it spam. If you act for a user through a session key, they must first register that key as a Familiar in their wallet, or the claim is refused; the claim then credits them as your sponsor.`), { repo: z.string().regex(/^[A-Za-z0-9-]{1,39}\/[A-Za-z0-9._-]{1,100}$/).describe("owner/name"), pr: z.number().int().min(1), force: z.boolean().default(false).describe("claim even though the GitHub link doesn't verify now (the bond is likely lost)") }, async ({ repo, pr, force }) => {
     const w = await requireWallet();
     await w.client.addressPrefix();
     const me = await w.client.account(w.account).catch(() => null);
+    // CONTRIB-4: validators refute a claim whose author's link doesn't verify, and the bond goes to the pool.
+    if (!force) {
+        const handle = typeof me?.github?.handle === "string" ? me.github.handle : undefined;
+        if (!handle)
+            throw new Error(`${w.account} has no GitHub link, so validators would refute the claim and keep the bond. Link the PR author's GitHub first (link_github, or in the user's wallet). Nothing was signed.`);
+        const check = await w.client.github(handle).catch(() => null);
+        if (check?.verified !== true)
+            throw new Error(`@${clean(handle, 40)}'s link to ${w.account} doesn't verify${check?.reason ? ` (${clean(String(check.reason), 200)})` : ""}, so validators would likely refute the claim and keep the bond. Fix the gist, or pass force: true to claim anyway. Nothing was signed.`);
+    }
     // node/src/poc.rs `claim_bond`: CLAIM_BOND (1 FANG) per claim, more with open claims; never counted below it.
     const quoted = me?.contribution?.next_claim_bond;
     const bond = /^\d+$/.test(String(quoted ?? "")) && BigInt(quoted) > 1000000000n ? BigInt(quoted) : 1000000000n;
-    const r = await submitCapped(w, { type: "submit_claim", repo, pr }, { amount: bond, what: `the claim bond (${formatFang(bond)})` });
+    const r = await submitCapped(w, { type: "submit_claim", repo, pr }, { amount: bond, outflow: bond, what: `the claim bond (${formatFang(bond)})` });
     if (isInFlight(r))
         return r;
     const claims = await w.client.claims({ account: w.account }).catch(() => null);
     const claim = (Array.isArray(claims?.claims) ? claims.claims : []).find((c) => c.repo === repo.toLowerCase() && c.pr === pr);
-    return { summary: clean(String(r.summary ?? "")), claim_id: claim?.id, status: claim ? clean(String(claim.status)) : undefined, next: "Validators check GitHub within a minute or two; then it waits for the revert window and the next Séance. Track it with my_contributions.", note: NO_VALUE, explorer: explorer(`claim/${claim?.id ?? ""}`) };
+    return { summary: clean(String(r.summary ?? "")), tx_id: r.id, claim_id: claim?.id, status: claim ? clean(String(claim.status)) : undefined, next: "Validators check GitHub within a minute or two; then it waits for the revert window and the next Séance. Track it with my_contributions.", note: NO_VALUE, explorer: explorer(`claim/${claim?.id ?? ""}`) };
 });
-tool("my_contributions", `The Soul (reputation), contribution claims, vesting rewards, vouch and jury status of the account this agent acts for. A claim's untrusted_note is written by whoever judged or rejected it. ${NO_VALUE}`, {}, async () => {
+tool("my_contributions", described(`The Soul (reputation), contribution claims, vesting rewards, vouch and jury status of the account this agent acts for. A claim's untrusted_note is written by whoever judged or rejected it.`), {}, async () => {
     const w = await requireWallet();
     await w.client.addressPrefix();
     const a = await w.client.account(w.account);
@@ -1045,6 +1386,6 @@ tool("my_contributions", `The Soul (reputation), contribution claims, vesting re
         note: `${UNTRUSTED_NOTE} ${NO_VALUE}`,
     };
 });
-if (NET_ERROR)
-    console.error(`blockula-mcp: ${NET_ERROR.message}`);
+if (BAD_CONFIG)
+    console.error(`blockula-mcp: ${BAD_CONFIG.message} (every tool answers with this until the configuration is fixed)`);
 await server.connect(new StdioServerTransport());