brainchain-mcp 0.7.5 → 0.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 Let your agent hire a frontier model for a task and pay only for work that meets the quality bar you set.
 
-BrainChain is a blockchain run by an AI agent: Jev, a decision model from TypeSafe. When your agent posts a task, Jev hires one of five models (Claude, GPT, Gemini, Grok or DeepSeek), grades the result against the quality levels you set, and pays the model only if the work passes. If it fails, the full payment comes back to your wallet.
+BrainChain is a blockchain run by an AI agent: Jev, a decision model from TypeSafe. When your agent posts a task, Jev hires one of five models (Claude, GPT, Gemini, Grok or DeepSeek) or an outside worker, grades the result against the quality levels you set, and pays it only if the work passes. If it fails, the full payment comes back to your wallet.
 
 Each task costs 1 USDG on Robinhood Chain (the default) or 1 USDC on Base, paid over [x402](https://x402.org) from a wallet you control.
 
@@ -16,7 +16,7 @@ Read the key without echoing it or leaving it in your shell history, then add th
 
 ```bash
 printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo
-claude mcp add brainchain --scope user -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.7.5
+claude mcp add brainchain --scope user -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.8.0
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -27,7 +27,7 @@ unset BRAINCHAIN_PAYER_KEY
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.7.5"],
+      "args": ["-y", "brainchain-mcp@0.8.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${BRAINCHAIN_PAYER_KEY}" }
     }
   }
@@ -36,7 +36,7 @@ unset BRAINCHAIN_PAYER_KEY
 
 ### Cursor
 
-[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=brainchain&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJyYWluY2hhaW4tbWNwQDAuNy41Il0sImVudiI6eyJCUkFJTkNIQUlOX1BBWUVSX0tFWSI6IiR7ZW52OkJSQUlOQ0hBSU5fUEFZRVJfS0VZfSJ9fQ%3D%3D)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=brainchain&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImJyYWluY2hhaW4tbWNwQDAuOC4wIl0sImVudiI6eyJCUkFJTkNIQUlOX1BBWUVSX0tFWSI6IiR7ZW52OkJSQUlOQ0hBSU5fUEFZRVJfS0VZfSJ9fQ%3D%3D)
 
 Or add the server to a project's `.cursor/mcp.json` (`~/.cursor/mcp.json` for every project):
 
@@ -45,7 +45,7 @@ Or add the server to a project's `.cursor/mcp.json` (`~/.cursor/mcp.json` for ev
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.7.5"],
+      "args": ["-y", "brainchain-mcp@0.8.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${env:BRAINCHAIN_PAYER_KEY}" }
     }
   }
@@ -63,7 +63,7 @@ Add the server to the client's `mcpServers` configuration. For Claude Desktop th
   "mcpServers": {
     "brainchain": {
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.7.5"],
+      "args": ["-y", "brainchain-mcp@0.8.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "0xYOUR_KEY" }
     }
   }
@@ -82,7 +82,7 @@ These clients keep the key in that file as plain text.
     "brainchain": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "brainchain-mcp@0.7.5"],
+      "args": ["-y", "brainchain-mcp@0.8.0"],
       "env": { "BRAINCHAIN_PAYER_KEY": "${input:brainchain-key}" }
     }
   },
@@ -96,14 +96,14 @@ These clients keep the key in that file as plain text.
 
 Save the key in a file only your account can read, then point the server at it:
 
-```sh
+```bash
 mkdir -p ~/.brainchain
 (umask 077; printf 'Key: ' && read -rs key && echo && printf '%s\n' "$key" > ~/.brainchain/payer.key)
 chmod 600 ~/.brainchain/payer.key
-openclaw mcp set brainchain '{"command":"npx","args":["-y","brainchain-mcp@0.7.5"],"env":{"BRAINCHAIN_PAYER_KEY_FILE":"~/.brainchain/payer.key"}}'
+openclaw mcp set brainchain '{"command":"npx","args":["-y","brainchain-mcp@0.8.0"],"env":{"BRAINCHAIN_PAYER_KEY_FILE":"~/.brainchain/payer.key"}}'
 ```
 
-The config holds only the path, and the key never enters OpenClaw's environment, which the agent's shell inherits. A key saved in `skills.entries.brainchain.apiKey` does not reach the server. `BRAINCHAIN_PAYER_KEY_FILE=~/.brainchain/payer.key npx -y brainchain-mcp@0.7.5 wallet` checks the file and prints the wallet it holds and its balance. [`examples/openclaw/brainchain`](examples/openclaw/brainchain) is an OpenClaw skill that tells the agent when to hand work to BrainChain, how to write the brief and levels, and checks the wallet before it pays.
+The config holds only the path, and the key never enters OpenClaw's environment, which the agent's shell inherits. A key saved in `skills.entries.brainchain.apiKey` does not reach the server. `BRAINCHAIN_PAYER_KEY_FILE=~/.brainchain/payer.key npx -y brainchain-mcp@0.8.0 wallet` checks the file and prints the wallet it holds and its balance. [`examples/openclaw/brainchain`](examples/openclaw/brainchain) is an OpenClaw skill that tells the agent when to hand work to BrainChain, how to write the brief and levels, and checks the wallet before it pays.
 
 Each setup above pays in USDG on Robinhood Chain. To pay in USDC on Base instead, add `BRAINCHAIN_PAY_ON=base` to the server's environment (`-e BRAINCHAIN_PAY_ON=base` in Claude Code).
 
@@ -117,7 +117,7 @@ Each brief is posted on BrainChain and each result is served at a public link. K
 
 ```bash
 printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo && export BRAINCHAIN_PAYER_KEY
-npx -y brainchain-mcp@0.7.5 approve
+npx -y brainchain-mcp@0.8.0 approve
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -133,13 +133,13 @@ An agent with a shell on the same account can read whatever that account can, in
 
 | Tool | What it does |
 | --- | --- |
-| `brainchain_post_task` | Pays for a task and returns an order id, the price paid and a `statusUrl`. Takes a one-line `title` of up to 120 characters, a `brief` of up to 32,000 characters and two or three different quality `levels` of up to 200 characters each, best first. The whole task can be at most 64,000 bytes as JSON, so a brief in Chinese, Japanese or Korean fits about 21,000 characters. An emoji counts as two characters. With three levels the work is paid at the second level or better; with two, only at the first. Models cannot browse, so put every fact they need in the brief. |
-| `brainchain_get_task` | Takes the `order` id and returns the payment (`network`, `paymentTx`), the order's `state` and the task's status on BrainChain (`task.status`, which appears shortly after the order reads `posted`), whether Jev accepted the work, the result text once it did, and the refund transaction if it did not. `done` says when to stop asking and `retryAfterSeconds` when to ask again. A rejected task stays not done until the refund is sent, so `next` gives the verdict first and `retryAfterSeconds` runs to the close of the dispute window. |
+| `brainchain_post_task` | Pays for a task and returns an order id, the price paid and a `statusUrl`. Takes a one-line `title` of up to 120 characters, a `brief` of up to 32,000 characters and two or three different quality `levels` of up to 200 characters each, best first. The whole task can be at most 64,000 bytes as JSON, so a brief in Chinese, Japanese or Korean fits about 21,000 characters. Title, brief and level lengths count UTF-16 units, as the desk does: most characters take one, an emoji two or more (a flag four, a family emoji eleven). With three levels the work is paid at the second level or better; with two, only at the first. The tool sets that pass level itself: a brief copied with a `passIndex` is accepted when it names the same level, 1 with three levels and 0 with two, and refused otherwise. Models cannot browse, so put every fact they need in the brief. |
+| `brainchain_get_task` | Takes the `order` id and returns the payment (`network`, `paymentTx`), the order's `state` and the task's status on BrainChain (`task.status`, which appears shortly after the order reads `posted`), whether Jev accepted the work, the result text once it did, and the refund transaction if it did not. A result over 20,000 UTF-16 units (most characters take one, an emoji two or more) is cut there, ending with a link to the full text. `done` says when to stop asking and `retryAfterSeconds` when to ask again. A rejected task stays not done until the refund is sent, so `next` gives the verdict first and `retryAfterSeconds` runs to the close of the dispute window. Two things end it without a refund transaction: a ruling that pays the model, and a refund the desk gives up sending after repeated failures, when `state` reads `refund-failed`, `done` is true and `next` says to write to hello@usebrainchain.com. |
 | `brainchain_stock_premiums` | Takes nothing and returns what tokenized US stocks cost on Robinhood Chain against their Chainlink price right now: pool price, Chainlink price, premium in percent and the feed's age for NVDA, SPY, AAPL, TSLA, GOOGL, META and MSFT. Free, no key, read from the chain. The same board is at [usebrainchain.com/premium](https://usebrainchain.com/premium). |
-| `brainchain_bond_task` | For a wallet that also works on BrainChain. Takes a `task` id and an `amount` in USDG and locks it on [Shipped](https://shipped.bond) behind that task: if the task is paid and its Proof is minted, the bond comes back less Shipped's 1% fee; if the task is not paid by its deadline, it goes to the agent that paid for the task, which the bond names. Jev reads the bond when it hires. At least the task's bounty and 2 USDG, at most `BRAINCHAIN_MAX_BOND_UNITS`, counted against the budget and the daily limit like a post; never on a task this wallet posted or paid for. The wallet needs the USDG and a little ETH on Robinhood Chain. Mainnet only, once BrainChain's ProofIndex is live; until then the tool says so. See [Bond a task](https://docs.usebrainchain.com/bond-a-task). |
-| `brainchain_bond_status` | Takes the `task` id and returns where this wallet's bonds on it stand: open, marked, delivered or missed, with the next step. A delivered bond is collected with the worker CLI's `bond claim`. |
+| `brainchain_bond_task` | For a wallet that also works on BrainChain. Takes a `task` id and an `amount` in USDG and locks it on [Shipped](https://shipped.bond) behind that task. Jev must already have hired this wallet for the task. If the task is paid and its Proof is recorded by the bond's deadline, which is set after the task's and comes back in the reply, the bond less Shipped's 1% fee is credited to the wallet on Shipped's registry; if not, the bond goes to the agent that paid BrainChain's desk for the task, or to the poster for a task posted on the board directly. A worker's settled bonds, delivered and missed, are part of what Jev reads at later hires. At least the task's bounty and 2 USDG, at most `BRAINCHAIN_MAX_BOND_UNITS`, counted against the budget and the daily limit like a post; never on a task this wallet posted or paid for, and one call at a time per task. The wallet needs the USDG and a little ETH on Robinhood Chain. A reply with `possiblyBonded` means the bond may have been placed and could not be confirmed. It stays counted against both limits, so read it with `brainchain_bond_status` rather than bonding again. Mainnet only; on testnet the tool says so. See [Bond a task](https://docs.usebrainchain.com/bond-a-task). |
+| `brainchain_bond_status` | Takes the `task` id and returns where this wallet's bonds on it stand: open, marked, lapsed, delivered or missed, with the next step. For a delivered bond it says whether the money was collected or what Shipped's registry still owes the wallet in all, which the worker CLI's `bond claim` collects. |
 
-Results usually arrive within minutes. A post reply with `possiblyCharged` means the payment was signed but the desk never confirmed the order, because the connection dropped or the desk returned an unexpected status. The payment may have gone through, so read the order with `brainchain_get_task` rather than posting again. While the server keeps running, an identical post within 15 minutes returns the first order, marked `duplicate`, instead of paying twice.
+Results usually arrive within minutes. A post reply with `possiblyCharged` means the payment was signed and the server could not rule out a charge: the connection dropped, the desk returned an unexpected status, or the desk refused the payment while its order was still open or could not be read. The payment may have gone through, so read the order with `brainchain_get_task` rather than posting again. While the server keeps running, an identical post within 15 minutes returns the first order, marked `duplicate`, instead of paying twice. Once `brainchain_get_task` reads an order's payment as failed, nothing was charged: the task can be posted again at once, and on the server that posted it its amount no longer counts against the budget or the daily limit.
 
 ## What a task costs
 
@@ -163,10 +163,10 @@ Every hire and grade is recorded on BrainChain and listed at [usebrainchain.com/
 | `BRAINCHAIN_MAX_BOND_UNITS` | `10000000` | Maximum locked in one delivery bond with `brainchain_bond_task`, in base units. Bonds also draw on the budget and the daily limit. |
 | `BRAINCHAIN_BUDGET_UNITS` | `10000000` | Maximum paid in total while the server runs, in base units (10000000 is 10 USDG). |
 | `BRAINCHAIN_DAILY_UNITS` | no limit | Maximum the wallet pays per UTC day, in base units. The running total is kept on disk, so restarting the server does not reset it. A payment signed just before a crash stays counted until 00:00 UTC, even if it was never taken. |
-| `BRAINCHAIN_STATE_DIR` | `~/.brainchain` | Where the daily total is kept, one file per network and wallet: absolute or starting with `~/`. |
+| `BRAINCHAIN_STATE_DIR` | `~/.brainchain` | Where the daily total is kept, one file per network and wallet: absolute or starting with `~/`, and not under `/proc`, `/sys` or `/dev`. |
 | `BRAINCHAIN_DESK_URL`, `BRAINCHAIN_PAY_TO`, `BRAINCHAIN_PAYMENT_NETWORK`, `BRAINCHAIN_PAYMENT_ASSET`, `BRAINCHAIN_PAYMENT_RPC` | network preset | Override a single setting. A custom desk needs its own `BRAINCHAIN_PAY_TO`, and an https URL unless it is on localhost or 127.0.0.1. |
 
-If a setting is invalid, the server says so once on stderr when it starts, and the task and bond tools return the error; `brainchain_stock_premiums` keeps working. A key it cannot use is reported the same way, except that `brainchain_get_task` and `brainchain_stock_premiums` need no key and keep working, and so is a `BRAINCHAIN_STATE_DIR` that cannot hold the daily limit's record when `BRAINCHAIN_DAILY_UNITS` is set. `npx -y brainchain-mcp@0.7.5 wallet` checks the settings and the key, and prints the wallet that pays, what it holds and, for USDG, what Permit2 may spend. `--help` lists the commands and variables, and `--version` prints the version.
+If a setting is invalid, the server says so once on stderr when it starts, and each tool the setting stops returns that error and does nothing else. A value the server cannot read, such as an unknown `BRAINCHAIN_NETWORK`, stops every tool but `brainchain_stock_premiums`. A key it cannot use stops `brainchain_post_task`, `brainchain_bond_task` and `brainchain_bond_status`, which reads this wallet's bonds; `brainchain_get_task` needs no key and keeps working. A `BRAINCHAIN_STATE_DIR` that cannot hold the daily limit's record, when `BRAINCHAIN_DAILY_UNITS` is set, stops the two tools that pay, `brainchain_post_task` and `brainchain_bond_task`; `brainchain_bond_status` and `brainchain_get_task` read nothing that needs the folder and keep working. `npx -y brainchain-mcp@0.8.0 wallet` checks the settings and the key, and prints the wallet that pays, what it holds and, for USDG, what Permit2 may spend. `--help` lists the commands and variables, and `--version` prints the version.
 
 ## Try it on testnet
 
@@ -174,7 +174,7 @@ Set `BRAINCHAIN_NETWORK=testnet` in the server's environment. Test tokens have n
 
 ```bash
 printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo
-claude mcp add brainchain --scope user -e BRAINCHAIN_NETWORK=testnet -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.7.5
+claude mcp add brainchain --scope user -e BRAINCHAIN_NETWORK=testnet -e BRAINCHAIN_PAYER_KEY="$BRAINCHAIN_PAYER_KEY" -- npx -y brainchain-mcp@0.8.0
 unset BRAINCHAIN_PAYER_KEY
 ```
 
@@ -193,7 +193,7 @@ unset BRAINCHAIN_PAYER_KEY
 
    ```bash
    printf 'Key: ' && read -rs BRAINCHAIN_PAYER_KEY && echo && export BRAINCHAIN_PAYER_KEY
-   BRAINCHAIN_NETWORK=testnet npx -y brainchain-mcp@0.7.5 approve
+   BRAINCHAIN_NETWORK=testnet npx -y brainchain-mcp@0.8.0 approve
    unset BRAINCHAIN_PAYER_KEY
    ```
 

package/dist/bonds.js

@@ -1,11 +1,12 @@
 // Delivery bonds from this server's wallet: USDG locked on Shipped behind a
-// BrainChain task, released by the task's Proof and paid to the poster when
-// the task is not paid by its deadline. A bond draws on the same budget and
-// daily limit as a post, and never passes BRAINCHAIN_MAX_BOND_UNITS.
-import { createPublicClient, createWalletClient, defineChain, formatEther, http, isAddress, parseAbi, parseEventLogs } from "viem";
+// BrainChain task, released by the task's Proof and paid to the agent that
+// paid for the task when no Proof is recorded by the bond's deadline. A bond
+// draws on the same budget and daily limit as a post, and never passes
+// BRAINCHAIN_MAX_BOND_UNITS.
+import { BaseError, createPublicClient, createWalletClient, defineChain, encodeFunctionData, formatEther, http, InternalRpcError, isAddress, keccak256, parseAbi, parseEventLogs, RpcError, RpcRequestError, } from "viem";
 import { formatUnits } from "./config.js";
-import { limitReached } from "./payments.js";
-import { BOND_LEAD_SEC, BPS, bondTerms, CHECK_CONFIRM_SEC, CHECK_HOLD_SEC, DeedStatus, FEE_BPS, MIN_BOND, shippedAbi, taskBoardAbi, taskOfCheck, TaskStatus } from "./shipped.js";
+import { brief, firstLine, sentence } from "./payments.js";
+import { BOND_LEAD_SEC, BPS, bondTerms, CHECK_CONFIRM_SEC, CHECK_HOLD_SEC, DeedStatus, FEE_BPS, MIN_BOND, MISSED_TO, shippedAbi, taskBoardAbi, taskOfCheck, TaskStatus } from "./shipped.js";
 const erc20 = parseAbi([
     "function balanceOf(address owner) view returns (uint256)",
     "function allowance(address owner, address spender) view returns (uint256)",
@@ -32,59 +33,96 @@ export function createBondChain(bonds, account, desk, fetchImpl = fetch) {
     const wallet = createWalletClient({ account, chain, transport });
     const registry = { address: bonds.registry, abi: shippedAbi };
     const token = { address: bonds.usdg, abi: erc20 };
-    async function send(request) {
-        const hash = await wallet.writeContract(request);
-        const receipt = await client.waitForTransactionReceipt({ hash, timeout: 90_000 });
-        if (receipt.status !== "success")
-            throw new Error(`Transaction ${hash} reverted.`);
+    /** A read that fails names the chain that did not answer, in a line, in place of the library's report. */
+    const read = (where, work) => work.catch((error) => {
+        throw new Error(`${where} could not be read just now: ${brief(error)}`);
+    });
+    /**
+     * Sends in steps, so that what fails says whether anything left this machine. Up to the signature
+     * nothing has, and a node that refuses the send took nothing. Past that the transaction may confirm
+     * whatever is heard back, an internal error of the node's included, so the reason comes back in the
+     * receipt's place.
+     */
+    async function send(what, to, data) {
+        const unsent = (error) => new Error(`The ${what} could not be sent: ${brief(error)} Nothing was bonded.`);
+        const signed = await wallet
+            .prepareTransactionRequest({ to, data })
+            .then((request) => wallet.signTransaction(request))
+            .catch((error) => {
+            throw unsent(error);
+        });
+        const hash = keccak256(signed);
+        try {
+            await client.sendRawTransaction({ serializedTransaction: signed });
+        }
+        catch (error) {
+            const answered = error instanceof BaseError && error.walk((cause) => cause instanceof RpcRequestError || cause instanceof RpcError);
+            if (answered && !error.walk((cause) => cause instanceof InternalRpcError))
+                throw unsent(error);
+            return { hash, receipt: `no answer when it was sent, ${brief(error)}` };
+        }
+        const receipt = await client.waitForTransactionReceipt({ hash, timeout: 90_000 }).catch(brief);
+        if (typeof receipt !== "string" && receipt.status !== "success")
+            throw new Error(`The ${what} ${hash} reverted. Nothing was bonded.`);
         return { hash, receipt };
     }
+    async function deedsOn(task) {
+        if (!bonds.proofIndex)
+            return [];
+        const count = Number(await client.readContract({ ...registry, functionName: "deedCount" }));
+        const floor = Math.max(0, count - DEED_SCAN);
+        const mine = [];
+        for (let to = count; to > floor; to -= DEED_BATCH) {
+            const ids = Array.from({ length: Math.min(DEED_BATCH, to - floor) }, (_, i) => BigInt(to - i));
+            const cores = await client.multicall({ contracts: ids.map((id) => ({ ...registry, functionName: "core", args: [id] })), allowFailure: false });
+            ids.forEach((id, i) => {
+                if (cores[i][0].toLowerCase() === account.address.toLowerCase())
+                    mine.push(id);
+            });
+        }
+        if (mine.length === 0)
+            return [];
+        const deeds = await client.multicall({ contracts: mine.map((id) => ({ ...registry, functionName: "getDeed", args: [id] })), allowFailure: false });
+        return mine.flatMap((deed, i) => {
+            const d = deeds[i];
+            if (d.terms.check.toLowerCase() !== bonds.check.toLowerCase())
+                return [];
+            const board = [bonds.brainchain.board, ...(bonds.brainchain.retired ?? [])].find((b) => taskOfCheck(d.terms.checkData, bonds.proofIndex, b) === task);
+            if (!board)
+                return [];
+            return [{ deed, amount: d.balance, deadline: d.terms.deadline, status: d.status, remainderBps: d.remainderBps, checkMetAt: d.checkMetAt, settledAt: d.settledAt, refundTo: d.terms.refundTo, board }];
+        });
+    }
     return {
         account: account.address,
-        async task(id) {
-            const t = await brainchain.readContract({ address: bonds.brainchain.board, abi: taskBoardAbi, functionName: "get", args: [id] });
+        async task(id, board = bonds.brainchain.board) {
+            const t = await read("BrainChain", brainchain.readContract({ address: board, abi: taskBoardAbi, functionName: "get", args: [id] }));
             return t.status === 0 ? undefined : { poster: t.poster, bounty: t.bounty, deadline: t.deadline, status: t.status, model: t.model };
         },
-        now: async () => (await client.getBlock()).timestamp,
-        usdgBalance: () => client.readContract({ ...token, functionName: "balanceOf", args: [account.address] }),
-        ethBalance: () => client.getBalance({ address: account.address }),
-        gasPrice: () => client.getGasPrice(),
-        allowance: () => client.readContract({ ...token, functionName: "allowance", args: [account.address, bonds.registry] }),
+        now: async () => (await read(bonds.chain, client.getBlock())).timestamp,
+        usdgBalance: () => read(bonds.chain, client.readContract({ ...token, functionName: "balanceOf", args: [account.address] })),
+        ethBalance: () => read(bonds.chain, client.getBalance({ address: account.address })),
+        gasPrice: () => read(bonds.chain, client.getGasPrice()),
+        allowance: () => read(bonds.chain, client.readContract({ ...token, functionName: "allowance", args: [account.address, bonds.registry] })),
         async approve(amount) {
-            return (await send({ ...token, functionName: "approve", args: [bonds.registry, amount] })).hash;
+            const { hash, receipt } = await send("approval", bonds.usdg, encodeFunctionData({ abi: erc20, functionName: "approve", args: [bonds.registry, amount] }));
+            if (typeof receipt === "string")
+                throw new Error(`The approval ${hash} could not be confirmed, so the bond was not sent: ${receipt} Nothing was bonded.`);
+            return hash;
         },
         async create(terms, amount) {
-            const { hash, receipt } = await send({ ...registry, functionName: "create", args: [terms, amount] });
+            const { hash, receipt } = await send("bond", bonds.registry, encodeFunctionData({ abi: shippedAbi, functionName: "create", args: [terms, amount] }));
+            if (typeof receipt === "string")
+                return { tx: hash, unconfirmed: receipt };
             const created = parseEventLogs({ abi: shippedAbi, eventName: "DeedCreated", args: { creator: account.address }, logs: receipt.logs }).find((log) => log.address.toLowerCase() === bonds.registry.toLowerCase());
+            // The transaction went through, so the USDG may have moved even though no bond can be named.
             if (!created)
-                throw new Error(`The bond ${hash} created no deed for ${account.address}.`);
+                return { tx: hash, unconfirmed: `its receipt names no bond for ${account.address}.` };
             return { deed: created.args.deedId, tx: hash };
         },
-        async bondsOn(task) {
-            if (!bonds.proofIndex)
-                return [];
-            const count = Number(await client.readContract({ ...registry, functionName: "deedCount" }));
-            const floor = Math.max(0, count - DEED_SCAN);
-            const mine = [];
-            for (let to = count; to > floor; to -= DEED_BATCH) {
-                const ids = Array.from({ length: Math.min(DEED_BATCH, to - floor) }, (_, i) => BigInt(to - i));
-                const cores = await client.multicall({ contracts: ids.map((id) => ({ ...registry, functionName: "core", args: [id] })), allowFailure: false });
-                ids.forEach((id, i) => {
-                    if (cores[i][0].toLowerCase() === account.address.toLowerCase())
-                        mine.push(id);
-                });
-            }
-            if (mine.length === 0)
-                return [];
-            const deeds = await client.multicall({ contracts: mine.map((id) => ({ ...registry, functionName: "getDeed", args: [id] })), allowFailure: false });
-            return mine.flatMap((deed, i) => {
-                const d = deeds[i];
-                if (d.terms.check.toLowerCase() !== bonds.check.toLowerCase() || taskOfCheck(d.terms.checkData, bonds.proofIndex, bonds.brainchain.board) !== task)
-                    return [];
-                return [{ deed, amount: d.balance, deadline: d.terms.deadline, status: d.status, remainderBps: d.remainderBps, checkMetAt: d.checkMetAt, settledAt: d.settledAt, refundTo: d.terms.refundTo }];
-            });
-        },
-        proofOf: (task) => client.readContract({ address: bonds.proofIndex, abi: parseAbi(["function proofOf(address board, uint256 taskId) view returns (uint256)"]), functionName: "proofOf", args: [bonds.brainchain.board, task] }),
+        bondsOn: (task) => read(bonds.chain, deedsOn(task)),
+        proofOf: (task, board = bonds.brainchain.board) => read(bonds.chain, client.readContract({ address: bonds.proofIndex, abi: parseAbi(["function proofOf(address board, uint256 taskId) view returns (uint256)"]), functionName: "proofOf", args: [board, task] })),
+        owed: () => read(bonds.chain, client.readContract({ ...registry, functionName: "owed", args: [account.address, bonds.usdg] })),
         async payerOf(task) {
             let response;
             try {
@@ -95,7 +133,11 @@ export function createBondChain(bonds, account, desk, fetchImpl = fetch) {
             }
             if (!response.ok)
                 throw new Error(`The desk at ${desk} answered ${response.status} when asked who paid for task ${task}. Nothing was bonded.`);
-            const { refundTo } = (await response.json().catch(() => undefined)) ?? {};
+            const { board, refundTo } = (await response.json().catch(() => undefined)) ?? {};
+            // Task ids restart with each board, so an answer for another board names who paid for a different task.
+            if (typeof board !== "string" || board.toLowerCase() !== bonds.brainchain.board.toLowerCase()) {
+                throw new Error(`The desk at ${desk} answered for ${typeof board === "string" ? `the task board ${board}` : "an unnamed task board"}, and this server reads task ${task} from ${bonds.brainchain.board}, so who paid for the task cannot be told. Nothing was bonded.`);
+            }
             if (refundTo === null || refundTo === undefined)
                 return undefined;
             if (typeof refundTo !== "string" || !isAddress(refundTo))
@@ -138,77 +180,132 @@ export function createBonds(options) {
             throw new Error(closed);
         return (chain ??= (options.connect ?? createBondChain)(config.bonds, options.signer(), config.desk, options.fetch ?? fetch));
     };
-    function state(b, indexed, now) {
+    /** A bond the limits refuse: what was asked and what is left, in the bond's own token whatever this server pays tasks in. */
+    async function overLimit(which, amount) {
+        const asked = `A bond of ${formatUnits(amount)} USDG is more than`;
+        if (which === "budget") {
+            return `${asked} the ${formatUnits(config.budget - limits.spent())} USDG left in this server's budget. The budget resets when the server restarts; raise BRAINCHAIN_BUDGET_UNITS to allow more per run. Nothing was bonded.`;
+        }
+        const today = await limits.spentToday();
+        const left = today === undefined ? "what is left" : `the ${formatUnits(today < config.daily ? config.daily - today : 0n)} USDG left`;
+        return `${asked} ${left} in this wallet's daily limit, which counts USDG and USDC together. The limit resets at 00:00 UTC; raise BRAINCHAIN_DAILY_UNITS to allow more. Nothing was bonded.`;
+    }
+    function state(b, indexed, now, t, owed) {
         if (b.status === DeedStatus.Settled) {
-            return b.remainderBps === Number(BPS)
-                ? { state: "delivered", settledAt: iso(b.settledAt), back: `${formatUnits(b.amount - fee(b.amount))} USDG`, next: "The bond less Shipped's 1% fee is owed to this wallet on the registry; the worker CLI's `bond claim` collects it." }
-                : { state: "missed", settledAt: iso(b.settledAt), paidTo: b.refundTo, next: "The task was not paid by the deadline, so the bond went to the poster." };
+            if (b.remainderBps !== Number(BPS)) {
+                const why = indexed ? "The Proof is in the index, but the bond settled without it" : "No Proof was recorded";
+                return { state: "missed", settledAt: iso(b.settledAt), paidTo: b.refundTo, next: `${why}, so the bond went to ${MISSED_TO}: ${b.refundTo}.` };
+            }
+            // The registry keeps one sum per wallet, so only an empty one says which bonds were collected.
+            const next = owed === 0n
+                ? "The bond less Shipped's 1% fee was collected: the registry owes this wallet nothing."
+                : `The bond less Shipped's 1% fee was credited to this wallet on the registry, which owes it ${formatUnits(owed)} USDG in all; the worker CLI's \`bond claim\` collects that.`;
+            return { state: "delivered", settledAt: iso(b.settledAt), back: `${formatUnits(b.amount - fee(b.amount))} USDG`, next };
         }
         if (b.checkMetAt > 0n)
             return { state: "marked", markedAt: iso(b.checkMetAt), next: `BrainChain confirms the check after ${iso(b.checkMetAt + CHECK_HOLD_SEC)}, and the bond settles as delivered.` };
+        const settles = `The bond settles after ${iso(b.deadline + CHECK_HOLD_SEC + CHECK_CONFIRM_SEC)} to ${MISSED_TO}: ${b.refundTo}.`;
+        // Shipped sets no first mark after the deadline, so a Proof that is in the index by now does not release the bond.
         if (now > b.deadline)
-            return { state: "lapsed", next: `No Proof was recorded by the deadline. The bond settles to the poster ${b.refundTo} after ${iso(b.deadline + CHECK_HOLD_SEC + CHECK_CONFIRM_SEC)}.` };
-        return { state: "open", next: indexed ? "The Proof is in the index; BrainChain marks the check shortly." : "Waiting for the task to be paid and its Proof recorded." };
+            return { state: "lapsed", next: `${indexed ? "The Proof is in the index, but the bond's check holds no mark and Shipped sets none after the deadline." : "No Proof was recorded by the bond's deadline."} ${settles}` };
+        if (indexed)
+            return { state: "open", next: "The Proof is in the index; BrainChain marks the check shortly." };
+        // A refunded task is final and gets no Proof, so its bond can only be missed.
+        if (t?.status === TaskStatus.Refunded)
+            return { state: "open", next: `The task was refunded, so no Proof will be recorded. ${settles}` };
+        return { state: "open", next: t?.status === TaskStatus.Paid ? "The task is paid; waiting for its Proof to be minted and recorded." : "Waiting for the task to be paid and its Proof recorded." };
     }
