brainchain-worker 0.18.3 → 0.18.4

package/dist/cli.js

@@ -8,7 +8,7 @@ import { brainchainTransport, createChain, faucetReopens, reason, requireChainId
 import { bond, bondClaim, bondStatus, createBondChain } from "./bond.js";
 import { assetOf, bridge, createBridgeChain } from "./bridge.js";
 import { createExitChain, exit as exitToParent } from "./exit.js";
-import { createSolanaFunding, fundFromSolana, PARENT_ETH_KEEP, solanaKeypair } from "./solana.js";
+import { createSolanaFunding, fundFromSolana, solanaKeypair } from "./solana.js";
 import { claim, createIncome } from "./claim.js";
 import { createProofsChain, createSettlementWatch, MAX_MINT, mint } from "./mint.js";
 import { chainOf, resolveNetwork } from "./network.js";
@@ -18,7 +18,7 @@ import { openStore, readWatched, writeWatched } from "./state.js";
 import { clearKeyFromEnvironment, keyConfigured, keyText, writeKeyFile } from "./key.js";
 import { createCreditChain, credit } from "./credit.js";
 import { appeal, createDisputeChain, dispute } from "./dispute.js";
-import { createReporter, createWatch, createWatchChain, requireWatcher } from "./watch.js";
+import { createReporter, createWatch, createWatchChain, outcome, requireWatcher } from "./watch.js";
 import { createWork, firstProgram, npxUnderSupervisor, programFound, shellCommand, stopLeftover, stopper, unseen, watchStarter } from "./work.js";
 /** How many of the latest decisions a first watch --once checks. */
 const FIRST_RUN_DECISIONS = 10n;
@@ -46,9 +46,13 @@ const COMMAND_USAGE = {
                                             place of the key.`,
     join: `  brainchain-worker join --name <name> --about <text> [--price <USDG>] [--agent-id <id>]
                                             Stake the minimum and apply to take tasks. The name is at
-                                            most 60 characters, the description at most 500. --agent-id
-                                            (mainnet) names the worker's ERC-8004 agent on Robinhood Chain,
-                                            so its BrainChain record is written to that identity.`,
+                                            most 60 characters and the description at most 500, counted
+                                            as UTF-16 units: two or more for an emoji. A worker that is
+                                            allowed or has an application waiting needs neither, and join
+                                            says so if given them: it stakes back up to the minimum.
+                                            --agent-id (mainnet) names the worker's ERC-8004 agent on
+                                            Robinhood Chain, so its BrainChain record is written to that
+                                            identity.`,
     run: `  brainchain-worker run --exec "<command>" [--format prompt|json] [--timeout <minutes>] [--once] [--mint]
                                             Do every task Jev hires the worker for: the command reads the
                                             task on stdin and prints the deliverable on stdout, within
@@ -60,32 +64,49 @@ const COMMAND_USAGE = {
     price: `  brainchain-worker price <USDG>            Change your asking price per task.`,
     mint: `  brainchain-worker mint [--count <n>] [--dry]
                                             Mint a Proof for each paid task waiting for one, up to 10 or
-                                            --count, at 0.001 WETH each on Robinhood Chain. --dry sends nothing.`,
+                                            --count, at 0.001 WETH each on Robinhood Chain. A task stays
+                                            listed until the service has seen its mint, which can take minutes,
+                                            and a mint before then pays for another piece. --dry lists them and
+                                            sends nothing.`,
     claim: `  brainchain-worker claim [--dry]           Claim the ETH due on the worker's Proofs, on Robinhood Chain.
                                             --dry lists what is due and sends nothing.`,
     bond: `  brainchain-worker bond <task> <USDG> [--yes] | bond status <task> | bond claim <task>
-                                            Bond USDG on Shipped behind a task, at least its bounty and 2 USDG:
-                                            the task's Proof releases it less Shipped's 1% fee, and a task that
-                                            is not paid by its deadline pays the bond to the poster. Shows the
-                                            cost and asks before sending; --yes sends without asking. status
-                                            says where the bond stands and claim collects what a settled one
-                                            left the worker. Mainnet.`,
+                                            Bond USDG on Shipped behind a task Jev hired this worker for, at
+                                            least its bounty and 2 USDG. If the task is paid and its Proof
+                                            recorded by the bond's deadline, the task's plus 48 hours, the bond
+                                            comes back less Shipped's 1% fee; if not, it goes to the agent that
+                                            paid BrainChain's desk for the task, or to the poster for a task
+                                            posted on the board directly. Shows the cost and asks before
+                                            sending; --yes sends without asking. status says where the bond
+                                            stands and claim collects what Shipped's registry owes the worker.
+                                            Mainnet.`,
     bridge: `  brainchain-worker bridge --eth <ETH> | --stake <amount> | --bounty <amount> [--dry]
                                             Move ETH for gas, the stake token or the bounty token from Robinhood
                                             Chain to the worker's address on BrainChain; it arrives in about a
-                                            minute. --eth works on both networks, the tokens on mainnet. --dry
-                                            checks the balances and sends nothing.`,
+                                            minute. It takes one of the three at a time. --eth works on both
+                                            networks, the tokens on mainnet. --dry checks the balances and sends
+                                            nothing.`,
     exit: `  brainchain-worker exit [--amount <USDG>] [--to-solana <address>] [--dry]
-                                            Get the worker's USDG on BrainChain back within a minute, not the
-                                            bridge's seven days: the desk pays it on Robinhood Chain less a 0.5%
-                                            fee, or as USDC on Solana with --to-solana (mainnet). Without --amount,
-                                            the whole balance. --dry checks and sends nothing.`,
+                                            On testnet, get the worker's tUSDG on BrainChain back, usually within
+                                            a minute, not the bridge's seven days: the desk pays it on Robinhood
+                                            Chain testnet less a 0.5% fee, at least 0.01 tUSDG. Without --amount,
+                                            the whole balance. --dry checks and sends nothing. Fast exits are off
+                                            on mainnet, where exit says so and sends nothing. --to-solana names a
+                                            Solana wallet for the payout, which Relay can reach from mainnet only,
+                                            so neither network takes it.`,
     fund: `  brainchain-worker fund --from-solana --usdc <amount> [--stake] [--gas-usdc <amount>] [--dry]
-                                            Fund the worker from a Solana wallet: Relay turns its USDC into ETH
-                                            for gas (2 USDC by default) and, with --stake, the rest into the stake
-                                            token, on Robinhood Chain, and bridge moves both to BrainChain. Signed
-                                            with BRAINCHAIN_SOLANA_KEY or BRAINCHAIN_SOLANA_KEY_FILE; the wallet
-                                            needs about 0.002 SOL for fees. Mainnet.`,
+                                            Fund the worker from a Solana wallet. Relay turns --gas-usdc of its
+                                            USDC (2 by default, and never more than --usdc) into ETH on Robinhood
+                                            Chain. With --stake, the rest of --usdc becomes the stake token there;
+                                            without it, the rest stays on Solana. Then bridge moves on to BrainChain
+                                            only what this run brought, less the ETH a token deposit pays, leaving
+                                            a little for gas; what the wallet already held stays. A quote that would
+                                            cost more than 3% on the ETH or 5% on the stake token (or 0.50 USD on a
+                                            small move), or that asks to sign anything but this USDC's deposit into
+                                            Relay's depository, stops the command before anything is signed. Signed
+                                            with BRAINCHAIN_SOLANA_KEY or BRAINCHAIN_SOLANA_KEY_FILE, one or the
+                                            other; the wallet needs about 0.002 SOL for fees. --dry checks and sends
+                                            nothing. Mainnet.`,
     propose: `  brainchain-worker propose --target board|executor|registry --call <function> --args '<JSON array>'
                             --title <text> --rationale <text> [--current <text>] [--proposed <text>] [--dry]
                                             Bond the stake token and propose a change to BrainChain for Jev to
@@ -94,13 +115,18 @@ const COMMAND_USAGE = {
     proposal: `  brainchain-worker proposal <id>           Where a proposal stands: waiting, adopted and when it runs, or kept.`,
     watch: `  brainchain-worker watch [--veto] [--once]
                                             Watch the chain: judge every queued change against the constitution
-                                            and re-verify every new decision, reporting what disagrees. With the
-                                            worker's key set, each round is reported to the service toward the
-                                            worker's watchtower mark. --veto vetoes a change that crosses a floor
-                                            through the guardian gate, when the worker's key is the gate's
-                                            watcher. --once reads one round, checks the decisions added since
-                                            the last --once (the latest 10 on the first) and exits 1 on a finding
-                                            or a decision it could not check.`,
+                                            and re-verify every new decision, reporting what disagrees. A call the
+                                            monitor does not know counts as breaking a floor; one with no floor,
+                                            such as moving house treasury funds, is listed as that. A decision
+                                            served without its work is listed as withheld, with the hash checks
+                                            that did not run. A record that cannot be read holds the place until a
+                                            day after its decision's block time; past that it is a finding, reported
+                                            once, and the place moves on. With the worker's key set, each round is
+                                            reported to the service toward the worker's watchtower mark. --veto vetoes
+                                            a change that crosses a floor through the guardian gate, when the worker's
+                                            key is the gate's watcher. --once reads one round, checks the decisions
+                                            added since the last --once (the latest 10 on the first) and exits 1
+                                            on a finding or when a decision could not be checked or reported.`,
     credit: `  brainchain-worker credit --agent-id <id> [--premium <bps>]
                                             Ask BrainChain to back a credit line for the worker's ERC-8004 agent
                                             on Priors (priors.trade): signs Priors' consent with the agent owner's
@@ -133,12 +159,13 @@ Environment:
   BRAINCHAIN_RPC_URL      Overrides the network's RPC.
   BRAINCHAIN_SOLANA_KEY   For fund --from-solana: the Solana wallet's secret key, base58.
   BRAINCHAIN_SOLANA_KEY_FILE
-                          Or a Solana CLI keypair file holding it.
+                          Or a Solana CLI keypair file holding it, one or the other.
   BRAINCHAIN_SOLANA_RPC   Overrides the Solana RPC (https://api.mainnet-beta.solana.com).
   BRAINCHAIN_SERVICE_URL  Overrides the BrainChain service that keeps results: https, or http on
                           localhost or 127.0.0.1.
 
 The command sees the worker's environment without any BRAINCHAIN_ variable, plus BRAINCHAIN_TASK_ID.
+run restarts itself in place at start on Node.js 22.15 or later, so its own environment holds no key either.
 It runs as your user, so it can reach what your user can: see "Your command" in the README.
 Unfinished work is kept in ~/.config/brainchain-worker/<address>.<network>.json across restarts,
 and one run at a time works for each address on each network.
@@ -260,19 +287,15 @@ async function needGas(chain, network) {
 export async function join(chain, network, values) {
     const name = values.get("name")?.trim() ?? "";
     const about = values.get("about")?.trim() ?? "";
-    if (!name)
-        throw new UsageError("--name is required, up to 60 characters");
+    // What the brain keeps, in UTF-16 units as a JavaScript string counts them: one for nearly all text, two or more for an emoji.
     if (name.length > 60)
-        throw new UsageError("--name is at most 60 characters");
+        throw new UsageError("--name is at most 60 characters, counted as UTF-16 units: one for nearly all text, two or more for an emoji");
     // A name that hides characters or turns text around can read as another, Jev's included.
     const nameHides = unseen(name);
     if (nameHides)
         throw new UsageError(`--name must be one line with no invisible or direction-changing characters, and it holds ${nameHides}`);
-    if (!about) {
-        throw new UsageError("--about is required: say what work your agent does in up to 500 characters, since Jev reads it to decide and refuses an empty application");
-    }
     if (about.length > 500)
-        throw new UsageError("--about is at most 500 characters");
+        throw new UsageError("--about is at most 500 characters, counted as UTF-16 units: one for nearly all text, two or more for an emoji");
     // A description may run over several lines.
     const aboutHides = unseen(about.replace(/[\t\n]/g, " "));
     if (aboutHides)
@@ -286,6 +309,21 @@ export async function join(chain, network, values) {
     const requested = values.has("price") ? price(values.get("price")) : undefined;
     const standing = await snapshot(chain);
     const { allowed, w, change, pending, open, applying, toStake } = standing;
+    // Only an application carries a name and a description, so a worker already allowed or waiting needs neither.
+    if (applying) {
+        if (!name)
+            throw new UsageError("--name is required, up to 60 characters");
+        if (!about)
+            throw new UsageError("--about is required: say what work your agent does in up to 500 characters, since Jev reads it to decide and refuses an empty application");
+        if (await chain.applicationVetoed())
+            throw new Error("The guardian vetoed setWorkerAllowed on the task board, so the executor does not queue an application until the admin reopens that function. Nothing was sent.");
+        const taken = await chain.openApplication();
+        if (taken > 0n)
+            throw new Error(`Proposal ${taken} already asks to allow this worker and is still open, and the contract takes one at a time. Nothing was sent. Follow it with \`npx brainchain-worker proposal ${taken}\`.`);
+    }
+    else if (name || about) {
+        console.log("This worker is past its application, so --name and --about are not used.");
+    }
     // The agent id travels in the application, and Jev keeps the profile it decided on.
     if (agentId !== undefined) {
         if (allowed || (change && pending) || open) {
@@ -657,6 +695,8 @@ export async function main(argv) {
         }
         if (!usdc)
             throw new UsageError("--usdc is required: how much USDC on Solana to use, such as --usdc 5");
+        if (gasUsdc && !switches.has("stake") && parseUnits(gasUsdc, 6) > parseUnits(usdc, 6))
+            throw new UsageError(`--gas-usdc ${gasUsdc} is more than --usdc ${usdc}, the most this command may spend`);
         if (network.id !== "mainnet" || !network.bridge)
             throw new Error("fund --from-solana is mainnet only: Relay connects Solana with Robinhood Chain mainnet, not the testnets");
         const worker = signer();
@@ -671,17 +711,9 @@ export async function main(argv) {
             ...(network.bridge.tokens?.stake ? { stakeToken: network.bridge.tokens.stake } : {}),
             dry: switches.has("dry"),
             log: console.log,
-            async bridgeOn(asset) {
-                if (asset === "eth") {
-                    const eth = await bridgeChain.parentEth();
-                    if (eth <= PARENT_ETH_KEEP)
-                        return console.log("Not enough ETH to send on to BrainChain beyond what stays for gas on the parent chain.");
-                    return bridge(network, bridgeChain, { asset: "eth", amount: formatEther(eth - PARENT_ETH_KEEP), dry: false, log: console.log });
-                }
-                const held = await bridgeChain.tokenBalance("stake");
-                const { decimals } = assetOf(network, "stake");
-                return bridge(network, bridgeChain, { asset: "stake", amount: formatUnits(held, decimals), dry: false, log: console.log });
-            },
+            parentEth: () => bridgeChain.parentEth(),
+            parentStake: () => bridgeChain.tokenBalance("stake"),
+            bridgeOn: (asset, amount) => bridge(network, bridgeChain, { asset, amount: formatUnits(amount, assetOf(network, asset).decimals), dry: false, log: console.log }),
         });
     }
     if (command === "credit") {
@@ -711,10 +743,7 @@ export async function main(argv) {
                 set: { key: "active", release: "", fromBlock: Number(network.fromBlock), board: taskBoard, log, executor },
                 briefs: new Map(),
             }, id);
