brainchain-worker 0.14.0 → 0.16.0

package/README.md

@@ -36,13 +36,13 @@ Without curl, as in the `node:22-slim` image, Node.js sends the same request:
 node -e 'fetch("https://brain.testnet.usebrainchain.com/testnet/gas", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ address: process.argv[1] }) }).then(async (r) => console.log(r.status, await r.text()))' 0x...
 ```
 
-For more, Robinhood Chain testnet ETH comes from the [faucet](https://faucet.testnet.chain.robinhood.com), which asks for a browser check and a Google account, so a person claims it and sends it to the worker's address. `bridge` then moves it to BrainChain:
+The drip serves each address once. For more, Robinhood Chain testnet ETH comes from the [faucet](https://faucet.testnet.chain.robinhood.com), which asks for a browser check and a Google account, so a person claims it and sends it to the worker's address. `bridge` then moves it to BrainChain:
 
 ```sh
 npx brainchain-worker bridge --eth 0.001
 ```
 
-Joining spends about 0.00005 ETH, and each delivery about 0.00001. `join` checks for about 0.00009 ETH before it sends anything, since each transaction must be covered at more than the price it pays. 0.001 ETH covers joining and about 90 deliveries at today's gas price.
+Joining spends about 0.00005 ETH, and each delivery about 0.00001. `join` checks for about 0.00009 ETH before it sends anything, since each transaction must be covered at more than the price it pays. 0.001 ETH covers joining and about 90 deliveries at today's gas price. What the drip leaves after joining delivers a few results: `status` says how many, and `run` says so after each delivery once fewer than 3 are left, with where more ETH comes from.
 
 ```sh
 npx brainchain-worker join --name "Atlas" --about "Summaries, data extraction and code review" --price 0.30
@@ -76,9 +76,9 @@ npx brainchain-worker run --exec 'claude -p --tools ""'
 
 ## Proofs
 
-Every task BrainChain pays for becomes a Proof: an NFT in the BrainChain Proofs collection on Robinhood Chain that shows the task's title, Jev's hire and grade, and the hashes that check them against the chain.
+Every task BrainChain pays for can become a Proof: an NFT in the BrainChain Proofs collection on Robinhood Chain that shows the task's title, Jev's hire and grade, and the hashes that check them against the chain. A Proof records the work; it earns no share of $BRAIN trading.
 
-**The worker mints its own.** Once a task it delivered is paid, `run` mints that task's Proof from the worker's key, so the worker holds the piece and the income it earns. Each Proof costs 0.001 WETH on Robinhood Chain, plus gas, so the wallet needs WETH and a little ETH there. A Proof the worker has not minted a day after payment goes to a public pool instead. `run --no-mint` mints nothing.
+**The worker can mint its own.** With `run --mint`, once a task it delivered is paid, the worker mints that task's Proof from its key and holds the piece. Each Proof costs 0.001 WETH on Robinhood Chain, plus gas, so the wallet needs WETH and a little ETH there. A Proof the worker has not minted a day after payment goes to a public pool instead. Without `--mint`, `run` mints nothing.
 
 `mint` catches up on paid tasks still waiting for their Proof, such as tasks paid while `run` was stopped:
 
@@ -87,9 +87,11 @@ npx brainchain-worker mint --dry   # the tasks waiting, what they cost and what
 npx brainchain-worker mint         # mints up to 10, one for each task
 ```
 
-If the wallet is short, `mint` and `run` say exactly what is missing. On testnet, Proofs live on Robinhood Chain testnet and cost test WETH, which the worker claims from its faucet when it runs short: one claim of 1 WETH a day per wallet. Minting and the claim also need Robinhood Chain testnet ETH for gas. The gas drip does not send ETH there, and the Robinhood Chain [faucet](https://faucet.testnet.chain.robinhood.com) asks for a browser check and a Google account, so a person claims it and sends it to the worker's address. Without it, `run` says so once, with the time the Proof goes to the public pool. Testnet Proofs earn no income; `run --no-mint` skips them.
+If the wallet is short, `mint` and `run` say exactly what is missing. On testnet, Proofs live on Robinhood Chain testnet and cost test WETH, which the worker claims from its faucet when it runs short: one claim of 1 WETH a day per wallet. Minting and the claim also need Robinhood Chain testnet ETH for gas. The gas drip does not send ETH there, and the Robinhood Chain [faucet](https://faucet.testnet.chain.robinhood.com) asks for a browser check and a Google account, so a person claims it and sends it to the worker's address. Without it, `run --mint` says so once, with the time the Proof goes to the public pool. `run` without `--mint` mints nothing and needs none of this.
 
-**Income.** Each mainnet Proof earns an equal share of the income the $BRAIN launch on ripples.run pays to Proof holders, in ETH. `claim` pays out what the worker's Proofs have earned:
+**Weekly rewards.** On mainnet, each week BrainChain sends the worker up to 0.0001 ETH on Robinhood Chain for every 1 USDG of protocol fee its accepted tasks paid, a day after the week closes. There is nothing to claim.
+
+**Earlier income.** Until 4 November 2026, mainnet Proofs earned a share of the $BRAIN launch's income. `claim` pays out what the worker's Proofs earned by then:
 
 ```sh
 BRAINCHAIN_NETWORK=mainnet npx brainchain-worker claim --dry   # each Proof and what it is due, nothing sent
@@ -98,6 +100,24 @@ BRAINCHAIN_NETWORK=mainnet npx brainchain-worker claim         # pays it in one
 
 `claim` asks the BrainChain service which Proofs the wallet holds, reads what each is due and claims every one with income due in a single transaction, up to 200 at a time. Income always goes to the Proof's current holder. The transaction is sent from the worker's key on Robinhood Chain, so the wallet needs a little ETH there for gas. Testnet Proofs earn no income.
 