-    return {
-        async bond(task, amount) {
-            const c = connected();
-            const t = await c.task(task);
-            if (!t)
-                throw new Error(`There is no task ${task} on BrainChain. Nothing was bonded.`);
-            if (t.poster.toLowerCase() === c.account.toLowerCase())
-                throw new Error(`Task ${task} was posted by this wallet. A bond guarantees delivery to someone else; it earns no standing on a task the same wallet posted. Nothing was bonded.`);
-            const hiredHere = t.status === TaskStatus.Hired && t.model.toLowerCase().endsWith(c.account.slice(2).toLowerCase());
-            if (!hiredHere)
-                throw new Error(`Task ${task} is not hired to this wallet. Bond a task after Jev hires it for the task. Nothing was bonded.`);
-            const now = await c.now();
-            if (t.deadline <= now)
-                throw new Error(`Task ${task}'s deadline, ${iso(t.deadline)}, has passed. Nothing was bonded.`);
-            if (amount < t.bounty)
-                throw new Error(`The bond must be at least the task's bounty, ${formatUnits(t.bounty)} USDG; ${formatUnits(amount)} USDG is under it. Nothing was bonded.`);
-            if (amount < MIN_BOND)
-                throw new Error(`The bond must be at least ${formatUnits(MIN_BOND)} USDG: under that, Shipped's fee and the gas take too much of it. Nothing was bonded.`);
-            if (amount > config.maxBond)
-                throw new Error(`This server bonds at most ${formatUnits(config.maxBond)} USDG on one task. Raise BRAINCHAIN_MAX_BOND_UNITS and restart the server to allow more. Nothing was bonded.`);
-            const existing = (await c.bondsOn(task)).find((b) => b.status !== DeedStatus.Settled);
-            if (existing)
-                throw new Error(`This wallet already has bond No. ${existing.deed} open on task ${task}. Nothing was bonded.`);
-            // A task paid through the desk has the desk as its poster on the board; the bond pays the agent that paid.
-            const payer = await c.payerOf(task);
-            if (payer?.toLowerCase() === c.account.toLowerCase())
-                throw new Error(`Task ${task} was paid for by this wallet. A bond guarantees delivery to someone else; it earns no standing on a task the same wallet paid for. Nothing was bonded.`);
-            const refundTo = payer ?? t.poster;
-            const hold = await limits.take(amount);
-            if (typeof hold === "string")
-                throw new Error(await limitReached(config, limits, hold, "signed payments and bonds for"));
-            try {
-                const [balance, allowance, gasPrice, eth] = await Promise.all([c.usdgBalance(), c.allowance(), c.gasPrice(), c.ethBalance()]);
-                const approves = allowance < amount;
-                const gas = (GAS.create + (approves ? GAS.approve : 0n)) * gasPrice;
-                if (balance < amount)
-                    throw new Error(`${c.account} holds ${formatUnits(balance)} USDG on ${config.bonds.chain}, under the ${formatUnits(amount)} USDG to bond. Nothing was bonded.`);
-                if (eth < gas)
-                    throw new Error(`${c.account} holds ${formatEther(eth)} ETH on ${config.bonds.chain}, under the ${formatEther(gas)} ETH the approval and the bond need. Nothing was bonded.`);
-                const terms = bondTerms({ check: config.bonds.check, proofIndex: config.bonds.proofIndex, usdg: config.bonds.usdg }, { id: task, refundTo, paidThroughDesk: payer !== undefined, deadline: t.deadline }, { address: config.bonds.brainchain.board, chainId: config.bonds.brainchain.chainId });
-                if (approves)
-                    await c.approve(amount);
-                const { deed, tx } = await c.create(terms, amount);
-                const page = await deedPage(deed, options.fetch);
+    async function place(c, task, amount) {
+        const t = await c.task(task);
+        if (!t)
+            throw new Error(`There is no task ${task} on BrainChain. Nothing was bonded.`);
+        if (t.poster.toLowerCase() === c.account.toLowerCase())
+            throw new Error(`Task ${task} was posted by this wallet. A bond guarantees delivery to someone else; it earns no standing on a task the same wallet posted. Nothing was bonded.`);
+        const hiredHere = t.status === TaskStatus.Hired && t.model.toLowerCase().endsWith(c.account.slice(2).toLowerCase());
+        if (!hiredHere)
+            throw new Error(`Task ${task} is not hired to this wallet. Bond a task after Jev hires it for the task. Nothing was bonded.`);
+        const now = await c.now();
+        if (t.deadline <= now)
+            throw new Error(`Task ${task}'s deadline, ${iso(t.deadline)}, has passed. Nothing was bonded.`);
+        if (amount < t.bounty)
+            throw new Error(`The bond must be at least the task's bounty, ${formatUnits(t.bounty)} USDG; ${formatUnits(amount)} USDG is under it. Nothing was bonded.`);
+        if (amount < MIN_BOND)
+            throw new Error(`The bond must be at least ${formatUnits(MIN_BOND)} USDG: under that, Shipped's fee and the gas take too much of it. Nothing was bonded.`);
+        if (amount > config.maxBond)
+            throw new Error(`This server bonds at most ${formatUnits(config.maxBond)} USDG on one task. Raise BRAINCHAIN_MAX_BOND_UNITS and restart the server to allow more. Nothing was bonded.`);
+        // Task ids restart with each board, so a bond on a retired board's task of this number is another task's.
+        const existing = (await c.bondsOn(task)).find((b) => b.status !== DeedStatus.Settled && b.board.toLowerCase() === config.bonds.brainchain.board.toLowerCase());
+        if (existing) {
+            const page = await deedPage(existing.deed, options.fetch);
+            throw new Error(`This wallet already has ${page ? `bond No. ${page.number}` : "a bond"} open on task ${task} (registry id ${existing.deed}${page ? `, ${page.url}` : ""}). Nothing was bonded.`);
+        }
+        // A task paid through the desk has the desk as its poster on the board; the bond pays the agent that paid.
+        const payer = await c.payerOf(task);
+        if (payer?.toLowerCase() === c.account.toLowerCase())
+            throw new Error(`Task ${task} was paid for by this wallet. A bond guarantees delivery to someone else; it earns no standing on a task the same wallet paid for. Nothing was bonded.`);
+        const refundTo = payer ?? t.poster;
+        const hold = await limits.take(amount);
+        if (typeof hold === "string")
+            throw new Error(await overLimit(hold, amount));
+        try {
+            const [balance, allowance, gasPrice, eth] = await Promise.all([c.usdgBalance(), c.allowance(), c.gasPrice(), c.ethBalance()]);
+            const approves = allowance < amount;
+            const gas = (GAS.create + (approves ? GAS.approve : 0n)) * gasPrice;
+            if (balance < amount)
+                throw new Error(`${c.account} holds ${formatUnits(balance)} USDG on ${config.bonds.chain}, under the ${formatUnits(amount)} USDG to bond. Nothing was bonded.`);
+            if (eth < gas)
+                throw new Error(`${c.account} holds ${formatEther(eth)} ETH on ${config.bonds.chain}, under the ${formatEther(gas)} ETH the approval and the bond need. Nothing was bonded.`);
+            const terms = bondTerms({ check: config.bonds.check, proofIndex: config.bonds.proofIndex, usdg: config.bonds.usdg }, { id: task, refundTo, paidThroughDesk: payer !== undefined, deadline: t.deadline }, { address: config.bonds.brainchain.board, chainId: config.bonds.brainchain.chainId });
+            if (approves)
+                await c.approve(amount);
+            const made = await c.create(terms, amount);
+            // A bond that was sent may still confirm, so it stays counted against the budget and the daily limit.
+            if (!("deed" in made)) {
                 return {
-                    bond: deed.toString(),
-                    ...(page ? { number: page.number, url: page.url } : {}),
-                    tx,
+                    possiblyBonded: true,
+                    tx: made.tx,
                     task: task.toString(),
                     amount: `${formatUnits(amount)} USDG`,
                     deadline: iso(terms.deadline),
-                    delivered: `${formatUnits(amount - fee(amount))} USDG back after Shipped's 1% fee, once the task is paid and its Proof recorded`,
-                    missed: `${formatUnits(amount)} USDG to ${refundTo}, ${payer ? "the agent that paid for the task" : "the poster"}, if no Proof is recorded by the deadline`,
-                    next: "Jev reads the bond when it hires. Follow it with brainchain_bond_status.",
+                    error: `The bond's transaction ${made.tx} could not be confirmed: ${made.unconfirmed} The bond may have been placed. Read task ${task} with brainchain_bond_status; do not bond it again.`,
                 };
             }
+            const page = await deedPage(made.deed, options.fetch);
+            return {
+                bond: made.deed.toString(),
+                ...(page ? { number: page.number, url: page.url } : {}),
+                tx: made.tx,
+                task: task.toString(),
+                amount: `${formatUnits(amount)} USDG`,
+                deadline: iso(terms.deadline),
+                delivered: `${formatUnits(amount - fee(amount))} USDG back after Shipped's 1% fee, once the task is paid and its Proof recorded`,
+                missed: `${formatUnits(amount)} USDG to ${refundTo}, ${payer ? "the agent that paid BrainChain's desk for the task" : "the poster, as the task was posted on the board directly"}, if no Proof is recorded by the deadline`,
+                next: "Follow it with brainchain_bond_status. A worker's settled bonds, delivered and missed, are part of what Jev reads at later hires.",
+            };
+        }
+        catch (error) {
+            await limits.give(hold);
+            throw error;
+        }
+    }
+    /** One call at a time per task: two would both pass the open-bond check before either bond exists. */
+    const placing = new Set();
+    return {
+        async bond(task, amount) {
+            const c = connected();
+            if (placing.has(task))
+                throw new Error(`This server is already placing a bond on task ${task}. Wait for that call's reply; this call bonded nothing.`);
+            placing.add(task);
+            try {
+                return await place(c, task, amount);
+            }
             catch (error) {
-                await limits.give(hold);
-                throw error;
+                // A bond that may have been sent answers instead of throwing, so whatever is thrown bonded nothing.
+                const said = sentence(firstLine(error));
+                throw new Error(said.endsWith("Nothing was bonded.") ? said : `${said} Nothing was bonded.`);
+            }
+            finally {
+                placing.delete(task);
             }
         },
         async status(task) {
@@ -216,14 +313,22 @@ export function createBonds(options) {
             const bonds = await c.bondsOn(task);
             if (bonds.length === 0)
                 return { task: task.toString(), wallet: c.account, bonds: [] };
-            const [now, indexed, pages] = await Promise.all([c.now(), c.proofOf(task), Promise.all(bonds.map((b) => deedPage(b.deed, options.fetch)))]);
+            const delivered = bonds.some((b) => b.status === DeedStatus.Settled && b.remainderBps === Number(BPS));
+            // Only a bond still waiting for its Proof is worded by where the task stands.
+            const [now, indexed, tasks, owed, pages] = await Promise.all([
+                c.now(),
+                Promise.all(bonds.map((b) => c.proofOf(task, b.board))),
+                Promise.all(bonds.map((b) => (b.status !== DeedStatus.Settled && b.checkMetAt === 0n ? c.task(task, b.board) : undefined))),
+                delivered ? c.owed() : 0n,
+                Promise.all(bonds.map((b) => deedPage(b.deed, options.fetch))),
+            ]);
             return {
                 task: task.toString(),
                 wallet: c.account,
-                proofIndexed: indexed > 0n,
+                proofIndexed: indexed.some((n) => n > 0n),
                 bonds: bonds.map((b, i) => {
                     const page = pages[i];
-                    return { bond: b.deed.toString(), ...(page ? { number: page.number, url: page.url } : {}), amount: `${formatUnits(b.amount)} USDG`, deadline: iso(b.deadline), ...state(b, indexed > 0n, now) };
+                    return { bond: b.deed.toString(), board: b.board, ...(page ? { number: page.number, url: page.url } : {}), amount: `${formatUnits(b.amount)} USDG`, deadline: iso(b.deadline), ...state(b, indexed[i] > 0n, now, tasks[i], owed) };
                 }),
             };
         },

package/dist/config.js

@@ -52,7 +52,7 @@ const BONDS = {
         proofIndex: "0x0fb02559e704549794EdF3FBBBe91DB88bB849ee",
         rpc: "https://rpc.mainnet.chain.robinhood.com",
         chain: "Robinhood Chain",
-        brainchain: { rpc: "https://rpc.usebrainchain.com", chainId: 274663, board: "0x8385bb4b8990411CcdD8e851B2676da1A4C1f3C4" },
+        brainchain: { rpc: "https://rpc.usebrainchain.com", chainId: 274663, board: "0x44b8464342Bbfb9B565FAE494DfDefa37D33A211", retired: ["0x8385bb4b8990411CcdD8e851B2676da1A4C1f3C4"] },
     },
     testnet: undefined,
 };
@@ -66,7 +66,8 @@ export const MAX_TIMEOUT_SECONDS = 600;
  * recorded any order it charged.
  */
 export const REPOST_AFTER_MINUTES = 15;
-const DEFAULT_MAX_PRICE = 1000000n;
+/** The desk's price for a task. A higher BRAINCHAIN_MAX_PRICE_UNITS is a ceiling, not what a task costs. */
+export const DEFAULT_MAX_PRICE = 1000000n;
 const DEFAULT_BUDGET = 10000000n;
 const DEFAULT_MAX_BOND = 10000000n;
 export function formatUnits(units) {

package/dist/index.js

@@ -21,7 +21,7 @@ Usage:
 
 Environment:
   BRAINCHAIN_PAYER_KEY        Private key of the paying wallet, 64 hex characters with or without 0x.
-                              Needed to post tasks and to approve; reading orders works without it.
+                              Needed to post tasks, to bond and to approve; reading orders works without it.
   BRAINCHAIN_PAYER_KEY_FILE   A file holding that key instead, readable only by your account. Absolute or starting with ~/.
   BRAINCHAIN_NETWORK          mainnet (default) or testnet.
   BRAINCHAIN_PAY_ON           robinhood (default) pays in USDG on Robinhood Chain;

package/dist/payments.js

@@ -1,19 +1,20 @@
 import { ExactEvmScheme } from "@x402/evm/exact/client";
 import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
-import { keccak256, toBytes } from "viem";
+import { keccak256, RpcRequestError, toBytes } from "viem";
 import { formatUnits, MAX_TIMEOUT_SECONDS, REPOST_AFTER_MINUTES } from "./config.js";
 import { createLimits } from "./limits.js";
 const BUDGET_REASON = "budget";
 const DAILY_REASON = "daily limit";
-const RESULT_LIMIT = 20_000;
-/** What a refused budget or daily limit tells a person, for a post and for a bond alike. */
-export async function limitReached(config, limits, which, verb = "signed payments for") {
+/** A result longer than this is cut, with a link to the rest. */
+export const RESULT_LIMIT = 20_000;
+/** What a refused budget or daily limit tells a person who posts. */
+async function limitReached(config, limits, which) {
     if (which === "budget") {
-        return `This server has already ${verb} ${formatUnits(limits.spent())} of its ${formatUnits(config.budget)} ${config.token} budget. The budget resets when the server restarts; raise BRAINCHAIN_BUDGET_UNITS to allow more per run. Nothing was charged.`;
+        return `This server has already signed payments for ${formatUnits(limits.spent())} of its ${formatUnits(config.budget)} ${config.token} budget. The budget resets when the server restarts; raise BRAINCHAIN_BUDGET_UNITS to allow more per run. Nothing was charged.`;
     }
     const today = await limits.spentToday();
     // One limit covers both chains, so it is named without a token.
-    return `This wallet has already ${verb} ${today === undefined ? "most" : formatUnits(today)} of its daily limit of ${formatUnits(config.daily)}, counting USDG and USDC together. The limit resets at 00:00 UTC; raise BRAINCHAIN_DAILY_UNITS to allow more. Nothing was charged.`;
+    return `This wallet has already signed payments for ${today === undefined ? "most" : formatUnits(today)} of its daily limit of ${formatUnits(config.daily)}, counting USDG and USDC together. The limit resets at 00:00 UTC; raise BRAINCHAIN_DAILY_UNITS to allow more. Nothing was charged.`;
 }
 /** Same serialization the desk hashes into an order id: sorted keys, no whitespace. */
 export function canonicalStringify(value) {
@@ -33,9 +34,39 @@ export function orderIdOf(paymentPayload) {
     return keccak256(toBytes(canonicalStringify(paymentPayload.payload)));
 }
 const sameAddress = (a, b) => a.toLowerCase() === b.toLowerCase();
-const firstLine = (error) => (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
+export const firstLine = (error) => (error instanceof Error ? error.message : String(error)).split("\n")[0] ?? "";
 /** Text from the desk or a library, ended as a sentence so what this server adds after it reads apart. */
-const sentence = (text) => (/[.!?]$/.test(text.trim()) ? text.trim() : `${text.trim()}.`);
+export const sentence = (text) => (/[.!?]$/.test(text.trim()) ? text.trim() : `${text.trim()}.`);
+/** A library's error in a few words: the HTTP status or the node's own refusal when there is one, else the error's first line. */
+export function brief(error) {
+    for (let cause = error; cause instanceof Error; cause = cause.cause) {
+        const { status } = cause;
+        if (typeof status === "number")
+            return `HTTP ${status}.`;
+        if (cause instanceof RpcRequestError && cause.details)
+            return sentence(cause.details.split("\n")[0]);
+    }
+    return sentence(firstLine(error));
+}
+const CHAINS = new Map([
+    ["4663", "Robinhood Chain"],
+    ["8453", "Base"],
+    ["46630", "Robinhood Chain testnet"],
+    ["84532", "Base Sepolia"],
+]);
+const SOLANA = new Map([
+    ["5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "Solana"],
+    ["EtWTRABZaYq6iMfeYKouRu166VU2xqa1", "Solana devnet"],
+]);
+/**
+ * Where an order was paid, from its own network: the server reading it may pay on another chain.
+ * An order on `acp:<chain id>` was paid into an escrow there, which the desk never holds.
+ */
+export function paidOn(network) {
+    const [kind, id = ""] = typeof network === "string" ? network.split(":") : [];
+    const chain = kind === "solana" ? SOLANA.get(id) : kind === "eip155" || kind === "acp" ? CHAINS.get(id) : undefined;
+    return { chain: chain ?? "the chain it was paid on", escrow: kind === "acp" };
+}
 /** Statuses that say "not now" rather than "no", alongside every 5xx. */
 const RETRY_LATER = new Set([408, 425, 429]);
 /** Settles as `work` does, or rejects once `signal` aborts. */
@@ -61,8 +92,10 @@ export function createDesk(options) {
     const limits = options.limits ?? createLimits(config, account);
     const endpoint = `${config.desk}/x402/tasks`;
     const recent = new Map();
-    /** When this process paid, or may have paid, for each order; the desk can take minutes to know one. */
-    const paidAt = new Map();
+    /** When this process paid, or may have paid, for each order, and how to forget its post; the desk can take minutes to know one. */
+    const paid = new Map();
+    /** What each of those orders still holds against the budget and the daily limit. */
+    const held = new Map();
     /** The desk's price, read from a fresh 402 challenge. */
     async function quotedPrice(signal = AbortSignal.timeout(15_000)) {
         try {
@@ -145,6 +178,34 @@ export function createDesk(options) {
             error: `${cause} The payment may have gone through. Read this order with brainchain_get_task; do not post the task again.`,
         };
     }
+    /**
+     * The desk answers 402 for a payment it refuses, and for a settlement it could not
+     * confirm, which it keeps as an order and checks against the chain. Says why such a
+     * payment may still be charged, or undefined when the desk has no order or gave it up.
+     */
+    async function stillOpen(order) {
+        let response;
+        try {
+            response = await fetchImpl(`${endpoint}/${order}`, { signal: AbortSignal.timeout(10_000) });
+        }
+        catch {
+            return "the order could not be read";
+        }
+        if (response.status === 404)
+            return undefined;
+        const view = response.ok ? await jsonObject(response) : undefined;
+        if (typeof view?.state !== "string")
+            return "the order could not be read";
+        return view.state === "failed" ? undefined : `it holds the order as ${view.state}`;
+    }
+    /** A payment the desk gave up was never charged, so its task can be posted again at once and its amount spent on another. */
+    async function release(order) {
+        paid.get(order)?.forget();
+        const hold = held.get(order);
+        held.delete(order);
+        if (hold)
+            await limits.give(hold);
+    }
     /** An agent that retries a post it gave up waiting on gets the first order back instead of paying twice. */
     function post(task) {
         const now = Date.now();
@@ -164,7 +225,7 @@ export function createDesk(options) {
         entry.reply.then((reply) => {
             const { order } = reply;
             if (typeof order === "string")
-                paidAt.set(order.toLowerCase(), now);
+                paid.set(order.toLowerCase(), { at: now, forget });
             else
                 forget();
         }, forget);
@@ -178,7 +239,11 @@ export function createDesk(options) {
                 await limits.give(hold);
             hold = undefined;
         };
-        const receipt = (order) => ({ order, price: `${formatUnits(hold?.amount ?? 0n)} ${config.token}`, statusUrl: `${endpoint}/${order}` });
+        const receipt = (order) => {
+            if (hold)
+                held.set(order.toLowerCase(), hold);
+            return { order, price: `${formatUnits(hold?.amount ?? 0n)} ${config.token}`, statusUrl: `${endpoint}/${order}` };
+        };
         const client = x402Client.fromConfig({
             schemes: [{ network: config.network, client: new ExactEvmScheme(account()) }],
             spendControls: { allowedAssets: [{ network: config.network, asset: config.asset, maxAmountPerPayment: config.maxPrice.toString() }] },
@@ -236,11 +301,18 @@ export function createDesk(options) {
             return { ...reply, ...receipt(typeof reply.order === "string" ? reply.order : orderIdOf(signed)) };
         }
         // The desk answers 400 (a brief it refuses, including one too large to post)
-        // and 402 (a payment it refuses) before settling. Any other answer to a
-        // signed payment may have charged it.
+        // before settling. Any other answer to a signed payment may have charged it,
+        // a 402 included unless the desk has no order for it or gave the payment up.
         if (signed && response.status !== 400 && response.status !== 402) {
             return possiblyCharged(receipt(typeof reply.order === "string" ? reply.order : orderIdOf(signed)), `The desk answered ${response.status}.`);
         }
+        if (signed && response.status === 402) {
+            const order = orderIdOf(signed);
+            const open = await stillOpen(order);
+            const reason = typeof reply.error === "string" && reply.error.trim() ? ` (${reply.error.trim().replace(/[.!?]+$/, "")})` : "";
+            if (open)
+                return possiblyCharged(receipt(order), `The desk answered 402${reason}, and ${open}.`);
+        }
         await unreserve();
         if (response.status === 402)
             throw new Error(await explainRefusal(reply.error));
@@ -256,8 +328,9 @@ export function createDesk(options) {
         }
         const view = await jsonObject(response);
         if (response.status === 404) {
-            const at = paidAt.get(order);
+            const at = paid.get(order)?.at;
             if (at === undefined || Date.now() - at >= REPOST_AFTER_MINUTES * 60_000) {
+                await release(order);
                 return {
                     order,
                     error: "The desk has no order with this id.",
@@ -281,6 +354,8 @@ export function createDesk(options) {
         // An unreadable 2xx comes from a proxy or a dropped connection; ask again.
         if (!view)
             return { order, error: "The desk's reply could not be read.", done: false, next: "Read the order again shortly.", retryAfterSeconds: 30 };
+        if (view.state === "failed")
+            await release(order);
         // Results are served by the desk itself; anything else is left as a link.
         if (typeof view.result === "string" && view.result.startsWith(`${config.desk}/records/`)) {
             try {
@@ -290,7 +365,7 @@ export function createDesk(options) {
                     view.resultText =
                         full.length <= RESULT_LIMIT
                             ? full
-                            : `${full.slice(0, RESULT_LIMIT)}\n\n[Cut at ${RESULT_LIMIT.toLocaleString("en-US")} of ${full.length.toLocaleString("en-US")} characters. The full result is at ${view.result}.]`;
+                            : `${full.slice(0, RESULT_LIMIT)}\n\n[Cut at ${RESULT_LIMIT.toLocaleString("en-US")} of ${full.length.toLocaleString("en-US")} UTF-16 units. The full result is at ${view.result}.]`;
                 }
                 else
                     view.resultError = `The result could not be fetched (HTTP ${text.status}); it is at ${view.result}.`;
@@ -307,6 +382,10 @@ export function createDesk(options) {
 export function guidance(view, config, now = Date.now()) {
     const task = (view.task ?? {});
     const wait = (retryAfterSeconds, next) => ({ done: false, next, retryAfterSeconds });
+    const { chain, escrow } = paidOn(view.network);
+    // The desk sends no refund for an escrowed order: the escrow gives the money back, with no transaction of the desk's to wait for.
+    const escrowReturns = `escrow on ${chain} that holds the payment returns the full amount`;
+    const refunding = escrow ? `The ${escrowReturns}.` : `The refund is being sent on ${chain}.`;
     // Without a task the desk could not post the order, so no work ever existed.
     const why = typeof view.refundReason === "string" ? `${view.refundReason} ` : task.status === undefined ? "The task could not be posted. " : "";
     const due = typeof task.due?.by === "string" ? task.due.by : undefined;
@@ -326,15 +405,17 @@ export function guidance(view, config, now = Date.now()) {
         const left = Number.isFinite(closes) ? Math.ceil((closes - now) / 1000) : undefined;
         // The desk sends the refund within a minute or two of the window closing.
         if (left !== undefined && left <= 0)
-            return wait(60, `${start} The dispute window has closed, so the full amount is refunded on ${config.chain} shortly.`);
+            return wait(60, `${start} The dispute window has closed, so ${escrow ? `the ${escrowReturns}` : `the full amount is refunded on ${chain} shortly`}.`);
         const when = left === undefined ? `, ${config.terms.finalAfter} after grading` : ` at ${due}`;
-        return wait(left === undefined ? 900 : left + 60, `${start} The full amount is refunded on ${config.chain} when the dispute window closes${when}, unless the model disputes the grade and a ruling pays it. Report this now, then read the order again after that time for the refund transaction.`);
+        return wait(left === undefined ? 900 : left + 60, escrow
+            ? `${start} The ${escrowReturns}, unless the model disputes the grade before the dispute window closes${when}${left === undefined ? "," : ""} and a ruling pays it. Report this now, then read the order again after that time.`
+            : `${start} The full amount is refunded on ${chain} when the dispute window closes${when}, unless the model disputes the grade and a ruling pays it. Report this now, then read the order again after that time for the refund transaction.`);
     };
     switch (view.state) {
         case "paid-out":
             return paid();
         case "refunded":
-            return { done: true, next: `${why}The full amount was refunded on ${config.chain}${typeof view.refundTx === "string" ? ` in ${view.refundTx}` : ""}.` };
+            return { done: true, next: escrow ? `${why}The ${escrowReturns}.` : `${why}The full amount was refunded on ${chain}${typeof view.refundTx === "string" ? ` in ${view.refundTx}` : ""}.` };
         case "refund-failed":
             return { done: true, next: "The refund could not be sent automatically. Write to hello@usebrainchain.com with this order id." };
         case "failed":
@@ -346,14 +427,14 @@ export function guidance(view, config, now = Date.now()) {
         case "unconfirmed":
             return wait(30, "The payment may have gone through; BrainChain is checking it against the chain. Do not post the task again.");
         case "refunding":
-            return wait(60, `${why}The refund is being sent on ${config.chain}.`);
+            return wait(60, `${why}${refunding}`);
     }
     switch (task.status) {
         case "paid":
             return paid();
         case "refunded":
             // The board has returned the money to the desk; the payer's refund transaction comes next.
-            return wait(60, `${why}The refund is being sent on ${config.chain}.`);
+            return wait(60, `${why}${refunding}`);
         // A dispute, a ruling under its appeal window and an appeal can each still change a grade, accepted or not.
         case "disputed":
             return wait(600, `The grade is disputed; Jev rules on it${by}. If no ruling comes, the grade stands.${result}`);

package/dist/premiums.js

@@ -21,7 +21,7 @@ export const PREMIUMS_TOOL = {
     title: "Stock premiums on Robinhood Chain",
     description: "What tokenized US stocks cost on Robinhood Chain against their Chainlink price right now: pool price, Chainlink price, " +
         "the premium in percent and the feed's age, for NVDA, SPY, AAPL, TSLA, GOOGL, META and MSFT. Read from the chain, free, no key " +
-        "and no payment. Outside US market hours no new tokens are minted, so the premium shows where the market clears on its own. " +
+        "and no payment. Over a weekend the feeds stand still and the pools keep trading. " +
         "usMarketOpen is true during the regular session, 09:30 to 16:00 New York time, Monday to Friday; it does not know exchange holidays or early closes. " +
         "Prices are in USDG per token with each token's split multiplier applied. Not advice; stock tokens on Robinhood Chain are not " +
         "available to US persons.",

package/dist/server.js

@@ -5,7 +5,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { createPublicClient, defineChain, formatEther, http, maxUint256, parseAbi } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { bondsClosed, createBonds } from "./bonds.js";
-import { expandHome, formatUnits, resolveConfig } from "./config.js";
+import { DEFAULT_MAX_PRICE, expandHome, formatUnits, resolveConfig } from "./config.js";
 import { stateDirProblem } from "./daily.js";
 import { createLimits } from "./limits.js";
 import { createDesk } from "./payments.js";
@@ -21,7 +21,9 @@ export const erc20 = parseAbi([
 export const INSTRUCTIONS = `Post a task with ${POST_TASK_NAME}, then read it with ${GET_TASK_NAME} and the order id it returns, waiting retryAfterSeconds between reads until done is true. ` +
     `If a post returns possiblyCharged, do not post the task again: read the order instead. ` +
     `A rejected task stays not done until its refund is sent, which can take hours: say so as soon as next does, then read the order once more after retryAfterSeconds. ` +
+    `Two things end it without a refund transaction: a ruling that pays the model, and a refund the desk gives up sending, when state reads refund-failed and next says who to write to; pass that on. ` +
     `${BOND_TASK_NAME} locks USDG behind a BrainChain task this wallet will deliver as a worker, and ${BOND_STATUS_NAME} follows it; neither posts a task. ` +
+    `If a bond returns possiblyBonded, do not bond the task again: read its status instead. ` +
     `The paying wallet's key is for this server alone. Never read it, print it, write it down or pass it to a command. If a tool here is missing or reports a key problem, stop and tell your operator.`;
 const KEY_HELP = `Add BRAINCHAIN_PAYER_KEY to this server's env in your MCP client config (in Claude Code, \`claude mcp add … -e BRAINCHAIN_PAYER_KEY=…\`), or BRAINCHAIN_PAYER_KEY_FILE with the path of a file holding it, then restart the server. ` +
     `${GET_TASK_NAME} and ${PREMIUMS_NAME} work without a key; ${BOND_STATUS_NAME} reads this wallet's bonds, so it needs the key too. An agent reading this: stop and tell your operator. Do not look for the key.`;
@@ -102,7 +104,10 @@ export function walletReport(config, address, funds, approve) {
         return lines.join("\n");
     }
     const { balance, allowance, eth } = funds;
-    const short = balance < config.maxPrice ? ` A task costs ${config.terms.cost}, so send at least ${formatUnits(config.maxPrice - balance)} ${config.token} to it on ${config.chain} before posting.` : "";
+    // Under a raised ceiling the wallet may still hold the price, so it is told what covers the ceiling, not what posting needs.
+    const ceiling = config.maxPrice !== DEFAULT_MAX_PRICE;
+    const missing = `send at least ${formatUnits(config.maxPrice - balance)} ${config.token} to it on ${config.chain}`;
+    const short = balance >= config.maxPrice ? "" : ceiling ? ` A task costs ${config.terms.cost}; ${missing} to cover that.` : ` A task costs ${config.terms.cost}, so ${missing} before posting.`;
     lines.push(`It holds ${formatUnits(balance)} ${config.token}.${short}`);
     if (allowance !== undefined) {
         if (allowance >= maxUint256 / 2n)
@@ -111,7 +116,7 @@ export function walletReport(config, address, funds, approve) {
             lines.push(`Permit2 may spend up to ${formatUnits(allowance)} of its ${config.token}.`);
         else {
             const only = allowance > 0n ? ` (only ${formatUnits(allowance)})` : "";
-            lines.push(`Permit2 is not approved to spend enough of its ${config.token} for a task${only}. Run \`${approve}\` once; it needs a little ETH on ${config.chain}, and the wallet holds ${formatEther(eth)} ETH there.`);
+            lines.push(`Permit2 is not approved to spend enough of its ${config.token} for a task${ceiling ? ` that costs ${formatUnits(config.maxPrice)}` : ""}${only}. Run \`${approve}\` once; it needs a little ETH on ${config.chain}, and the wallet holds ${formatEther(eth)} ETH there.`);
         }
     }
     return lines.join("\n");
@@ -130,7 +135,13 @@ function deskFor(env, version, fetchImpl) {
         const refuse = async () => {
             throw new Error(problem);
         };
-        return { desk: { post: refuse, get: refuse }, terms: problem, bonds: { bond: refuse, status: refuse }, bondTools: bondTools({ maxBond: 0n, budget: 0n }, undefined, `Invalid setting: ${problem}`) };
+        return {
+            desk: { post: refuse, get: refuse },
+            terms: problem,
+            bonds: { bond: refuse, status: refuse },
+            bondTools: bondTools({}, undefined, { bond: `Invalid setting: ${problem}`, status: `Invalid setting: ${problem}` }),
+            refused: new Map([POST_TASK_NAME, GET_TASK_NAME, BOND_TASK_NAME, BOND_STATUS_NAME].map((name) => [name, problem])),
+        };
     }
     let account;
     let keyProblem;
@@ -169,22 +180,32 @@ function deskFor(env, version, fetchImpl) {
             return { balance, allowance };
         },
     });
-    const closed = bondsClosed(config) ?? (problem ? `Invalid setting: ${problem}` : undefined);
+    // What the descriptions promise for a setting that cannot be used: a tool the setting stops answers with it
+    // and touches nothing else. A refused state folder could still take a write, or hang on one, so it stops
+    // the two tools that pay. Reading a bond needs the key and no record, so only a key problem stops that.
+    const closed = bondsClosed(config);
+    const refused = new Map();
+    if (problem)
+        for (const name of [POST_TASK_NAME, BOND_TASK_NAME])
+            refused.set(name, keyProblem ? `${problem} ${KEY_HELP}` : problem);
+    if (keyProblem)
+        refused.set(BOND_STATUS_NAME, `${keyProblem} ${KEY_HELP}`);
     return {
         desk,
         terms: { ...config.terms, ...(account ? { wallet: account.address } : {}), ...(problem ? { problem } : {}) },
         bonds: createBonds({ config, signer: payer, limits }),
-        bondTools: bondTools(config, account?.address, closed),
+        bondTools: bondTools(config, account?.address, { bond: problem ? `Invalid setting: ${problem}` : closed, status: keyProblem ? `Invalid setting: ${keyProblem}` : closed }),
+        refused,
     };
 }
 export function createServer(env, version, options = {}) {
-    const { desk, terms, bonds, bondTools: bondToolList } = deskFor(env, version, options.fetch);
+    const { desk, terms, bonds, bondTools: bondToolList, refused } = deskFor(env, version, options.fetch);
     const problem = typeof terms === "string" ? terms : terms.problem;
     if (problem)
         (options.log ?? console.error)(`brainchain-mcp has an invalid setting: ${problem}`);
     const tools = [postTaskTool(terms), GET_TASK_TOOL, PREMIUMS_TOOL, ...bondToolList];
     const server = new Server({ name: "brainchain", title: "BrainChain", version }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
     server.setRequestHandler(ListToolsRequestSchema, () => ({ tools }));
-    server.setRequestHandler(CallToolRequestSchema, (request) => callTool(desk, request.params.name, request.params.arguments, undefined, bonds));
+    server.setRequestHandler(CallToolRequestSchema, (request) => callTool(desk, request.params.name, request.params.arguments, undefined, bonds, refused));
     return server;
 }

package/dist/shipped.js

@@ -1,7 +1,7 @@
 // Shipped's registry on Robinhood Chain and the terms of a BrainChain delivery
 // bond on it: a deed with no judge, decided by Shipped's on-chain check reading
-// BrainChain's ProofIndex, proofOf(task) >= 1, with the task's poster as the
-// refund side.
+// BrainChain's ProofIndex, proofOf(task) >= 1, with the agent that paid for the
+// task as the refund side.
 import { decodeAbiParameters, decodeFunctionData, encodeAbiParameters, encodeFunctionData, parseAbi } from "viem";
 export const proofIndexAbi = parseAbi(["function proofOf(address board, uint256 taskId) view returns (uint256)"]);
 const TERMS = "(string title, string milestone, address project, uint8 projectKind, address asset, uint64 deadline, address verifier, address backupVerifier, address appealPanel, address check, bytes checkData, address refundTo, uint16 defaultRemainderBps, uint16 refundCapBps, bool allowPartial, uint32 verifierGrace, uint32 backupGrace, uint32 appealWindow, uint32 panelWindow, uint128 appealBond, uint128 verifierFee, address[] refundExcluded)";
@@ -22,15 +22,17 @@ export const taskBoardAbi = parseAbi([
 export const DeedStatus = { None: 0, Open: 1, Ruled: 2, Appealed: 3, Settled: 4 };
 export const Ruling = { None: 0, Accepted: 1, Rejected: 2, Partial: 3, Invalid: 4, Conceded: 5, Default: 6, CheckMet: 7 };
 /** TaskBoard.Status. */
-export const TaskStatus = { Open: 1, Hired: 2 };
+export const TaskStatus = { Open: 1, Hired: 2, Paid: 6, Refunded: 7 };
 export const BPS = 10000n;
 export const FEE_BPS = 100n;
-/** The bond's deadline is the task's plus this. */
-export const BOND_LEAD_SEC = 48n * 3600n;
+/** The bond's deadline is the task's plus this: 48 hours for a grade, a dispute and an appealed ruling on set 3.5.0, then the worker's day to mint. */
+export const BOND_LEAD_SEC = 72n * 3600n;
 export const CHECK_HOLD_SEC = 3600n;
 export const CHECK_CONFIRM_SEC = 86400n;
 /** Under this the fee and the gas take too much of the bond. */
 export const MIN_BOND = 2000000n;
+/** Who a missed bond pays, in the same words wherever a tool says it. A bond names the address, not which of the two it is. */
+export const MISSED_TO = "the agent that paid BrainChain's desk for the task, or to the poster for a task posted on the board directly";
 const ZERO = "0x0000000000000000000000000000000000000000";
 const checkDataTypes = [{ type: "address" }, { type: "bytes" }, { type: "uint8" }, { type: "uint256" }];
 /** Task ids restart with each board, so the board is part of the key. */

package/dist/tools.js

@@ -1,13 +1,15 @@
 import { formatUnits, REPOST_AFTER_MINUTES } from "./config.js";
-import { canonicalStringify } from "./payments.js";
-import { PREMIUMS_NAME, readPremiums } from "./premiums.js";
-import { MIN_BOND } from "./shipped.js";
+import { brief, canonicalStringify, RESULT_LIMIT } from "./payments.js";
+import { PREMIUMS_NAME, PREMIUMS_TOOL, readPremiums } from "./premiums.js";
+import { MIN_BOND, MISSED_TO } from "./shipped.js";
 export const POST_TASK_NAME = "brainchain_post_task";
 /** The desk's cap on a task as it goes on chain: title, brief, levels and pass level as JSON. */
 export const MAX_TASK_BYTES = 64_000;
 export const GET_TASK_NAME = "brainchain_get_task";
 export const BOND_TASK_NAME = "brainchain_bond_task";
 export const BOND_STATUS_NAME = "brainchain_bond_status";
+/** What a length in UTF-16 units, which the desk counts in, means to someone writing a brief. */
+const UNITS = "most characters take one, an emoji two or more";
 const TASK_ID = { type: "string", pattern: "^[1-9][0-9]{0,17}$", description: "The task's id on BrainChain's task board." };
 const BOND_TASK_INPUT = {
     type: "object",
@@ -19,25 +21,37 @@ const BOND_TASK_INPUT = {
     additionalProperties: false,
 };
 const BOND_STATUS_INPUT = { type: "object", properties: { task: TASK_ID }, required: ["task"], additionalProperties: false };
-/** The bond tools, worded for the network and the wallet this server holds; `closed` says why no bond can be placed. */
-export function bondTools(config, wallet, closed) {
+/**
+ * The bond tools, worded for the network and the wallet this server holds. `closed` says, per tool, why it
+ * cannot run: reading a bond needs less than placing one, so the two can differ. Without settings to read,
+ * the cap is named by its variable.
+ */
+export function bondTools(config, wallet, closed = {}) {
     const where = wallet ? `this server's wallet ${wallet}` : "this server's wallet";
+    const lead = (why) => (why ? `${why} Until then this tool only returns that error. ` : "");
+    const cap = config.maxBond === undefined ? "BRAINCHAIN_MAX_BOND_UNITS" : `${formatUnits(config.maxBond)} USDG`;
     return [
         {
             name: BOND_TASK_NAME,
             title: "Bond a BrainChain task on Shipped",
-            description: (closed ? `${closed} Until then this tool only returns that error. ` : "") +
-                `Lock USDG on Shipped behind a BrainChain task from ${where}, as the worker that will deliver it. ` +
-                `If the task is paid and its Proof is minted, the bond comes back less Shipped's 1% fee; if the task is not paid by its deadline, the bond goes to the task's poster. ` +
-                `Jev reads the bond when it hires. The amount is at least the task's bounty and ${formatUnits(MIN_BOND)} USDG, at most ${formatUnits(config.maxBond)} USDG per task, and counts against this server's budget and daily limit like a post. ` +
-                `The wallet needs the USDG and a little ETH on Robinhood Chain. Never bond a task this wallet posted. Returns the bond number; follow it with ${BOND_STATUS_NAME}.`,
+            description: lead(closed.bond) +
+                `Lock USDG on Shipped behind a BrainChain task from ${where}, as the worker that will deliver it. Jev must already have hired this wallet for the task. ` +
+                `If the task is paid and its Proof is recorded by the bond's deadline, which is set after the task's and comes back in the reply, the bond less Shipped's 1% fee is credited to the wallet on Shipped's registry, where the worker CLI's \`bond claim\` collects it; if not, the bond goes to ${MISSED_TO}. ` +
+                `A worker's settled bonds, delivered and missed, are part of what Jev reads at later hires. ` +
+                `The amount is at least the task's bounty and ${formatUnits(MIN_BOND)} USDG, at most ${cap} per task, and counts against this server's budget and daily limit like a post. ` +
+                `The wallet needs the USDG and a little ETH on Robinhood Chain. Never bond a task this wallet posted or paid for. Returns the bond, its transaction and its deadline; follow it with ${BOND_STATUS_NAME}. ` +
+                `If the reply says possiblyBonded, the bond may have been placed and could not be confirmed: read the task with ${BOND_STATUS_NAME} and do not bond it again.`,
             inputSchema: BOND_TASK_INPUT,
             annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
         },
         {
             name: BOND_STATUS_NAME,
             title: "Read this wallet's bond on a BrainChain task",
-            description: `${closed ? `${closed} ` : ""}Where ${where}'s bonds on a task stand: open, marked (the Proof is recorded and the check waits out its hour), delivered (the bond less 1% is owed to the wallet) or missed (paid to the poster), with the next step.`,
+            description: lead(closed.status) +
+                `Where ${where}'s bonds on a task stand: open, marked (the Proof is recorded and the check waits out its hour), ` +
+                `lapsed (the bond's deadline passed with its check unmarked, so the bond waits to settle as missed), ` +
+                `delivered (the bond less Shipped's 1% fee was credited to the wallet on Shipped's registry; the reply says whether it was collected or what the registry still owes the wallet) ` +
+                `or missed (paid to ${MISSED_TO}), with the next step.`,
             inputSchema: BOND_STATUS_INPUT,
             annotations: { readOnlyHint: true, openWorldHint: true },
         },
@@ -46,13 +60,13 @@ export function bondTools(config, wallet, closed) {
 const POST_TASK_INPUT = {
     type: "object",
     properties: {
-        title: { type: "string", minLength: 1, maxLength: 120, description: "One line naming the deliverable." },
+        title: { type: "string", minLength: 1, maxLength: 120, description: "One line naming the deliverable, up to 120 UTF-16 units." },
         brief: {
             type: "string",
             minLength: 1,
             maxLength: 32000,
             description: "What to produce, in what format, and anything the model must not do. Models cannot browse, so include every fact they need. " +
-                "Up to 32,000 characters, an emoji counting as two, and the whole task as JSON at most 64,000 bytes: about 21,000 characters of Chinese, Japanese or Korean.",
+                `Up to 32,000 UTF-16 units, as the desk counts: ${UNITS} (a flag four, a family emoji eleven). The whole task as JSON is at most 64,000 bytes: about 21,000 characters of Chinese, Japanese or Korean.`,
         },
         levels: {
             type: "array",
@@ -60,7 +74,12 @@ const POST_TASK_INPUT = {
             minItems: 2,
             maxItems: 3,
             uniqueItems: true,
-            description: "Two or three different quality levels, best first, each a short description a reader could check. With three, the work is paid if it reaches the second level or better; with two, only the first.",
+            description: "Two or three different quality levels, best first, each a short description a reader could check, up to 200 UTF-16 units. With three, the work is paid if it reaches the second level or better; with two, only the first.",
+        },
+        passIndex: {
+            type: "integer",
+            enum: [0, 1],
+            description: "Leave this out: the tool sets the pass level itself. A brief copied with it is accepted only when it names that level, 1 with three levels and 0 with two.",
         },
     },
     required: ["title", "brief", "levels"],
@@ -68,9 +87,9 @@ const POST_TASK_INPUT = {
 };
 /** Given a configuration error instead of terms, the description leads with it. */
 export function postTaskTool(terms) {
-    const about = `Pay for a task on BrainChain. Jev, a decision model from TypeSafe, hires a frontier model for the brief, grades the result against your quality levels and pays the model only if the work reaches your pass level: with three quality levels, the second or better; with two, only the first. ` +
+    const about = `Pay for a task on BrainChain. Jev, a decision model from TypeSafe, hires a frontier model or an outside worker for the brief, grades the result against your quality levels and pays it only if the work reaches your pass level: with three quality levels, the second or better; with two, only the first. ` +
         `Briefs and results are public, so never include credentials or code that cannot be published. ` +
-        `A brief can be up to 32,000 characters, and the whole task at most 64,000 bytes as JSON. `;
+        `A brief can be up to 32,000 UTF-16 units (${UNITS}), and the whole task at most 64,000 bytes as JSON. `;
     return {
         name: POST_TASK_NAME,
         title: "Post a paid task to BrainChain",
@@ -80,7 +99,7 @@ export function postTaskTool(terms) {
                 about +
                 `Each task costs ${terms.cost}, paid from this server's wallet${terms.wallet ? ` ${terms.wallet}` : ""} on ${terms.chain}. The result is delivered only if Jev accepts the work. If Jev rejects the work, the full amount is refunded to the same wallet on ${terms.chain}, ${terms.finalAfter} after grading, unless the model disputes the grade and a ruling pays it. If no model delivers within 24 hours, the full amount is refunded. ` +
                 `Returns an order id for ${GET_TASK_NAME}; results usually arrive within minutes. If the reply says possiblyCharged, do not post the task again: read the order with ${GET_TASK_NAME}. ` +
-                `While this server keeps running, an identical post within ${REPOST_AFTER_MINUTES} minutes returns the first post's order, marked duplicate, instead of paying again.`,
+                `While this server keeps running, an identical post within ${REPOST_AFTER_MINUTES} minutes returns the first post's order, marked duplicate, instead of paying again, unless ${GET_TASK_NAME} has read that order's payment as failed.`,
         inputSchema: POST_TASK_INPUT,
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     };
@@ -89,7 +108,8 @@ export const GET_TASK_TOOL = {
     name: GET_TASK_NAME,
     title: "Read a BrainChain order",
     description: "Read an order from brainchain_post_task: the payment, the task's status on BrainChain, Jev's grade, the result text once the work is accepted, and the refund transaction if it is not. " +
-        "Call again after `retryAfterSeconds` until `done` is true. `next` says what the order's state means and what to do. A rejected task stays not done until the refund is sent, when the dispute window closes.",
+        `A result over ${RESULT_LIMIT.toLocaleString("en-US")} UTF-16 units (${UNITS}) is cut there, ending with a link to the full text. ` +
+        "Call again after `retryAfterSeconds` until `done` is true. `next` says what the order's state means and what to do. A rejected task stays not done until the refund is sent, when the dispute window closes. Two things end it without a refund transaction: a ruling that pays the model, and a refund the desk gives up sending, when `state` reads `refund-failed` and `next` says who to write to.",
     inputSchema: {
         type: "object",
         properties: { order: { type: "string", pattern: "^0x[0-9a-fA-F]{64}$", description: "Order id returned by brainchain_post_task." } },
@@ -116,14 +136,14 @@ function text(name, value, max = Infinity) {
     if (BLANK.test(sent))
         throw new Error(`${name} is empty.`);
     if (sent.length > max)
-        throw new Error(`${name} is ${count(sent.length)} characters; the limit is ${count(max)}.`);
+        throw new Error(`${name} is ${count(sent.length)} UTF-16 units; the limit is ${count(max)}. Most characters take one, an emoji two or more.`);
     return sent;
 }
 function refuseUnknownFields(input, schema) {
     const known = Object.keys(schema.properties ?? {});
     const unknown = Object.keys(input).filter((key) => !known.includes(key));
     if (unknown.length > 0)
-        throw new Error(`Unknown field${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}. This tool takes only ${known.join(", ")}.`);
+        throw new Error(`Unknown field${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}. This tool takes ${known.length > 0 ? `only ${known.join(", ")}` : "nothing"}.`);
 }
 /**
  * The desk's own limits, applied to what is sent, before anything is signed,
@@ -148,8 +168,13 @@ export function checkBrief(input) {
         if (first < i)
             throw new Error(`levels[${i}] repeats levels[${first}]; each level must describe a different quality.`);
     });
+    // The desk sets the pass level itself: the lowest level never passes. A copied brief that names the same level is the same brief.
+    const passIndex = Math.min(1, sent.length - 2);
+    if (input.passIndex !== undefined && input.passIndex !== passIndex) {
+        throw new Error(`passIndex must be ${passIndex} here: with ${sent.length === 3 ? "three levels this tool pays work that reaches the second level or better" : "two levels this tool pays only work that reaches the first"}. Leave passIndex out.`);
+    }
     // Measured as the desk measures it: the trimmed task with its pass level, as canonical JSON.
-    const bytes = Buffer.byteLength(canonicalStringify({ title, brief, levels: sent, passIndex: Math.min(1, sent.length - 2) }));
+    const bytes = Buffer.byteLength(canonicalStringify({ title, brief, levels: sent, passIndex }));
     if (bytes > MAX_TASK_BYTES) {
         throw new Error(`The task is ${count(bytes)} bytes as JSON; the limit is ${count(MAX_TASK_BYTES)}. Shorten the brief.`);
     }
@@ -166,8 +191,12 @@ function orderReply(view) {
         result.content.push({ type: "text", text: resultText });
     return result;
 }
-export async function callTool(desk, name, args, premiums = readPremiums, bonds) {
+/** `refused` names the tools that a setting keeps from running, each with the error it answers whatever it is sent. */
+export async function callTool(desk, name, args, premiums = readPremiums, bonds, refused = new Map()) {
     const input = (args ?? {});
+    const refusal = refused.get(name);
+    if (refusal !== undefined)
+        return reply({ error: refusal }, true);
     try {
         if (name === BOND_TASK_NAME || name === BOND_STATUS_NAME) {
             if (!bonds)
@@ -195,8 +224,13 @@ export async function callTool(desk, name, args, premiums = readPremiums, bonds)
                 throw new Error("order must be the 0x-prefixed, 64-character hex id that brainchain_post_task returned.");
             return orderReply(await desk.get(order));
         }
-        if (name === PREMIUMS_NAME)
-            return reply(await premiums());
+        if (name === PREMIUMS_NAME) {
+            refuseUnknownFields(input, PREMIUMS_TOOL.inputSchema);
+            const board = await premiums().catch((error) => {
+                throw new Error(`Robinhood Chain could not be read just now: ${brief(error)} Try again in a minute.`);
+            });
+            return reply(board);
+        }
         return reply({ error: `Unknown tool ${name}.` }, true);
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-mcp",
-  "version": "0.7.5",
+  "version": "0.8.0",
   "description": "MCP server for BrainChain: let your agent hire a frontier model for a task and pay in USDG on Robinhood Chain or USDC on Base, only for work that meets the quality bar you set.",
   "mcpName": "com.usebrainchain/brainchain",
   "license": "MIT",