-            const findings = report.checks.filter((c) => c.status === "fail" || c.status === "error").map((c) => `${c.name}: ${c.message}`);
-            // A verified decision is reported with the record it was checked against, fetched again as the service serves it.
-            const record = findings.length === 0 && keyed && report.payloadURI ? await fetchRecord(report.payloadURI).catch(() => undefined) : undefined;
-            return { findings, ...(record ? { record } : {}) };
+            return outcome(report, keyed ? { refetch: fetchRecord } : {});
         };
         const chain = createWatchChain(network, account);
         const watch = createWatch({
@@ -747,9 +776,8 @@ export async function main(argv) {
         const id = positional[0];
         if (id === undefined || !/^\d{1,18}$/.test(id) || id === "0")
             throw new UsageError("Usage: brainchain-worker proposal <id>, such as proposal 2");
-        // Reading a proposal needs no key, so any address stands in for the signer.
-        const reader = keyConfigured() ? signer().account : privateKeyToAccount(generatePrivateKey());
-        return proposal(network, createProposals(network, reader), BigInt(id), console.log);
+        // Reading a proposal needs no key, so any address stands in for the signer, and a key that is set is never read.
+        return proposal(network, createProposals(network, privateKeyToAccount(generatePrivateKey())), BigInt(id), console.log);
     }
     const worker = signer();
     if (command === "dispute" || command === "appeal") {

package/dist/credit.js

@@ -1,4 +1,4 @@
-import { createPublicClient, http, parseAbi } from "viem";
+import { BaseError, ContractFunctionRevertedError, createPublicClient, http, parseAbi } from "viem";
 import { reason } from "./chain.js";
 import { parentChainOf } from "./network.js";
 export const CONSENT_TYPES = {
@@ -47,6 +47,9 @@ export async function credit(network, chain, options) {
         owner = await chain.ownerOf(agentId);
     }
     catch (error) {
+        // The registry reverts ownerOf for an id it never minted; anything else says nothing about the agent.
+        if (error instanceof BaseError && error.walk((e) => e instanceof ContractFunctionRevertedError))
+            throw new Error(`There is no ERC-8004 agent ${agentId} on Robinhood Chain.`);
         throw new Error(`ERC-8004 agent ${agentId} could not be read on Robinhood Chain: ${reason(error)}`);
     }
     if (owner.toLowerCase() !== chain.account.toLowerCase()) {

package/dist/exit.js

@@ -1,16 +1,32 @@
 // `exit`: the worker's USDG on BrainChain paid back within a minute instead of the bridge's seven days. The desk pays
 // it on Robinhood Chain, or, with `--to-solana`, as USDC on Solana through Relay: the transfer to the desk carries the
-// Solana address after its arguments, so nothing else is signed and nothing is needed on Robinhood Chain.
+// Solana address after its arguments, so nothing else is signed and nothing is needed on Robinhood Chain. The token and
+// the desk the service names are checked against this release before anything is signed.
+import { PublicKey } from "@solana/web3.js";
 import bs58 from "bs58";
-import { createPublicClient, createWalletClient, encodeFunctionData, erc20Abi, formatUnits, http, parseUnits } from "viem";
-import { RECEIPT_MS } from "./chain.js";
+import { createPublicClient, createWalletClient, encodeFunctionData, erc20Abi, formatUnits, http, isAddress, parseUnits } from "viem";
+import { RECEIPT_MS, reason } from "./chain.js";
 import { chainOf } from "./network.js";
-/** A Solana address: 32 bytes in base58. */
+/**
+ * Keys no one can spend USDC from. Program ids are often on the curve, so the
+ * curve alone does not catch them: the all-zero address, which the desk also
+ * reads as no destination, the token programs, USDC's mint and Relay's depository.
+ */
+const NOT_WALLETS = new Set([
+    "11111111111111111111111111111111",
+    "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
+    "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb",
+    "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
+    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+    "99vQwtBwYtrqqD9YSXbdum3KBdxPAVxYTaQ3cfnJSrN2",
+]);
+/** A Solana address a wallet can spend from: 32 bytes in base58, on the ed25519 curve. A program-derived address is off it, and USDC sent there is stranded. */
 export function isSolanaAddress(value) {
-    if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value))
+    if (!/^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(value) || NOT_WALLETS.has(value))
         return false;
     try {
-        return bs58.decode(value).length === 32;
+        const bytes = bs58.decode(value);
+        return bytes.length === 32 && PublicKey.isOnCurve(bytes);
     }
     catch {
         return false;
@@ -27,13 +43,39 @@ export function exitFee(amount, terms) {
     const fee = proportional > floor ? proportional : floor;
     return fee > amount ? amount : fee;
 }
+const units = (value) => typeof value === "string" && /^\d{1,30}$/.test(value);
+/** What the service answers for its exit terms, refused here when it is not the shape the rest of `exit` reads. */
 export async function exitTerms(service, fetchImpl = fetch) {
-    const response = await fetchImpl(`${service}/exits`, { signal: AbortSignal.timeout(20_000) });
+    const host = new URL(service).host;
+    const response = await fetchImpl(`${service}/exits`, { signal: AbortSignal.timeout(20_000) }).catch(() => {
+        throw new Error(`Could not reach the BrainChain service at ${host} for the exit terms. Nothing was sent.`);
+    });
     if (response.status === 404)
         throw new Error("Fast exits are off on this network");
     if (!response.ok)
-        throw new Error(`${service}/exits answered ${response.status}`);
-    return (await response.json());
+        throw new Error(`The BrainChain service at ${host} answered ${response.status} when asked for the exit terms. Nothing was sent.`);
+    const terms = (await response.json().catch(() => undefined));
+    const readable = typeof terms?.desk === "string" &&
+        isAddress(terms.desk, { strict: false }) &&
+        typeof terms.token === "string" &&
+        isAddress(terms.token, { strict: false }) &&
+        Number.isInteger(terms.feeBps) &&
+        terms.feeBps >= 0 &&
+        [terms.minFeeUnits, terms.minUnits, terms.maxUnits].every(units);
+    if (!readable)
+        throw new Error(`The BrainChain service at ${host} named the exit terms in a form exit cannot read. Nothing was sent.`);
+    return terms;
+}
+/** Why the terms cannot be signed for: a transfer goes to whatever token and desk they name, and only this release says which those are. */
+export function termsProblem(network, terms) {
+    const host = new URL(network.service).host;
+    if (terms.token.toLowerCase() !== network.contracts.bountyToken.toLowerCase()) {
+        return `The BrainChain service at ${host} names the token ${terms.token} for an exit, and ${network.name}'s ${network.bountySymbol} is ${network.contracts.bountyToken}. Nothing was sent.`;
+    }
+    if (terms.desk.toLowerCase() !== network.exitDesk.toLowerCase()) {
+        return `The BrainChain service at ${host} names the desk ${terms.desk}, and this release of brainchain-worker pays only ${network.exitDesk}. Nothing was sent.`;
+    }
+    return undefined;
 }
 export async function exitRecord(service, tx, fetchImpl = fetch) {
     const response = await fetchImpl(`${service}/exits/${tx}`, { signal: AbortSignal.timeout(20_000) });
@@ -43,15 +85,22 @@ export async function exitRecord(service, tx, fetchImpl = fetch) {
         throw new Error(`${service}/exits answered ${response.status}`);
     return (await response.json()).exits[0];
 }
-export function createExitChain(network, account) {
-    const read = createPublicClient({ chain: chainOf(network), transport: http(network.rpc, { timeout: 20_000 }) });
+export function createExitChain(network, account, receiptMs = RECEIPT_MS) {
+    const read = createPublicClient({ chain: chainOf(network), transport: http(network.rpc, { timeout: 20_000 }), pollingInterval: 1_000 });
     const wallet = createWalletClient({ account, chain: chainOf(network), transport: http(network.rpc, { timeout: 20_000 }) });
     return {
         account: account.address,
         bountyBalance: (token) => read.readContract({ address: token, abi: erc20Abi, functionName: "balanceOf", args: [account.address] }),
+        async unmined() {
+            const [pending, latest] = await Promise.all([read.getTransactionCount({ address: account.address, blockTag: "pending" }), read.getTransactionCount({ address: account.address })]);
+            return pending - latest;
+        },
         async sendToDesk(token, desk, amount, solana) {
             const hash = await wallet.sendTransaction({ to: token, data: exitCalldata(desk, amount, solana) });
-            const receipt = await read.waitForTransactionReceipt({ hash, timeout: RECEIPT_MS });
+            // Sent is not lost: the transfer can still land, so another run would pay the desk twice.
+            const receipt = await read.waitForTransactionReceipt({ hash, timeout: receiptMs }).catch((error) => {
+                throw new Error(`The transfer to the desk was sent (${hash}) and could not be confirmed (${reason(error)}). Follow it at ${network.service}/exits/${hash} before running exit again: another run sends another transfer.`);
+            });
             if (receipt.status !== "success")
                 throw new Error(`the transfer to the desk reverted (${hash})`);
             return hash;
@@ -64,11 +113,14 @@ export async function exit(network, chain, options) {
     const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     if (options.toSolana !== undefined) {
         if (!isSolanaAddress(options.toSolana))
-            throw new Error(`"${options.toSolana}" is not a Solana address`);
+            throw new Error(`"${options.toSolana}" is not the address of a Solana wallet, so USDC sent there could not be spent`);
         if (network.id !== "mainnet")
             throw new Error("--to-solana is mainnet only: Relay connects Solana with Robinhood Chain mainnet, not the testnets");
     }
     const terms = await exitTerms(network.service, fetchImpl);
+    const refused = termsProblem(network, terms);
+    if (refused)
+        throw new Error(refused);
     const balance = await chain.bountyBalance(terms.token);
     const amount = options.amount === undefined ? balance : parseUnits(options.amount, 6);
     const min = BigInt(terms.minUnits);
@@ -82,34 +134,45 @@ export async function exit(network, chain, options) {
     if (amount < min)
         throw new Error(`An exit is at least ${show(min)}`);
     if (amount > max)
-        throw new Error(`An exit is at most ${show(max)}; send the rest in another exit`);
+        throw new Error(`An exit is at most ${show(max)}, and nothing was sent. Give --amount up to that, and send the rest in another exit.`);
     const fee = exitFee(amount, terms);
     const net = amount - fee;
-    log(`Exit ${show(amount)} from ${network.name}: ${show(net)} arrives on the parent chain (chain ${terms.payoutChainId}) after a ${show(fee)} fee.`);
-    if (options.toSolana !== undefined)
-        log(`Paid as USDC on Solana to ${options.toSolana}, less Relay's own fee, unless the move would cost more than 3% (or 0.50 USD); then it is paid on the parent chain.`);
+    const paid = options.toSolana === undefined
+        ? `${show(net)} arrives on the parent chain (chain ${terms.payoutChainId}) after a ${show(fee)} fee.`
+        : `${show(net)} after a ${show(fee)} fee is paid as USDC on Solana to ${options.toSolana}, less Relay's own fee. The desk prices that move once the transfer arrives; one that would cost more than 3% (or 0.50 USD) is paid in ${symbol} on the parent chain (chain ${terms.payoutChainId}) instead.`;
+    log(`Exit ${show(amount)} from ${network.name}: ${paid}`);
     if (dry) {
         log("Dry run, nothing sent.");
         return;
     }
+    const unmined = await chain.unmined();
+    if (unmined > 0)
+        throw new Error(`This wallet has a transaction on ${network.name} that is not mined yet, which may be an earlier exit, and another run would send another transfer. Nothing was sent; run exit again once it is mined.`);
     const tx = await chain.sendToDesk(terms.token, terms.desk, amount, options.toSolana);
+    const follow = `${network.service}/exits/${tx}`;
     log(`Sent to the desk on ${network.name} (${tx}). Waiting for the payout, usually under a minute.`);
     const end = Date.now() + (options.waitMs ?? 1_800_000);
     let last = "";
     let record;
     for (;;) {
         record = await exitRecord(network.service, tx, fetchImpl).catch(() => undefined);
-        if (record?.state === "paid" || record?.state === "returned")
+        if (record?.state === "paid" || record?.state === "returned" || record?.state === "held")
             break;
         if (record?.reason && record.reason !== last)
             log(`Waiting: ${record.reason}.`);
         last = record?.reason ?? last;
         if (Date.now() > end) {
-            log(`Still waiting after ${Math.round((options.waitMs ?? 1_800_000) / 60_000)} minutes. The desk pays it or sends it back within a day; follow it at ${network.service}/exits/${tx}.`);
+            const within = options.toSolana === undefined ? "The desk pays it or sends it back within a day" : "Within a day the desk pays it or sends it back, or holds it for a person if Relay has not settled the move";
+            log(`Still waiting after ${Math.round((options.waitMs ?? 1_800_000) / 60_000)} minutes. ${within}; follow it at ${follow}.`);
             return;
         }
         await sleep(options.pollMs ?? 10_000);
     }
+    if (record.state === "held") {
+        log(`The desk holds this exit for a person: ${record.reason ?? "no reason given"}. Nothing more is sent for it until it is settled; follow it at ${follow}.`);
+        process.exitCode = 1;
+        return;
+    }
     if (record.state === "returned") {
         log(`The desk sent it back on ${network.name}: ${record.reason ?? "no reason given"} (${record.returnTx}).`);
         process.exitCode = 1;

package/dist/key.js

@@ -6,7 +6,7 @@ import { stateDir } from "./state.js";
 /** Names the file a run passes its key through when it restarts itself without the key in its environment. */
 const HANDOFF = "BRAINCHAIN_WORKER_KEY_HANDOFF";
 const HANDOFF_NAME = /^brainchain-worker-key-[0-9a-f]{32}$/;
-const expandHome = (path) => (path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(1)) : path);
+export const expandHome = (path) => (path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(1)) : path);
 /** Whether the environment names a key, without reading it: a key file can be a pipe, which reads only once. */
 export const keyConfigured = (env = process.env) => Boolean(env[HANDOFF] || env.BRAINCHAIN_WORKER_KEY?.trim() || env.BRAINCHAIN_WORKER_KEY_FILE?.trim());
 /** What is wrong with a key file's text, in words that never repeat any of it. */
@@ -85,19 +85,33 @@ function handoffDir() {
         return stateDir();
     }
 }
+/** A variable that holds a key or says where one is: the worker's and the Solana wallet's, which `run` never uses. */
+const KEY_VARIABLE = /^BRAINCHAIN_(WORKER|SOLANA)_KEY(_FILE)?$/;
+/** A key file that is a pipe has been read and holds nothing, so its name can stay: a restart would put a key piped in to stay out of files in one for a moment. */
+function namesOnlyAPipe(names, env) {
+    if (names.length !== 1 || names[0] !== "BRAINCHAIN_WORKER_KEY_FILE")
+        return false;
+    try {
+        return !statSync(expandHome(env.BRAINCHAIN_WORKER_KEY_FILE.trim())).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 /**
- * Restarts this process in place without BRAINCHAIN_WORKER_KEY in its
- * environment. Deleting the variable would not do: `ps eww` and /proc read the
- * block the process started with, and a command run by `run` can reach both.
- * The pid, the output and the supervisor's view all stay as they were. Returns
- * when there is nothing to clear, or when it could not be cleared.
+ * Restarts this process in place without any key variable in its environment.
+ * Deleting them would not do: `ps eww` and /proc read the block the process
+ * started with, and a command run by `run` can reach both. The pid, the output
+ * and the supervisor's view all stay as they were. Returns when there is
+ * nothing to clear, or when it could not be cleared.
  */
 export function clearKeyFromEnvironment(key, warn, env = process.env, execve = process.execve) {
-    if (env.BRAINCHAIN_WORKER_KEY === undefined)
+    const names = Object.keys(env).filter((name) => KEY_VARIABLE.test(name));
+    if (names.length === 0 || namesOnlyAPipe(names, env))
         return;
     if (typeof execve !== "function")
-        return warn(`warning: Node.js ${process.version} cannot clear the key from this process's environment; Node.js 22.15 or later can`);
-    const { BRAINCHAIN_WORKER_KEY: _, ...rest } = env;
+        return warn(`warning: Node.js ${process.version} cannot clear the key variables from this process's environment; Node.js 22.15 or later can`);
+    const rest = Object.fromEntries(Object.entries(env).filter(([name]) => !KEY_VARIABLE.test(name)));
     let file;
     try {
         file = join(handoffDir(), `brainchain-worker-key-${randomBytes(16).toString("hex")}`);
@@ -107,6 +121,6 @@ export function clearKeyFromEnvironment(key, warn, env = process.env, execve = p
     catch (error) {
         if (file !== undefined)
             rmSync(file, { force: true });
-        warn(`warning: could not clear the key from this process's environment (${error.message})`);
+        warn(`warning: could not clear the key variables from this process's environment (${error.message})`);
     }
 }

package/dist/mint.js

@@ -159,7 +159,7 @@ export async function mint(network, chain, options) {
         return log(`The BrainChain service lists no paid task of ${chain.account} waiting for a Proof, so there is nothing to mint.`);
     const batch = listed.slice(0, Math.min(options.count ?? MAX_MINT, MAX_MINT));
     const left = listed.length - batch.length;
-    const rest = left > 0 ? ` ${left} more paid task${left === 1 ? " waits" : "s wait"} for a Proof: run mint again.` : "";
+    const rest = left > 0 ? ` ${left} more paid task${left === 1 ? " waits" : "s wait"} for a Proof, for a later mint.` : "";
     const funds = await afford(proofs, chain, batch.length, { dry: options.dry, claiming: () => log("Claiming test WETH from the faucet..."), now: options.now ?? wall });
     const each = `${formatEther(funds.price)} WETH each plus gas`;
     if (options.dry) {
@@ -180,6 +180,8 @@ export async function mint(network, chain, options) {
     }
     if (rest)
         log(rest.trim());
+    // The service scans in rounds and caches the list, so it still shows these tasks for a while.
+    log("`mint --dry` lists these tasks until the service has seen these mints, which can take minutes. A mint before then, here or by `run --mint`, pays for another piece.");
 }
 /**
  * What `run` does once a task is delivered: it watches the task until it

package/dist/network.js

@@ -37,6 +37,7 @@ export const TESTNET = {
         router: "0x1BBe71Dd3af85309A5c7Ab00B190F38f34Fe3569",
         gas: "Get Robinhood Chain testnet ETH at https://faucet.testnet.chain.robinhood.com",
     },
+    exitDesk: "0xf848984c8A0D9E49Cc9C97380C62b34C6f3b97D1",
     contracts: {
         taskBoard: "0x7A7cC5D35A642CCc268C7B263fF800bc7eBD52A4",
         staking: "0x6aFC3EFB49CF9b14C2F7c6C4f6C0bb3eF0125e2b",
@@ -97,6 +98,7 @@ export const MAINNET = {
         gas: "Send it a little ETH on Robinhood Chain",
         tokens: { stake: "0xC80333bf7f4078e14Ce5b6e223aF607aDcA44418", bounty: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168" },
     },
+    exitDesk: "0xafB0C4Ef895D4895040cdC6435B96D3EE8350c6E",
     contracts: {
         taskBoard: MAINNET_TASK_BOARD,
         staking: MAINNET_WORKER_STAKING,