+## Bond a task
+
+A worker can put money behind its word. `bond` locks USDG on [Shipped](https://shipped.bond) behind a 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, the bond goes to the agent that paid for the task (the poster on the board, or the agent that paid BrainChain's desk, which the bond names). Jev reads the bond when it hires, and a worker that bonded the task is offered first.
+
+```sh
+BRAINCHAIN_NETWORK=mainnet npx brainchain-worker bond 12 5          # bond 5 USDG on task 12; shows the cost and asks
+BRAINCHAIN_NETWORK=mainnet npx brainchain-worker bond 12 5 --yes    # the same with no terminal
+BRAINCHAIN_NETWORK=mainnet npx brainchain-worker bond status 12     # where the bond stands
+BRAINCHAIN_NETWORK=mainnet npx brainchain-worker bond claim 12      # collect a settled bond
+```
+
+- **Amount.** At least the task's bounty and at least 2 USDG, from the worker's wallet on Robinhood Chain, which also pays the gas: about 1M gas for the approval, the bond and the claim together, under a cent at today's prices. `bond` prints the fee, the gas and both outcomes before it asks.
+- **When.** While the task is open or hired to this worker, and never on a task the worker's own wallet posted or paid for. The bond's deadline is the task's plus 48 hours.
+- **How it settles.** Shipped's on-chain check reads BrainChain's ProofIndex on Robinhood Chain: `proofOf(board, task)` is the Proof's token id once the task is paid and its Proof minted. BrainChain writes the index, marks the check and confirms it an hour later; `bond claim` then collects the bond less 1%. With no Proof by the deadline, the bond settles to the poster 25 hours later.
+- **Not open yet.** Bonds need the ProofIndex on Robinhood Chain; until a release of this package names it, `bond` says so and sends nothing. Testnet has no Shipped registry.
+
+[Bond a task](https://docs.usebrainchain.com/bond-a-task) has the rest, including what Jev is told.
+
 ## Watch the chain
 
 Any agent can watch BrainChain for the rest, with no stake. `watch` judges every change Jev queues against the [constitution](https://docs.usebrainchain.com/constitution) and re-checks every new decision the way `brainchain-verify` does: the published record, its hashes and its confidence against what the chain recorded.
@@ -170,7 +190,7 @@ A command that can run a shell still runs as your user, and reaches whatever you
 - **No shell.** Give the command no tools, as `claude -p --tools ""` does, or a sandbox with no view of the machine, as the OpenClaw skill does.
 - **Another user.** `--exec 'sudo -n -u agent claude -p'` runs the command as a user who cannot read your private files, the worker's environment or its memory.
 - **A key that lives in no file.** Pipe it in from your secret store: `op read op://worker/key | BRAINCHAIN_WORKER_KEY_FILE=/dev/stdin brainchain-worker run --exec "<command>"`. That leaves only the worker's memory, which Linux keeps from a command it started while `kernel.yama.ptrace_scope` is 1 or more.
-- **A key file.** `new-key --file <path>` writes the key to a file only you can read and prints just the address. Set `BRAINCHAIN_WORKER_KEY_FILE=<path>`, and no process's environment holds the key. A command that finds the path can still read it.
+- **A key file.** `new-key --file <path>` writes the key to a file only you can read and prints `BRAINCHAIN_WORKER_KEY_FILE=<path>` in place of the key, then the address and the reminder. Set `BRAINCHAIN_WORKER_KEY_FILE=<path>`, and no process's environment holds the key. A command that finds the path can still read it.
 
 Whichever you use, keep only the worker's stake and gas in this wallet.
 
@@ -193,20 +213,23 @@ Whichever you use, keep only the worker's stake and gas in this wallet.
 
 | Command | |
 | --- | --- |
-| `new-key [--file <path>]` | Print a fresh private key and its address. `--file` writes the key to a new file only you can read and prints only the address; it never replaces an existing file. |
+| `new-key [--file <path>]` | Print a fresh private key and its address. `--file` writes the key to a new file only you can read and prints `BRAINCHAIN_WORKER_KEY_FILE=<path>` in place of the key; it never replaces an existing file. |
 | `join --name <name> --about <text> [--price <USDG>] [--agent-id <id>]` | Claim tBRAIN from the faucet if needed (on mainnet, the BRAIN comes from the wallet), stake the minimum and apply. Jev reads the name and description to decide, and refuses an empty one. The name is one line of at most 60 characters and the description at most 500, and neither may hold invisible or direction-changing characters. `--agent-id` (mainnet) names the worker's ERC-8004 agent on Robinhood Chain. The wallet must own that agent or be its registered wallet; `join` checks this before it sends anything, and the id goes in the application. Every task the worker is hired for while its wallet holds that id is then written to the identity's reputation, tag `brainchain`, from `0xafB0C4Ef895D4895040cdC6435B96D3EE8350c6E`. A new worker's price defaults to 0.20; a worker that has staked keeps its price unless `--price` changes it. An allowed worker whose stake fell below the minimum, after `leave` or a slash, stakes back up to it. Stake that is unstaking does not count, so the tBRAIN comes from the wallet or the faucet until `withdraw` returns it. |
-| `run --exec "<command>" [--format prompt\|json] [--timeout <minutes>] [--once] [--no-mint]` | Do every task the worker is hired for, earliest deadline first, and mint the Proof of each one that is paid. It logs how each delivered task settles: paid and how much, or refunded, why and any stake slashed. An idle run logs a line each hour with whether the worker can be hired. `--timeout` sets how many minutes the command may spend on one task: 20 by default, at most 1440, fractions allowed. `--once` does one pass and exits, with code 1 if a task failed or was left too close to its deadline, for a cron job. `--no-mint` mints no Proofs. |
-| `status` | Whether the worker can be hired, its stake, its tBRAIN or BRAIN balance, price, record and earnings. The record counts tasks paid, refunded and in flight, and gives a line for each task in flight: accepted and when it is paid, disputed and when Jev rules, ruled and until when it can be appealed. Below the minimum stake, it also says where `join` will find the tBRAIN it needs, or on mainnet where to buy BRAIN. |
+| `run --exec "<command>" [--format prompt\|json] [--timeout <minutes>] [--once] [--mint]` | Do every task the worker is hired for, earliest deadline first, and with `--mint` mint the Proof of each one that is paid. It logs how each delivered task settles: paid and how much, or refunded, why and any stake slashed. An idle run logs a line each hour with whether the worker can be hired. Until it can be, the run checks every 5 minutes and logs each change, such as Jev allowing the worker and the timelock passing. Once the wallet's ETH covers fewer than 3 deliveries, it says so after each one. `--timeout` sets how many minutes the command may spend on one task: 20 by default, at most 1440, fractions allowed. `--once` does one pass and exits, with code 1 if a task failed or was left too close to its deadline, for a cron job. `--no-mint` is still accepted and changes nothing; minting happens only with `--mint`. |
+| `status` | Whether the worker can be hired, its stake, its tBRAIN or BRAIN balance, price, record, earnings and ETH for gas, with about how many deliveries that ETH pays for. The record counts tasks paid, refunded and in flight, and gives a line for each task in flight: accepted and when it is paid, disputed and when Jev rules, ruled and until when it can be appealed. Below the minimum stake, it also says where `join` will find the tBRAIN it needs, or on mainnet where to buy BRAIN. |
 | `price <USDG>` | Change the asking price, in tUSDG on testnet and USDG on mainnet. |
 | `mint [--count <n>] [--dry]` | Mint the Proof of each paid task waiting for one, up to 10 at a time or `--count`, at 0.001 WETH each on Robinhood Chain plus gas. `--dry` lists the tasks and what the wallet lacks without sending anything. |
 | `claim [--dry]` | Claim the ETH due on the worker's Proofs on Robinhood Chain, in one transaction. `--dry` lists each Proof and what it is due without sending anything. |
+| `bond <task> <USDG> [--yes]` | Lock USDG on Shipped behind a task, at least its bounty and 2 USDG. Prints the fee, the gas and both outcomes, then asks; `--yes` sends without a terminal. See [Bond a task](#bond-a-task). Mainnet. |
+| `bond status <task>` | Where the worker's bond on a task stands: open, marked, delivered or missed. |
+| `bond claim <task>` | Collect what a settled bond left the worker, with `withdraw` on Shipped's registry. |
 | `bridge --eth <ETH> \| --stake <amount> \| --bounty <amount> [--dry]` | Move ETH, the stake token or the bounty token from Robinhood Chain to the worker's address on BrainChain. `--eth` works on testnet and mainnet; `--stake` and `--bounty` on mainnet, since testnet's tokens exist only on BrainChain. |
 | `credit --agent-id <id> [--premium <bps>]` | Sign Priors' consent for BrainChain to back a credit line for the worker's ERC-8004 agent, with the key that owns the agent, and send it to the service. The line opens once the worker is proven on the board. `--premium` is the most the sponsor may charge per 30 days (default 0, at most 200). Mainnet only. |
 | `watch [--veto] [--once]` | 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 when a decision could not be checked or reported, keeping its place so the next run checks it again. It saves its place in `~/.config/brainchain-worker`, one for each key and one for runs without a key, and only warns if it cannot write there. A change that has run or was vetoed is listed and is not a finding. |
 | `propose --target <contract> --call <function> --args <JSON> --title <text> --rationale <text> [--current <text>] [--proposed <text>] [--data <hex>] [--dry]` | Bond the stake token and propose a change for Jev to decide. See [Propose a change](#propose-a-change). |
 | `proposal <id>` | Where a proposal stands: waiting for Jev and until when, adopted and when its change runs, or kept with the bond burned. Needs no key. |
 | `dispute <task>` | Dispute the grade on a task the worker delivered, inside the dispute window. Jev rules; a confident ruling decides, otherwise the grade stands. |
-| `appeal <task>` | Appeal a ruling that went against the worker, inside the appeal window, approving the bond (a quarter of the bounty) first. Jev rules again; the bond comes back unless Jev confidently rules the same way. Testnet only for now. |
+| `appeal <task>` | Appeal a ruling that went against the worker, inside the appeal window, approving the bond (a quarter of the bounty) first. A wallet holding less tUSDG than the bond claims it from the test USDG faucet before that, which gives 100 tUSDG once a day. Jev rules again; the bond comes back unless Jev confidently rules the same way. Testnet only for now. |
 | `leave` | Start unstaking. The stake unlocks after 3 days, once no task of the worker's is in flight. |
 | `withdraw` | Withdraw the unlocked stake. |
 | `--version` | Print the version. |

package/dist/bond.js

@@ -0,0 +1,300 @@
+// A delivery bond on Shipped: the worker locks USDG on Robinhood Chain behind
+// a task, and the task's Proof is what releases it. Shipped's check reads
+// BrainChain's ProofIndex, proofOf(task) >= 1, so a task that is paid and gets
+// its Proof returns the bond less Shipped's 1% fee, and one that is not pays
+// the bond to the task's poster.
+import { createPublicClient, createWalletClient, decodeAbiParameters, decodeFunctionData, encodeAbiParameters, encodeFunctionData, formatEther, http, isAddress, parseAbi, parseEventLogs, } from "viem";
+import { taskBoardAbi } from "./abi.js";
+import { erc20Abi, RECEIPT_MS, Status } from "./chain.js";
+import { chainOf, proofsChainOf, proofsTransport } from "./network.js";
+import { usdg, when } from "./standing.js";
+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)";
+export const shippedAbi = parseAbi([
+    `function create(${TERMS} t, uint256 deposit) returns (uint256 deedId)`,
+    "function withdraw(address asset) returns (uint256)",
+    "function owed(address account, address asset) view returns (uint256)",
+    "function deedCount() view returns (uint256)",
+    "function core(uint256 deedId) view returns (address creator, uint8 status, address asset, uint64 deadline)",
+    `function getDeed(uint256 deedId) view returns ((address creator, uint8 status, uint8 ruling, uint16 remainderBps, uint16 feeBps, bool overturned, uint64 createdAt, uint64 ruledAt, uint64 appealedAt, uint64 settledAt, uint64 checkMetAt, uint64 windowEnd, address ruledBy, address appellant, uint256 balance, ${TERMS} terms))`,
+    `event DeedCreated(uint256 indexed deedId, address indexed creator, address indexed project, ${TERMS} terms, uint256 deposit, uint16 feeBps)`,
+    "error AssetNotAllowed()",
+    "error CreationIsPaused()",
+    "error InvalidDeadline()",
+    "error InvalidRefund()",
+    "error NothingOwed()",
+]);
+/** ShippedDeeds.Status and Ruling. */
+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 };
+const BPS = 10000n;
+const ZERO = "0x0000000000000000000000000000000000000000";
+/** The bond's deadline is the task's plus this: grading, the worker's day to mint and the check's hold all fit. */
+export const BOND_LEAD_SEC = 48n * 3600n;
+/** A marked check is confirmed an hour later; a bond with no Proof can be settled a day after that. */
+export const CHECK_HOLD_SEC = 3600n;
+export const CHECK_CONFIRM_SEC = 86400n;
+/** Shipped's fee on a released bond, in basis points, as the registry charges it today. */
+export const FEE_BPS = 100n;
+/** Below this the fee and the gas are too large a share of the bond. */
+export const MIN_BOND = 2000000n;
+/** Gas each transaction takes, measured on a fork of Robinhood Chain (approve 57,976; create 978,948 on a 496-byte milestone; withdraw 61,603), with room. */
+export const GAS = { approve: 60000n, create: 1100000n, withdraw: 85000n };
+/** Deeds read per batch, and the most read when the worker's bonds are looked for. */
+const DEED_BATCH = 200;
+const DEED_SCAN = 5_000;
+const checkDataTypes = [{ type: "address" }, { type: "bytes" }, { type: "uint8" }, { type: "uint256" }];
+/** StaticCallCheck data: proofOf(board, task) on the index, at least 1. Task ids restart with each board, so the board is part of the key. */
+export function encodeCheckData(proofIndex, board, task) {
+    return encodeAbiParameters(checkDataTypes, [proofIndex, encodeFunctionData({ abi: proofIndexAbi, functionName: "proofOf", args: [board, task] }), 0, 1n]);
+}
+/** The task a bond's check reads on `proofIndex` for `board`, or undefined for any other check. */
+export function taskOfCheck(data, proofIndex, board) {
+    try {
+        const [target, call, op, threshold] = decodeAbiParameters(checkDataTypes, data);
+        if (target.toLowerCase() !== proofIndex.toLowerCase() || op !== 0 || threshold !== 1n)
+            return undefined;
+        const { functionName, args } = decodeFunctionData({ abi: proofIndexAbi, data: call });
+        return functionName === "proofOf" && args[0].toLowerCase() === board.toLowerCase() ? args[1] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The terms of a delivery bond on one task. Shipped's own check decides it, so
+ * there is no verifier and no appeal; the refund side is the agent that paid
+ * for the task: the poster on the board, or the payer the desk recorded.
+ */
+export function bondTerms(config, task, board) {
+    return {
+        title: `BrainChain task #${task.id}`,
+        milestone: `The Proof NFT for BrainChain task #${task.id} (task board ${board.address} on BrainChain, chain ${board.chainId}) is recorded in BrainChain's ProofIndex at ${config.proofIndex} on Robinhood Chain, ` +
+            `read as proofOf(${board.address}, ${task.id}) >= 1. BrainChain records the Proof once the task is paid and the Proof is minted. ` +
+            `If no Proof is recorded by the deadline, the bond is paid to ${task.refundTo}, ${task.paidThroughDesk ? "the agent that paid BrainChain's desk for the task" : "the task's poster"}.`,
+        project: ZERO,
+        projectKind: 0,
+        asset: config.usdg,
+        deadline: task.deadline + BOND_LEAD_SEC,
+        verifier: ZERO,
+        backupVerifier: ZERO,
+        appealPanel: ZERO,
+        check: config.check,
+        checkData: encodeCheckData(config.proofIndex, board.address, task.id),
+        refundTo: task.refundTo,
+        defaultRemainderBps: 0,
+        refundCapBps: 0,
+        allowPartial: false,
+        verifierGrace: 0,
+        backupGrace: 0,
+        appealWindow: 0,
+        panelWindow: 0,
+        appealBond: 0n,
+        verifierFee: 0n,
+        refundExcluded: [],
+    };
+}
+export function createBondChain(network, config, account, fetcher = fetch) {
+    const brainchain = createPublicClient({ chain: chainOf(network), transport: http(network.rpc, { timeout: 20_000, retryCount: 2 }) });
+    const chain = proofsChainOf(network.proofs);
+    const transport = proofsTransport(network.proofs);
+    const client = createPublicClient({ chain, transport, pollingInterval: 1_000 });
+    const wallet = createWalletClient({ account, chain, transport });
+    const registry = { address: config.registry, abi: shippedAbi };
+    const token = { address: config.usdg, abi: erc20Abi };
+    async function send(request) {
+        const hash = await wallet.writeContract(request);
+        const receipt = await client.waitForTransactionReceipt({ hash, timeout: RECEIPT_MS });
+        if (receipt.status !== "success")
+            throw new Error(`Transaction ${hash} reverted`);
+        return { hash, receipt };
+    }
+    return {
+        account: account.address,
+        async task(id) {
+            const t = await brainchain.readContract({ address: network.contracts.taskBoard, 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, config.registry] }),
+        async approve(amount) {
+            return (await send({ ...token, functionName: "approve", args: [config.registry, amount] })).hash;
+        },
+        async create(terms, amount) {
+            const { hash, receipt } = await send({ ...registry, functionName: "create", args: [terms, amount] });
+            const created = parseEventLogs({ abi: shippedAbi, eventName: "DeedCreated", args: { creator: account.address }, logs: receipt.logs }).find((log) => log.address.toLowerCase() === config.registry.toLowerCase());
+            if (!created)
+                throw new Error(`The bond ${hash} created no deed for ${account.address}`);
+            return { deed: created.args.deedId, tx: hash };
+        },
+        async bondsOn(task) {
+            if (!config.proofIndex)
+                return [];
+            const count = Number(await client.readContract({ ...registry, functionName: "deedCount" }));
+            const mine = [];
+            for (let to = count; to > Math.max(0, count - DEED_SCAN); to -= DEED_BATCH) {
+                const ids = Array.from({ length: Math.min(DEED_BATCH, to - Math.max(0, count - DEED_SCAN)) }, (_, 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() !== config.check.toLowerCase() || taskOfCheck(d.terms.checkData, config.proofIndex, network.contracts.taskBoard) !== task)
+                    return [];
+                return [{ deed, task, amount: d.balance, deadline: d.terms.deadline, status: d.status, ruling: d.ruling, remainderBps: d.remainderBps, checkMetAt: d.checkMetAt, settledAt: d.settledAt, refundTo: d.terms.refundTo }];
+            });
+        },
+        proofOf: (task) => client.readContract({ address: config.proofIndex, abi: proofIndexAbi, functionName: "proofOf", args: [network.contracts.taskBoard, task] }),
+        async payerOf(task) {
+            const host = new URL(network.service).host;
+            const response = await fetcher(`${network.service}/bonds/refund-to/${task}`, { signal: AbortSignal.timeout(15_000) }).catch(() => {
+                throw new Error(`Could not reach the BrainChain service at ${host} to ask who paid for task ${task}`);
+            });
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw new Error(`The BrainChain service at ${host} answered ${response.status} when asked who paid for task ${task}`);
+            }
+            const { refundTo } = (await response.json().catch(() => undefined)) ?? {};
+            if (refundTo === null || refundTo === undefined)
+                return undefined;
+            if (typeof refundTo !== "string" || !isAddress(refundTo))
+                throw new Error(`The BrainChain service at ${host} named the payer of task ${task} in a form bond cannot read`);
+            return refundTo;
+        },
+        owed: () => client.readContract({ ...registry, functionName: "owed", args: [account.address, config.usdg] }),
+        async withdraw() {
+            const amount = await client.readContract({ ...registry, functionName: "owed", args: [account.address, config.usdg] });
+            const { hash } = await send({ ...registry, functionName: "withdraw", args: [config.usdg] });
+            return { amount, tx: hash };
+        },
+    };
+}
+/** The ETH the bond's transactions need at this gas price, approval included when one is needed. */
+export const bondGas = (gasPrice, approves) => (GAS.create + (approves ? GAS.approve : 0n)) * gasPrice;
+const fee = (amount) => (amount * FEE_BPS) / BPS;
+/** Where a bond stands, in one line. */
+export function bondLine(network, b, indexed, now) {
+    const head = `Bond No. ${b.deed} on task ${b.task}: ${usdg(network, b.amount)}`;
+    if (b.status === DeedStatus.Settled) {
+        if (b.remainderBps === Number(BPS))
+            return `${head}, delivered at ${when(b.settledAt)}: ${usdg(network, b.amount - fee(b.amount))} back after Shipped's 1% fee (bond claim ${b.task} collects it)`;
+        return `${head}, missed: paid to the poster ${b.refundTo} at ${when(b.settledAt)}`;
+    }
+    if (b.checkMetAt > 0n) {
+        const confirmAt = b.checkMetAt + CHECK_HOLD_SEC;
+        return `${head}, the Proof is in the index and the check was marked at ${when(b.checkMetAt)}; BrainChain confirms it ${now < confirmAt ? `after ${when(confirmAt)}` : "shortly"}`;
+    }
+    if (now > b.deadline)
+        return `${head}, deadline ${when(b.deadline)} passed with no Proof recorded; it settles to the poster ${b.refundTo} after ${when(b.deadline + CHECK_HOLD_SEC + CHECK_CONFIRM_SEC)}`;
+    return `${head}, open until ${when(b.deadline)}: ${indexed ? "the Proof is in the index and BrainChain marks the check shortly" : "waiting for the task to be paid and its Proof recorded"}`;
+}
+function closed(network, config) {
+    if (!config)
+        return `Bonds run on Robinhood Chain against Shipped's registry, which ${network.name} has no counterpart of. Set BRAINCHAIN_NETWORK=mainnet.`;
+    if (!config.proofIndex)
+        return "Bonds are not open yet: BrainChain's ProofIndex on Robinhood Chain, which a bond's check reads, is not deployed. A later release of brainchain-worker names it.";
+    return undefined;
+}
+/** Reads the task, says what the bond costs and what it does, and sends the approval and the bond. */
+export async function bond(network, config, chain, task, options) {
+    const { log } = options;
+    const shut = closed(network, config);
+    if (shut)
+        throw new Error(shut);
+    const open = config;
+    const t = await chain.task(task);
+    if (!t)
+        throw new Error(`There is no task ${task} on ${network.name}.`);
+    if (t.poster.toLowerCase() === chain.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 worker posted itself.`);
+    const hiredHere = t.status === Status.Hired && t.model.toLowerCase().endsWith(chain.account.slice(2).toLowerCase());
+    if (t.status !== Status.Open && !hiredHere)
+        throw new Error(`Task ${task} is not open and not hired to this worker, so there is nothing to bond.`);
+    const now = await chain.now();
+    if (t.deadline <= now)
+        throw new Error(`Task ${task}'s deadline, ${when(t.deadline)}, has passed.`);
+    if (options.amount < t.bounty)
+        throw new Error(`The bond must be at least the task's bounty, ${usdg(network, t.bounty)}; ${usdg(network, options.amount)} is under it.`);
+    if (options.amount < MIN_BOND)
+        throw new Error(`The bond must be at least ${usdg(network, MIN_BOND)}: under that, Shipped's fee and the gas take too much of it.`);
+    const existing = (await chain.bondsOn(task)).find((b) => b.status !== DeedStatus.Settled);
+    if (existing)
+        throw new Error(`This worker already has bond No. ${existing.deed} open on task ${task}. \`bond status ${task}\` shows where it stands.`);
+    // 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 chain.payerOf(task);
+    if (payer?.toLowerCase() === chain.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 worker paid for itself.`);
+    const refundTo = payer ?? t.poster;
+    const [balance, allowance, gasPrice, eth] = await Promise.all([chain.usdgBalance(), chain.allowance(), chain.gasPrice(), chain.ethBalance()]);
+    const approves = allowance < options.amount;
+    const gas = bondGas(gasPrice, approves);
+    const terms = bondTerms(open, { id: task, refundTo, paidThroughDesk: payer !== undefined, deadline: t.deadline }, { address: network.contracts.taskBoard, chainId: network.chainId });
+    const back = options.amount - fee(options.amount);
+    log([
+        `Bond ${usdg(network, options.amount)} on task ${task} (bounty ${usdg(network, t.bounty)}, deadline ${when(t.deadline)}).`,
+        `  Released by the task's Proof: ${usdg(network, back)} back after Shipped's 1% fee (${usdg(network, fee(options.amount))}), collected with \`bond claim ${task}\`.`,
+        `  Missed: if no Proof is recorded by ${when(terms.deadline)}, the ${usdg(network, options.amount)} goes to ${refundTo}, ${payer ? "the agent that paid for the task" : "the poster"}.`,
+        `  Gas now: about ${formatEther(gas)} ETH on ${network.proofs.name} for ${approves ? "the approval and the bond" : "the bond"} at ${formatEther(gasPrice * 1000000000n)} gwei; the claim later costs about ${formatEther(GAS.withdraw * gasPrice)} ETH.`,
+    ].join("\n"));
+    if (balance < options.amount)
+        throw new Error(`${chain.account} holds ${usdg(network, balance)} on ${network.proofs.name}, under the ${usdg(network, options.amount)} to bond. Nothing was sent.`);
+    if (eth < gas)
+        throw new Error(`${chain.account} holds ${formatEther(eth)} ETH on ${network.proofs.name}, under the ${formatEther(gas)} ETH the transactions need. Nothing was sent.`);
+    if (!options.yes) {
+        if (!options.ask)
+            throw new Error("There is no terminal to confirm on. Run again with --yes to send without asking.");
+        const answer = (await options.ask("Send it? [y/N] ")).trim().toLowerCase();
+        if (answer !== "y" && answer !== "yes")
+            return log("Nothing sent.");
+    }
+    if (approves) {
+        log(`Approving ${usdg(network, options.amount)} for Shipped's registry...`);
+        await chain.approve(options.amount);
+    }
+    log(`Bonding ${usdg(network, options.amount)} on task ${task}...`);
+    const { deed, tx } = await chain.create(terms, options.amount);
+    log(`Bond No. ${deed} is open on Shipped (${tx}). Jev reads it when it hires; \`bond status ${task}\` follows it.`);
+}
+/** Prints where the worker's bonds on a task stand. */
+export async function bondStatus(network, config, chain, task, log) {
+    const shut = closed(network, config);
+    if (shut)
+        throw new Error(shut);
+    const bonds = await chain.bondsOn(task);
+    if (bonds.length === 0)
+        return log(`${chain.account} has no bond on task ${task}.`);
+    const [now, indexed] = await Promise.all([chain.now(), chain.proofOf(task)]);
+    for (const b of bonds)
+        log(bondLine(network, b, indexed > 0n, now));
+}
+/** Collects what a settled bond left the worker: withdraw(USDG) on the registry. */
+export async function bondClaim(network, config, chain, task, log) {
+    const shut = closed(network, config);
+    if (shut)
+        throw new Error(shut);
+    const [latest] = await chain.bondsOn(task);
+    if (!latest)
+        throw new Error(`${chain.account} has no bond on task ${task}.`);
+    if (latest.status !== DeedStatus.Settled) {
+        const [now, indexed] = await Promise.all([chain.now(), chain.proofOf(task)]);
+        throw new Error(`${bondLine(network, latest, indexed > 0n, now)}. It can be claimed once it has settled.`);
+    }
+    const owed = await chain.owed();
+    if (owed === 0n) {
+        return log(latest.remainderBps === Number(BPS) ? `Bond No. ${latest.deed} was delivered and its ${usdg(network, latest.amount - fee(latest.amount))} already withdrawn.` : `Bond No. ${latest.deed} was missed: its ${usdg(network, latest.amount)} went to the poster ${latest.refundTo}, so there is nothing to claim.`);
+    }
+    if ((await chain.ethBalance()) === 0n)
+        throw new Error(`${chain.account} has no ETH on ${network.proofs.name} to pay gas for the claim.`);
+    log(`Claiming ${usdg(network, owed)} from Shipped's registry on ${network.proofs.name}...`);
+    const { amount, tx } = await chain.withdraw();
+    log(`Paid ${usdg(network, amount)} to ${chain.account} (${tx}).`);
+}

package/dist/bridge.js

@@ -1,6 +1,7 @@
 import { createPublicClient, createWalletClient, encodeAbiParameters, formatEther, formatUnits, http, parseAbi, parseUnits, } from "viem";
 import { reason, RECEIPT_MS } from "./chain.js";
 import { chainOf, parentChainOf } from "./network.js";
+import { grouped } from "./standing.js";
 const inboxAbi = parseAbi([
     "function depositEth() payable returns (uint256)",
     "function calculateRetryableSubmissionFee(uint256 dataLength, uint256 baseFee) view returns (uint256)",
@@ -100,7 +101,8 @@ export async function bridge(network, chain, options) {
     const amount = parseUnits(options.amount, decimals);
     if (amount <= 0n)
         throw new Error("the amount must be above zero");
-    const shown = `${formatUnits(amount, decimals)} ${symbol}`;
+    // Token amounts are grouped as status shows them; ETH amounts are small.
+    const shown = asset === "eth" ? `${formatUnits(amount, decimals)} ${symbol}` : `${grouped(amount, decimals)} ${symbol}`;
     let eth;
     try {
         eth = await chain.parentEth();
@@ -120,7 +122,7 @@ export async function bridge(network, chain, options) {
     }
     const held = await chain.tokenBalance(asset);
     if (held < amount) {
-        throw new Error(`${chain.account} holds ${formatUnits(held, decimals)} ${symbol} on ${parent.name}, ${formatUnits(amount - held, decimals)} short of ${shown}`);
+        throw new Error(`${chain.account} holds ${grouped(held, decimals)} ${symbol} on ${parent.name}, ${grouped(amount - held, decimals)} short of ${shown}`);
     }
     const value = await chain.arrivalCost(asset, amount);
     if (eth < value + parseUnits("0.0001", 18)) {

package/dist/chain.js

@@ -359,6 +359,8 @@ export function createChain(network, account, store = memoryStore()) {
         ...work,
         account: account.address,
         gasPrice: () => client.getGasPrice(),
+        /** How many transactions the wallet has sent. */
+        sent: () => client.getTransactionCount({ address: account.address }),
         stakeBalance: () => client.readContract({ address: stakeToken, abi: erc20Abi, functionName: "balanceOf", args: [account.address] }),
         bountyBalance: () => client.readContract({ address: bountyToken, abi: erc20Abi, functionName: "balanceOf", args: [account.address] }),
         stake: () => client.readContract({ address: staking, abi: workerStakingAbi, functionName: "get", args: [account.address] }),

package/dist/cli.js

@@ -1,25 +1,31 @@
 import { createRequire } from "node:module";
+import { createInterface } from "node:readline/promises";
 import { verifyDecision } from "brainchain-verify";
 import { createPublicClient, http } from "viem";
-import { parseUnits } from "viem";
+import { formatEther, parseUnits, zeroAddress } from "viem";
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
 import { brainchainTransport, createChain, faucetReopens, reason, requireChainId, unhealthy } from "./chain.js";
+import { bond, bondClaim, bondStatus, createBondChain } from "./bond.js";
 import { assetOf, bridge, createBridgeChain } from "./bridge.js";
 import { claim, createIncome } from "./claim.js";
 import { createProofsChain, createSettlementWatch, MAX_MINT, mint } from "./mint.js";
 import { chainOf, resolveNetwork } from "./network.js";
 import { buildCall, caseURI, createProposals, proposal, propose } from "./propose.js";
-import { ethNeeded, flightLine, gasLine, hireable, joinLimits, shortOfGas, shortOfStake, snapshot, stake, usdg, wallet, when } from "./standing.js";
+import { deliveries, deliveriesLeft, ethNeeded, flightLine, gasHelp, gasLine, hireable, joinLimits, shortOfGas, shortOfStake, snapshot, stake, usdg, wallet, when } from "./standing.js";
 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 { createWork, firstProgram, HIDDEN, npxUnderSupervisor, programFound, shellCommand, stopLeftover, stopper, watchStarter } from "./work.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;
 /** How long an idle run goes without a line before it says it is still waiting. */
 const HEARTBEAT_MS = 3_600_000;
+/** Below this many deliveries' worth of gas, run warns after each delivery. */
+const LOW_DELIVERIES = 3n;
+/** How often a run that cannot be hired yet reads again whether it can. */
+const HIREABLE_CHECK_MS = 300_000;
 /** A published record's bytes as the service serves them, capped at a megabyte. */
 async function fetchRecord(uri) {
     const response = await fetch(uri, { signal: AbortSignal.timeout(20_000) });
@@ -34,19 +40,20 @@ const { version } = createRequire(import.meta.url)("../package.json");
 /** Each command's lines in the usage text, in the order the text lists them. */
 const COMMAND_USAGE = {
     "new-key": `  brainchain-worker new-key [--file <path>] Print a fresh private key and its address. --file writes the key
-                                            to a new file only you can read and prints only the address.`,
+                                            to a new file only you can read and prints the file's path in
+                                            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.`,
-    run: `  brainchain-worker run --exec "<command>" [--format prompt|json] [--timeout <minutes>] [--once] [--no-mint]
+    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
                                             --timeout minutes (20 by default, at most 1440). It logs how
-                                            each task settles, and mints the Proof of each task it is paid
-                                            for, unless --no-mint.`,
-    status: `  brainchain-worker status                  Stake, wallet, application, record and earnings, with where each
+                                            each task settles. --mint also mints the Proof of each task it is
+                                            paid for.`,
+    status: `  brainchain-worker status                  Stake, wallet, application, record, earnings and gas, with where each
                                             task in flight stands.`,
     price: `  brainchain-worker price <USDG>            Change your asking price per task.`,
     mint: `  brainchain-worker mint [--count <n>] [--dry]
@@ -54,6 +61,13 @@ const COMMAND_USAGE = {
                                             --count, at 0.001 WETH each on Robinhood Chain. --dry 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.`,
     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
@@ -84,8 +98,9 @@ const COMMAND_USAGE = {
                                             window. Jev rules on it; a confident ruling decides.`,
     appeal: `  brainchain-worker appeal <task>           Appeal the ruling on a task, when it went against the worker, within the
                                             appeal window, with the bond the task's terms fix (a quarter of the
-                                            bounty). Jev rules again; the bond comes back unless Jev confidently
-                                            rules the same way. Testnet only for now.`,
+                                            bounty), claimed from the test USDG faucet when the wallet holds less.
+                                            Jev rules again; the bond comes back unless Jev confidently rules the
+                                            same way. Testnet only for now.`,
     leave: `  brainchain-worker leave                   Start unstaking (3-day cooldown).`,
     withdraw: `  brainchain-worker withdraw                Withdraw stake once the cooldown has passed.`,
 };
@@ -119,12 +134,14 @@ export class UsageError extends Error {
 const FLAGS = {
     "new-key": { file: false },
     join: { name: false, about: false, price: false, "agent-id": false },
-    run: { exec: false, format: false, timeout: false, once: true, "no-mint": true },
+    // --no-mint is still accepted from before minting became opt-in; it changes nothing.
+    run: { exec: false, format: false, timeout: false, once: true, mint: true, "no-mint": true },
     status: {},
     price: {},
     leave: {},
     withdraw: {},
     claim: { dry: true },
+    bond: { yes: true },
     mint: { count: false, dry: true },
     bridge: { eth: false, stake: false, bounty: false, dry: true },
     watch: { veto: true, once: true },
@@ -134,7 +151,7 @@ const FLAGS = {
     dispute: {},
     appeal: {},
 };
-const POSITIONAL = { price: 1, proposal: 1, dispute: 1, appeal: 1 };
+const POSITIONAL = { price: 1, proposal: 1, dispute: 1, appeal: 1, bond: 2 };
 /** A command's flags; a name from argv can match what every object inherits, such as constructor. */
 const flagsOf = (command) => (Object.hasOwn(FLAGS, command) ? FLAGS[command] : undefined);
 export function parse(command, args) {
@@ -193,7 +210,7 @@ function signer() {
     const raw = keyText()?.trim();
     if (!raw)
         throw new Error("Set BRAINCHAIN_WORKER_KEY to the worker's private key, or BRAINCHAIN_WORKER_KEY_FILE to a file that holds it. `npx brainchain-worker new-key` makes one.");
-    const hex = raw.startsWith("0x") ? raw.slice(2) : raw;
+    const hex = raw.replace(/^0x/i, "");
     if (!/^[0-9a-fA-F]{64}$/.test(hex))
         throw new Error("The worker's key must be 64 hex characters, with or without 0x");
     const key = `0x${hex.toLowerCase()}`;
@@ -214,12 +231,12 @@ function price(value) {
 }
 const RUN = '`npx brainchain-worker run --exec "<command>"`';
 const KEEP_RUNNING = "https://github.com/usebrainchain/brainchain-worker#keep-it-running";
-function noGas(chain, network) {
-    return new Error(`${chain.account} has no ETH on ${network.name} for gas. ${network.gas(chain.account)}.`);
+async function noGas(chain, network) {
+    return new Error(`${chain.account} has no ETH on ${network.name} for gas. ${gasHelp(network, chain.account, 0n, await chain.sent())}.`);
 }
 async function needGas(chain, network) {
     if ((await chain.ethBalance()) === 0n)
-        throw noGas(chain, network);
+        throw await noGas(chain, network);
 }
 export async function join(chain, network, values) {
     const name = values.get("name")?.trim() ?? "";
@@ -229,15 +246,18 @@ export async function join(chain, network, values) {
     if (name.length > 60)
         throw new UsageError("--name is at most 60 characters");
     // A name that hides characters or turns text around can read as another, Jev's included.
-    if (HIDDEN.test(name) || /[\x00-\x1f\x7f-\x9f]/.test(name))
-        throw new UsageError("--name must be one line with no invisible or direction-changing characters");
+    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");
-    if (HIDDEN.test(about))
-        throw new UsageError("--about must have no invisible or direction-changing characters");
+    // A description may run over several lines.
+    const aboutHides = unseen(about.replace(/[\t\n]/g, " "));
+    if (aboutHides)
+        throw new UsageError(`--about must have no invisible or direction-changing characters, and it holds ${aboutHides}`);
     const agentId = values.get("agent-id");
     if (agentId !== undefined && !/^(0|[1-9]\d{0,14})$/.test(agentId))
         throw new UsageError("--agent-id is the worker's ERC-8004 agent id, a whole number");
@@ -261,12 +281,19 @@ export async function join(chain, network, values) {
     }
     // A worker that has staked keeps its price unless --price changes it.
     const asking = requested ?? (w.registered ? w.price : price(DEFAULT_PRICE));
-    const [gas, gasPrice, bond, balance, timelock] = await Promise.all([chain.ethBalance(), chain.gasPrice(), chain.bond(), chain.stakeBalance(), chain.timelock()]);
+    const [gas, gasPrice, bond, balance, timelock, sent] = await Promise.all([
+        chain.ethBalance(),
+        chain.gasPrice(),
+        chain.bond(),
+        chain.stakeBalance(),
+        chain.timelock(),
+        chain.sent(),
+    ]);
     const need = toStake + (applying ? bond : 0n);
     const claims = balance < need && !network.buyStake;
     // Checked before anything is sent: a wallet that runs out partway leaves the stake placed and the application unsent.
     const gasNeed = ethNeeded(joinLimits(standing, claims, toStake === 0n && w.price !== asking), gasPrice);
-    const lacksGas = gas < gasNeed ? `${chain.account} holds ${shortOfGas(network, chain.account, gas, gasNeed, "join")}` : undefined;
+    const lacksGas = gas < gasNeed ? `${chain.account} holds ${shortOfGas(network, chain.account, gas, sent, gasNeed, "join")}` : undefined;
     if (balance < need && network.buyStake) {
         const short = shortOfStake(network, w, balance, need, await chain.now());
         // Both needs at once, so a new worker does not bridge ETH only to learn it needs the stake token too.
@@ -320,9 +347,10 @@ export async function join(chain, network, values) {
         "the application with `npx brainchain-worker status`. New workers are offered house tasks first, which BrainChain pays for.");
 }
 async function status(chain, network) {
-    const [gas, gasPrice, s, held, record, bountyBalance, stakeBalance, bond, faucet, now] = await Promise.all([
+    const [gas, gasPrice, sent, s, held, record, bountyBalance, stakeBalance, bond, faucet, now] = await Promise.all([
         chain.ethBalance(),
         chain.gasPrice(),
+        chain.sent(),
         snapshot(chain),
         chain.held(),
         chain.record(),
@@ -342,7 +370,7 @@ async function status(chain, network) {
   Price     ${w.registered ? `${usdg(network, w.price)} per task` : "not set until you join"}
   Record    ${record.paid} paid, ${record.refunded} refunded, ${record.inFlight.length} in flight${held > 0 ? " (stake held until they settle)" : ""}${record.inFlight.map((f) => `\n            ${flightLine(f)}`).join("")}
   Earned    ${usdg(network, record.earned)} after fees; wallet holds ${usdg(network, bountyBalance)}
-  Gas       ${gasLine(network, chain.account, s, gas, gasPrice, !network.buyStake && stakeBalance < s.toStake + (s.applying ? bond : 0n))}`);
+  Gas       ${gasLine(network, chain.account, s, gas, gasPrice, !network.buyStake && stakeBalance < s.toStake + (s.applying ? bond : 0n), sent)}`);
 }
 async function run(network, { key, account }, values, once, mints) {
     const exec = values.get("exec");
@@ -379,9 +407,23 @@ async function run(network, { key, account }, values, once, mints) {
         stopping: stop.stopping,
         // A cron job sees a failed task as a failed run.
         failed: once ? () => void (process.exitCode = 1) : undefined,
-        delivered: settlements.track,
-        gasHelp: network.gas(account.address),
+        delivered(task) {
+            settlements.track(task);
+            void lowGas();
+        },
+        gasHelp: async () => gasHelp(network, account.address, 0n, await chain.sent()),
     });
+    // The drip pays for only a few deliveries, so the log says when the wallet is down to its last ones.
+    const lowGas = async () => {
+        const [gas, price, sent] = await Promise.all([chain.ethBalance(), chain.gasPrice(), chain.sent()]).catch(() => []);
+        if (gas === undefined || price === undefined || sent === undefined)
+            return;
+        const left = deliveriesLeft(gas, price);
+        if (left >= LOW_DELIVERIES)
+            return;
+        const enough = left === 0n ? "not enough for another delivery" : `enough for about ${left} more ${left === 1n ? "delivery" : "deliveries"}`;
+        log(`warning: the wallet holds ${formatEther(gas)} ETH for gas, ${enough}. ${gasHelp(network, account.address, gas, sent)}.`);
+    };
     for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"])
         process.on(signal, stop.signal);
     if (process.env.npm_execpath !== undefined) {
@@ -406,12 +448,14 @@ async function run(network, { key, account }, values, once, mints) {
         log(`could not read the wallet's ETH balance: ${reason(error)}`);
     }
     if (gas === 0n)
-        throw noGas(chain, network);
-    const [line, sick] = await Promise.all([
+        throw await noGas(chain, network);
+    const held = gas;
+    const [line, sick, left] = await Promise.all([
         snapshot(chain).then((s) => hireable(s, network, "run"), (error) => `could not check (${reason(error)})`),
         unhealthy(network.service),
+        held === undefined ? undefined : chain.gasPrice().then((price) => deliveriesLeft(held, price), () => undefined),
     ]);
-    log(`worker ${chain.account} on ${network.name}; hireable: ${line}`);
+    log(`worker ${chain.account} on ${network.name}; hireable: ${line}${left === undefined ? "" : `; gas for ${deliveries(left)}`}`);
     if (sick)
         log(`warning: ${sick}`);
     if (once) {
@@ -428,12 +472,16 @@ async function run(network, { key, account }, values, once, mints) {
     log("waiting for tasks (Ctrl-C to stop)");
     // Minting waits on receipts from another chain, so it runs beside the work, one round at a time.
     let minting;
+    const hireChange = hireWatch(line, () => snapshot(chain).then((s) => hireable(s, network, "run"), () => undefined));
     while (!stop.stopping()) {
         await work.round().catch((error) => log(`round failed: ${reason(error)}`));
         minting ??= settlements
             .round()
             .catch((error) => log(`settlement round failed: ${reason(error)}`))
             .finally(() => (minting = undefined));
+        const changed = stop.stopping() ? undefined : await hireChange();
+        if (changed !== undefined)
+            log(`hireable: ${changed}`);
         if (quietFor() >= HEARTBEAT_MS && !work.busy() && !stop.stopping()) {
             log(`still waiting for tasks; hireable: ${await snapshot(chain).then((s) => hireable(s, network, "run"), (error) => `could not check (${reason(error)})`)}`);
         }
@@ -443,6 +491,26 @@ async function run(network, { key, account }, values, once, mints) {
     await minting;
     log("stopped");
 }
+/**
+ * Reads again, every few minutes until the worker can be hired, whether it can,
+ * and returns the new answer when it changed. A run started while Jev decides
+ * on the application then says when Jev allows the worker, and when its
+ * timelock has passed.
+ */
+export function hireWatch(first, check, everyMs = HIREABLE_CHECK_MS, now = Date.now) {
+    let last = first;
+    let checkedAt = now();
+    return async () => {
+        if (last === "yes" || now() - checkedAt < everyMs)
+            return undefined;
+        checkedAt = now();
+        const line = await check();
+        if (line === undefined || line === last)
+            return undefined;
+        last = line;
+        return line;
+    };
+}
 /** Run's log, with each line's time, and how long it has been quiet, so an idle run can say it is still there. */
 export function timedLog(write, now = Date.now) {
     let last = now();
@@ -454,6 +522,41 @@ export function timedLog(write, now = Date.now) {
         quietFor: () => now() - last,
     };
 }
+/** The task id and amount a bond command names, or what is wrong with them. */
+export function bondArgs(positional) {
+    const [first, second] = positional;
+    const taskId = (value, usage) => {
+        if (value === undefined || !/^[1-9]\d{0,17}$/.test(value))
+            throw new UsageError(usage);
+        return BigInt(value);
+    };
+    if (first === "status" || first === "claim")
+        return { action: first, task: taskId(second, `Usage: brainchain-worker bond ${first} <task>, such as bond ${first} 12`) };
+    const task = taskId(first, "Usage: brainchain-worker bond <task> <USDG>, such as bond 12 5, or bond status <task>, or bond claim <task>");
+    if (second === undefined || !/^\d{1,9}(\.\d{1,6})?$/.test(second) || Number(second) <= 0) {
+        throw new UsageError("The amount is in USDG, above zero with at most 6 decimals, such as bond 12 5");
+    }
+    return { action: "bond", task, amount: parseUnits(second, 6) };
+}
+async function bondCommand(network, positional, yes) {
+    const args = bondArgs(positional);
+    const config = network.proofs.bonds;
+    const chain = createBondChain(network, config ?? { registry: zeroAddress, check: zeroAddress, usdg: zeroAddress }, signer().account);
+    if (args.action !== "bond")
+        return (args.action === "status" ? bondStatus : bondClaim)(network, config, chain, args.task, console.log);
+    const ask = process.stdin.isTTY
+        ? async (question) => {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            try {
+                return await rl.question(question);
+            }
+            finally {
+                rl.close();
+            }
+        }
+        : undefined;
+    return bond(network, config, chain, args.task, { amount: args.amount, yes, ...(ask ? { ask } : {}), log: console.log });
+}
 /** Where watch --once keeps its place: a key's place counts toward its watchtower mark, so each key has its own, apart from runs without one. */
 export const watchPlace = (log, key) => (key === undefined ? log : `${log}.${key}`);
 /** What watch says at start. Without a key it names no address: the one its reads go through is a throwaway. */
@@ -496,6 +599,8 @@ export async function main(argv) {
     if (command === "claim") {
         return claim(network, (income) => createIncome(network.proofs, income, signer().account), { dry: switches.has("dry"), log: console.log });
     }
+    if (command === "bond")
+        return bondCommand(network, positional, switches.has("yes"));
     if (command === "mint") {
         const count = values.get("count");
         if (count !== undefined && !(/^\d{1,2}$/.test(count) && Number(count) >= 1 && Number(count) <= MAX_MINT)) {
@@ -602,7 +707,7 @@ export async function main(argv) {
         return propose(network, createProposals(network, worker.account), call, uri, { dry: switches.has("dry"), log: console.log });
     }
     if (command === "run")
-        return run(network, worker, values, switches.has("once"), !switches.has("no-mint"));
+        return run(network, worker, values, switches.has("once"), switches.has("mint"));
     const chain = createChain(network, worker.account);
     switch (command) {
         case "join":

package/dist/dispute.js

@@ -1,8 +1,8 @@
 import { createPublicClient, createWalletClient, encodeFunctionData, formatUnits, parseAbi } from "viem";
 import { erc20Errors, transferErrors } from "./abi.js";
-import { appealAbi, brainchainTransport, erc20Abi, explainRevert, reason, RECEIPT_MS, Status } from "./chain.js";
+import { appealAbi, brainchainTransport, erc20Abi, explainRevert, faucetReopens, reason, RECEIPT_MS, Status } from "./chain.js";
 import { chainOf } from "./network.js";
-import { ethNeeded, shortOfGas } from "./standing.js";
+import { ethNeeded, GAS, shortOfGas } from "./standing.js";
 /** TaskBoard statuses from set 3.5.0 on: a ruling that waits out its appeal window, and one under appeal. */
 export const { Ruled, Appealed } = Status;
 const boardAbi = [
@@ -55,7 +55,23 @@ export function createDisputeChain(network, account) {
         appealOf: (id) => client.readContract({ ...board, functionName: "appealOf", args: [id] }),
         appealBond: (id) => client.readContract({ ...board, functionName: "appealBond", args: [id] }),
         bountyBalance: () => client.readContract({ ...token, functionName: "balanceOf", args: [account.address] }),
+        async bountyFaucet() {
+            const [amount, interval, last] = await Promise.all([
+                client.readContract({ ...token, functionName: "FAUCET_AMOUNT" }),
+                client.readContract({ ...token, functionName: "FAUCET_INTERVAL" }),
+                client.readContract({ ...token, functionName: "lastClaim", args: [account.address] }),
+            ]);
+            return { amount, opensAt: last === 0n ? 0n : last + interval };
+        },
+        async claimBounty() {
+            const hash = await wallet.writeContract({ ...token, functionName: "faucet" });
+            const receipt = await client.waitForTransactionReceipt({ hash, timeout: RECEIPT_MS });
+            if (receipt.status !== "success")
+                throw new Error(`The faucet claim ${hash} reverted`);
+            return hash;
+        },
         ethBalance: () => client.getBalance({ address: account.address }),
+        sent: () => client.getTransactionCount({ address: account.address }),
         gasPrice: () => client.getGasPrice(),
         allowance: () => client.readContract({ ...token, functionName: "allowance", args: [account.address, board.address] }),
         async approveBounty(amount) {
@@ -110,14 +126,41 @@ export async function appeal(network, chain, id, log) {
     const closes = terms.ruledAt + terms.window;
     if (now > closes)
         throw new Error(`The appeal window for task ${id} closed at ${at(closes)}.`);
-    const [bond, balance, eth, gasPrice, allowance] = await Promise.all([chain.appealBond(id), chain.bountyBalance(), chain.ethBalance(), chain.gasPrice(), chain.allowance()]);
+    const [bond, balance, eth, gasPrice, allowance, sent] = await Promise.all([
+        chain.appealBond(id),
+        chain.bountyBalance(),
+        chain.ethBalance(),
+        chain.gasPrice(),
+        chain.allowance(),
+        chain.sent(),
+    ]);
     const amount = `${formatUnits(bond, 6)} ${network.bountySymbol}`;
-    if (balance < bond)
-        throw new Error(`The appeal bond is ${amount}, and the worker holds ${formatUnits(balance, 6)}. Bridge more with \`npx brainchain-worker bridge --bounty <amount>\`.`);
-    // Checked for both transactions before either is sent: an approval alone spends gas and leaves the bond approved.
-    const need = ethNeeded(allowance < bond ? [APPROVE_GAS, APPEAL_GAS] : [APPEAL_GAS], gasPrice);
+    const holds = `The appeal bond is ${amount}, and this wallet holds ${formatUnits(balance, 6)}.`;
+    // Test USDG comes from its faucet, as tBRAIN does for join; only mainnet's USDG is bridged in.
+    const claims = balance < bond && network.bountyFaucet === true;
+    if (balance < bond && !claims)
+        throw new Error(`${holds} Bridge more with \`npx brainchain-worker bridge --bounty <amount>\`.`);
+    const closed = (opensAt) => new Error(`${holds} The ${network.bountySymbol} faucet allows one claim a day, and this wallet can claim again at ${at(opensAt)}` +
+        (opensAt > closes ? `, after the appeal window closes at ${at(closes)}.` : `. Run appeal again then, before the appeal window closes at ${at(closes)}.`));
+    if (claims) {
+        const faucet = await chain.bountyFaucet();
+        if (now < faucet.opensAt)
+            throw closed(faucet.opensAt);
+        if (balance + faucet.amount < bond)
+            throw new Error(`${holds} The faucet's ${formatUnits(faucet.amount, 6)} ${network.bountySymbol} a day would not make up the rest.`);
+    }
+    // Checked for every transaction before any is sent: an approval alone spends gas and leaves the bond approved.
+    const need = ethNeeded([...(claims ? [GAS.faucet] : []), ...(allowance < bond ? [APPROVE_GAS] : []), APPEAL_GAS], gasPrice);
     if (eth < need)
-        throw new Error(`${chain.account} holds ${shortOfGas(network, chain.account, eth, need, "the appeal")} Nothing was sent.`);
+        throw new Error(`${chain.account} holds ${shortOfGas(network, chain.account, eth, sent, need, "the appeal")} Nothing was sent.`);
+    if (claims) {
+        log(`Claiming ${network.bountySymbol} from the testnet faucet for the bond...`);
+        const claim = await chain.claimBounty().catch((error) => {
+            const opensAt = faucetReopens(error);
+            throw opensAt === undefined ? error : closed(opensAt);
+        });
+        log(`Claimed: ${claim}`);
+    }
     const approval = await chain.approveBounty(bond);
     const tx = await chain.appeal(id).catch((error) => {
         if (approval === undefined)

package/dist/key.js

@@ -13,7 +13,7 @@ export const keyConfigured = (env = process.env) => Boolean(env[HANDOFF] || env.
 function keyFileProblem(text) {
     if (text === "")
         return "is empty";
-    if (/^(0x)?[0-9a-fA-F]{64}$/.test(text))
+    if (/^(0x)?[0-9a-f]{64}$/i.test(text))
         return undefined;
     if (/[\r\n]/.test(text))
         return "holds more than one line";
@@ -21,7 +21,7 @@ function keyFileProblem(text) {
         return "holds a line in the form NAME=value";
     if (/^["'`]|["'`]$/.test(text))
         return "holds the key in quotes";
-    const hex = text.startsWith("0x") ? text.slice(2) : text;
+    const hex = text.replace(/^0x/i, "");
     if (/^[0-9a-fA-F]+$/.test(hex))
         return `holds ${hex.length} hex characters where a key has 64`;
     return "holds characters that are not hex digits";

package/dist/mint.js

@@ -272,7 +272,7 @@ export function createSettlementWatch(options) {
                 entry.told = true;
                 store.save();
                 return log(`task ${key}: no proof minted. ${funds.missing} It tries again every hour, without another line, until ${when(BigInt(until))}; ` +
-                    "an hour later the Proof goes to the public pool. Testnet Proofs earn no income, and `run --no-mint` turns minting off.");
+                    "an hour later the Proof goes to the public pool. Proofs earn no income, and `run` without `--mint` mints none.");
             }
             await chain.approve(funds.price);
             const { tokenId, tx } = await chain.mint();

package/dist/network.js

@@ -10,10 +10,13 @@ export const TESTNET = {
     explorer: "https://usebrainchain.com/testnet",
     stakeSymbol: "tBRAIN",
     bountySymbol: "tUSDG",
-    // The drip needs no browser, so an agent can fund itself; the faucet asks for a browser check and a Google account.
-    gas: (address) => "Ask the testnet gas drip first: `curl -X POST https://brain.testnet.usebrainchain.com/testnet/gas -H 'content-type: application/json' " +
-        `-d '{"address":"${address}"}'\` sends 0.0001 ETH, enough to join, once per address. After that, get Robinhood Chain testnet ETH from ` +
-        "https://faucet.testnet.chain.robinhood.com and move it here with `npx brainchain-worker bridge --eth 0.001`",
+    bountyFaucet: true,
+    gas: "Get Robinhood Chain testnet ETH from https://faucet.testnet.chain.robinhood.com, which asks for a browser check and a Google account, " +
+        "so a person claims it, and move it here with `npx brainchain-worker bridge --eth 0.001`",
+    drip: {
+        wei: 100000000000000n,
+        request: (address) => `\`curl -X POST https://brain.testnet.usebrainchain.com/testnet/gas -H 'content-type: application/json' -d '{"address":"${address}"}'\``,
+    },
     proofs: {
         chainId: 46630,
         name: "Robinhood Chain testnet",
@@ -63,7 +66,7 @@ export const MAINNET = {
     explorer: "https://usebrainchain.com",
     stakeSymbol: "BRAIN",
     bountySymbol: "USDG",
-    gas: () => "Send this address ETH on Robinhood Chain, then move it here with `npx brainchain-worker bridge --eth 0.001`",
+    gas: "Send this address ETH on Robinhood Chain, then move it here with `npx brainchain-worker bridge --eth 0.001`",
     buyStake: "Buy BRAIN on Robinhood Chain at ripples.run (https://ripples.run/t/0xa06e3D898Bce92F67617E0Bfb640F153A5b65AB7) and move it to BrainChain with " +
         `brainchain-worker bridge --stake <amount> (docs: https://docs.usebrainchain.com/bridging); the stake token on BrainChain is ${BRAIN}.`,
     proofs: {
@@ -75,6 +78,12 @@ export const MAINNET = {
         weth: "0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73",
         gas: "Send it a little ETH there for gas",
         income: "0xeb1b4168D4b87D3d9F0D64E13B7071251BBB63b7",
+        // Shipped's registry and StaticCallCheck. The ProofIndex is named here once it is deployed; until then bonds are closed.
+        bonds: {
+            registry: "0xD5Da523ee49CB7Fe855B0C6fa38707190A9D531F",
+            check: "0x2e7C4F0F2e6079C3B5F7Cd2440308234CBDc537D",
+            usdg: "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
+        },
     },
     identity: "0x8004A169FB4a3325136EB29fA0ceB6D2e539a432",
     priors: { pool: "0x281210097f0de7A8FB6F87310AF0f089c9C8DE21", root: 20423n },

package/dist/proc.js

@@ -0,0 +1,34 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+/** One field of `ps` for a process, or undefined when it is gone or ps cannot tell. */
+export function ps(pid, field) {
+    const result = spawnSync("ps", ["-o", `${field}=`, "-p", String(pid)], { encoding: "utf8" });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}
+/**
+ * When a Linux process started, from /proc, which slim container images have
+ * without ps. The kernel counts it in ticks since boot, 100 a second on every
+ * architecture Node.js runs on.
+ */
+function procStart(pid) {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+        const ticks = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19]);
+        const boot = Number(/^btime (\d+)$/m.exec(readFileSync("/proc/stat", "utf8"))?.[1]);
+        return Number.isSafeInteger(ticks) && boot > 0 ? boot * 1000 + ticks * 10 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** When a process started, in ms since the epoch, or undefined when it is gone or neither /proc nor ps can tell. */
+export function startTime(pid) {
+    const started = procStart(pid);
+    if (started !== undefined)
+        return started;
+    const elapsed = /^(?:(?:(\d+)-)?(\d+):)?(\d+):(\d+)$/.exec(ps(pid, "etime") ?? "");
+    if (!elapsed)
+        return undefined;
+    const [days, hours, minutes, seconds] = elapsed.slice(1).map((part) => Number(part ?? 0));
+    return Date.now() - (((days * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000;
+}

package/dist/propose.js

@@ -2,7 +2,7 @@ import { BaseError, createPublicClient, createWalletClient, decodeErrorResult, d
 import { erc20Errors } from "./abi.js";
 import { bondsAbi, brainchainTransport, erc20Abi, executorAbi, RECEIPT_MS } from "./chain.js";
 import { chainOf } from "./network.js";
-import { stake, when } from "./standing.js";
+import { gasHelp, stake, when } from "./standing.js";
 /** Every call the executor can be asked to make, by the contract it calls. */
 export const GOVERNED = {
     board: parseAbi([
@@ -198,6 +198,7 @@ export function createProposals(network, account) {
         account: account.address,
         now: async () => (await client.getBlock()).timestamp,
         ethBalance: () => client.getBalance({ address: account.address }),
+        sent: () => client.getTransactionCount({ address: account.address }),
         stakeBalance: () => client.readContract({ address: stakeToken, abi: erc20Abi, functionName: "balanceOf", args: [account.address] }),
         bond: () => client.readContract({ ...proposals, functionName: "bond" }),
         decideWithin: () => client.readContract({ ...proposals, functionName: "decideWithin" }),
@@ -303,7 +304,7 @@ export async function propose(network, chain, call, uri, options) {
         throw new Error(`The wallet holds ${stake(network, balance)} of the ${stake(network, bond)} bond.${buy}`);
     }
     if (gas === 0n)
-        throw new Error(`${chain.account} has no ETH on ${network.name} for gas. ${network.gas(chain.account)}.`);
+        throw new Error(`${chain.account} has no ETH on ${network.name} for gas. ${gasHelp(network, chain.account, 0n, await chain.sent())}.`);
     log(`Bonding ${stake(network, bond)} and proposing...`);
     const { id, tx } = await chain.propose(call, uri, bond);
     log(`Proposal ${id} is waiting for Jev (${tx}). Follow it with \`npx brainchain-worker proposal ${id}\`.`);

package/dist/standing.js

@@ -1,7 +1,7 @@
 import { formatEther, formatUnits } from "viem";
 import { ApplicationState, Status } from "./chain.js";
 /** A token amount with thousands separators, such as 1,250,000; a fraction is kept as it is. */
-function grouped(amount, decimals) {
+export function grouped(amount, decimals) {
     const [whole, fraction] = formatUnits(amount, decimals).split(".");
     return `${whole.replace(/\B(?=(\d{3})+$)/g, ",")}${fraction === undefined ? "" : `.${fraction}`}`;
 }
@@ -27,7 +27,7 @@ export async function snapshot(chain) {
     };
 }
 /** The highest gas limit seen for each transaction join can send, across testnet and mainnet. */
-const GAS = { faucet: 76000n, approve: 50000n, stake: 120000n, setPrice: 31000n, apply: 240000n };
+export const GAS = { faucet: 76000n, approve: 50000n, stake: 120000n, setPrice: 31000n, apply: 240000n };
 /** The highest gas limit seen for delivering a result. */
 const SUBMIT_GAS = 104000n;
 /**
@@ -105,13 +105,42 @@ export function wallet(network, s, balance, bond, faucet, now) {
     const buy = network.buyStake ? `. ${network.buyStake}` : "";
     return `${has}; join needs ${stake(network, need)}${reopens}${unstaking}${buy}`;
 }
+/**
+ * Where a wallet gets ETH for gas, given what it holds and how many
+ * transactions it has sent. The drip serves an address once and turns away one
+ * that holds a drip's worth, so only a wallet that has sent nothing and holds
+ * less is sure to get it; any other is sent to the faucet.
+ */
+export function gasHelp(network, address, gas, sent) {
+    const { drip } = network;
+    if (!drip)
+        return network.gas;
+    if (sent > 0 || gas >= drip.wei)
+        return `${network.gas}. The gas drip serves each address once`;
+    const after = `${network.gas[0].toLowerCase()}${network.gas.slice(1)}`;
+    return `Ask the testnet gas drip first: ${drip.request(address)} sends ${formatEther(drip.wei)} ETH, enough to join, once per address. After that, ${after}`;
+}
 /** What a wallet short of gas holds and needs, for join's refusal and for `status`. */
-export const shortOfGas = (network, address, gas, need, purpose) => `${formatEther(gas)} ETH on ${network.name}; ${purpose} needs about ${aboutEth(need)} ETH for gas. ${network.gas(address)}.`;
-/** The wallet's ETH, and what more join or the next delivery needs, since a send the wallet cannot cover fails partway through. */
-export function gasLine(network, address, s, gas, gasPrice, claims) {
+export const shortOfGas = (network, address, gas, sent, need, purpose) => `${formatEther(gas)} ETH on ${network.name}; ${purpose} needs about ${aboutEth(need)} ETH for gas. ${gasHelp(network, address, gas, sent)}.`;
+/** How many results the wallet's ETH delivers at this gas price, the last of them at the fee cap the RPC checks. */
+export function deliveriesLeft(gas, gasPrice) {
+    const price = gasPrice > 0n ? gasPrice : 1n;
+    const last = ethNeeded([SUBMIT_GAS], price);
+    return gas < last ? 0n : (gas - last) / (SUBMIT_GAS * price) + 1n;
+}
+/** About how many results the wallet's ETH delivers, for `status` and `run`. */
+export const deliveries = (count) => `about ${count} ${count === 1n ? "delivery" : "deliveries"}`;
+/**
+ * The wallet's ETH, and what more join or the next delivery needs, since a
+ * send the wallet cannot cover fails partway through. A worker with nothing to
+ * join hears how many results its ETH delivers.
+ */
+export function gasLine(network, address, s, gas, gasPrice, claims, sent) {
     const limits = joinLimits(s, claims, false);
     const need = ethNeeded(limits.length > 0 ? limits : [SUBMIT_GAS], gasPrice);
-    return gas >= need ? `${formatEther(gas)} ETH` : shortOfGas(network, address, gas, need, limits.length > 0 ? "join" : "delivering a result");
+    if (gas < need)
+        return shortOfGas(network, address, gas, sent, need, limits.length > 0 ? "join" : "delivering a result");
+    return limits.length > 0 ? `${formatEther(gas)} ETH` : `${formatEther(gas)} ETH, enough for ${deliveries(deliveriesLeft(gas, gasPrice))} at the current gas price`;
 }
 /** What join says when the wallet holds too little of a stake token that has no faucet. */
 export function shortOfStake(network, w, balance, need, now) {

package/dist/state.js

@@ -2,6 +2,7 @@ import { randomBytes } from "node:crypto";
 import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, readlinkSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { dirname, join } from "node:path";
+import { startTime } from "./proc.js";
 export const stateDir = () => join(homedir(), ".config", "brainchain-worker");
 /** The decision count a one-shot watch run stopped at, kept per decision log; undefined when there is none or it cannot be read. */
 export function readWatched(log, dir = stateDir()) {
@@ -113,6 +114,8 @@ const LOCK_STALE_MS = 15_000;
 const LOCK_WATCH_MS = 7_000;
 /** A takeover takes a few system calls, so one marker older than this was left by a crash. */
 const TAKEOVER_STALE_MS = 5_000;
+/** How far a start time read from ps, which gives it to the second, can fall after the true one. */
+const START_SLACK_MS = 2_000;
 /**
  * Where a pid means something. Containers sharing a config folder each have
  * their own numbering, so a holder's pid says nothing outside its own space.
@@ -170,14 +173,27 @@ function holderOf(text) {
     }
     return { pid: 0, space: "" };
 }
+/**
+ * Whether the run that wrote a bare-pid lock is still going. 0.12 and earlier
+ * wrote the pid once and never touched the file again, so the lock's age says
+ * nothing. A process that started after the lock was written, as pid 1 does
+ * when a container restarts, has only come to reuse the pid.
+ */
+function bareHeld(pid, writtenAt) {
+    if (!alive(pid))
+        return false;
+    const started = startTime(pid);
+    return started === undefined || started <= writtenAt + START_SLACK_MS;
+}
 /** Whether the run that wrote a lock is still going. */
 function isHeld(file, { pid, space }, watchMs) {
     const touched = touchedAt(file);
-    if (touched === undefined || Date.now() - touched >= LOCK_STALE_MS)
+    if (touched === undefined)
         return false;
-    // A bare pid was written in this PID namespace or one gone since, so after a restart a live pid can be another process.
     if (space === undefined)
-        return alive(pid);
+        return bareHeld(pid, touched);
+    if (Date.now() - touched >= LOCK_STALE_MS)
+        return false;
     if (pid === 0)
         return true;
     if (space === pidSpace())

package/dist/work.js

@@ -2,6 +2,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { toBytes } from "viem";
 import { fetchBrief, PermanentError, reason, RECEIPT_MS } from "./chain.js";
+import { ps, startTime } from "./proc.js";
 import { memoryStore } from "./state.js";
 /** The most the service accepts for one result. */
 export const MAX_RESULT_BYTES = 100_000;
@@ -17,6 +18,19 @@ const ANSI = /\x1b(?:\[[0-?]*[ -\/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\)|[@-Z\\-_
 export const stripAnsi = (text) => text.replace(ANSI, "");
 /** Characters that show nothing or turn the text around them, so text that holds them can read as other text. */
 export const HIDDEN = /[\u00ad\u061c\u180e\u200b\u200e\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/;
+/**
+ * What a worker's name and description may not hold: control, format and
+ * separator characters, and the default-ignorable code points Unicode files
+ * as letters or marks, which no property escape reaches, plus the blank
+ * braille pattern. Each shows nothing, breaks the line or turns the text
+ * around, so a name that holds one can read as another.
+ */
+const UNSEEN = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}͏ᅟᅠ឴឵᠋-᠏⁥⠀ㅤ︀-️ﾠ￰-￸\u{e0000}-\u{e0fff}]/u;
+/** The first character of `text` that UNSEEN refuses, as U+XXXX, or undefined when there is none. */
+export function unseen(text) {
+    const found = UNSEEN.exec(text)?.[0];
+    return found === undefined ? undefined : `U+${found.codePointAt(0).toString(16).toUpperCase().padStart(4, "0")}`;
+}
 /** Text from strangers, made safe to print as one terminal line. */
 export const printable = (text) => stripAnsi(text)
     .replace(/[\t\n\r]+/g, " ")
@@ -96,19 +110,6 @@ function signalGroup(pid, signal) {
             throw error;
     }
 }
-/** One field of `ps` for a process, or undefined when it is gone or ps cannot tell. */
-function ps(pid, field) {
-    const result = spawnSync("ps", ["-o", `${field}=`, "-p", String(pid)], { encoding: "utf8" });
-    return result.status === 0 ? result.stdout.trim() : undefined;
-}
-/** When a process started, in ms since the epoch, or undefined when it is gone or ps cannot tell. */
-function startTime(pid) {
-    const elapsed = /^(?:(?:(\d+)-)?(\d+):)?(\d+):(\d+)$/.exec(ps(pid, "etime") ?? "");
-    if (!elapsed)
-        return undefined;
-    const [days, hours, minutes, seconds] = elapsed.slice(1).map((part) => Number(part ?? 0));
-    return Date.now() - (((days * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000;
-}
 function exists(pid) {
     try {
         process.kill(pid, 0);
@@ -359,7 +360,8 @@ export function createWork(options) {
     };
     const needGas = async () => {
         if ((await chain.ethBalance()) === 0n) {
-            throw new Error(`The wallet has no ETH to pay gas for the submit${options.gasHelp ? `. ${options.gasHelp}` : ""}. The task is tried again`);
+            const help = await options.gasHelp?.().catch(() => undefined);
+            throw new Error(`The wallet has no ETH to pay gas for the submit${help ? `. ${help}` : ""}. The task is tried again`);
         }
     };
     const inTime = async (task) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-worker",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Earn on BrainChain and propose changes to it: stake, apply, do the tasks Jev hires your agent for, and bond BRAIN to put a change to Jev.",
   "license": "MIT",
   "author": "BrainChain <hello@usebrainchain.com>",
@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "brainchain-verify": "^0.4.0",
-    "viem": "^2.0.0"
+    "viem": "^2.57.12"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",