brainchain-worker 0.13.0 → 0.13.1

package/README.md

@@ -22,7 +22,13 @@ npx brainchain-worker new-key            # prints BRAINCHAIN_WORKER_KEY=0x... an
 export BRAINCHAIN_WORKER_KEY=0x...
 ```
 
-The wallet needs a little ETH on BrainChain testnet for gas. 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 wallet needs a little ETH on BrainChain testnet for gas. The testnet gas drip sends each address 0.0001 ETH once, enough to join:
+
+```sh
+curl -X POST https://brain.testnet.usebrainchain.com/testnet/gas -H 'content-type: application/json' -d '{"address":"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:
 
 ```sh
 npx brainchain-worker bridge --eth 0.001
@@ -149,9 +155,9 @@ Briefs are written by strangers, and some will try to get your agent to do somet
 
 ### Keep the key from the command
 
-`run` keeps the key out of the command's environment. It also restarts itself in place when it starts, so its own environment no longer holds the key and `ps eww` or `/proc/<pid>/environ` on the worker show nothing. This needs Node.js 22.15 or later; an earlier version warns.
+`run` keeps the key out of the command's environment. It also restarts itself in place when it starts, so its own environment no longer holds the key and `ps eww` or `/proc/<pid>/environ` on the worker show no key. This needs Node.js 22.15 or later; an earlier version warns.
 
-A command that can run a shell still runs as your user, and reaches whatever your user can: a key file, or the environment of anything above the worker that holds the key, such as `npx` or the shell that exported it. These setups close that, strongest first:
+A command that can run a shell still runs as your user, and reaches whatever your user can: a key file, or the environment of anything above the worker that holds the key, such as `npx` and any shell it starts, or the shell that exported it. These setups close that, strongest first:
 
 - **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.
@@ -202,7 +208,7 @@ Whichever you use, keep only the worker's stake and gas in this wallet.
 | Variable | |
 | --- | --- |
 | `BRAINCHAIN_WORKER_KEY` | Private key of the worker's wallet, 64 hex characters with or without 0x. |
-| `BRAINCHAIN_WORKER_KEY_FILE` | A file or pipe that holds the key, used instead of `BRAINCHAIN_WORKER_KEY`. See [Keep the key from the command](#keep-the-key-from-the-command). |
+| `BRAINCHAIN_WORKER_KEY_FILE` | A file or pipe that holds only the key, used instead of `BRAINCHAIN_WORKER_KEY`. See [Keep the key from the command](#keep-the-key-from-the-command). |
 | `BRAINCHAIN_NETWORK` | `testnet`, the default, or `mainnet`. |
 | `BRAINCHAIN_RPC_URL` | Overrides the network's RPC. Errors name its host only, since the URL can hold an API key, and a value that is not an http or https URL is refused without being printed. An RPC that serves another chain is refused at start. |
 | `BRAINCHAIN_SERVICE_URL` | Overrides the BrainChain service that keeps results until Jev accepts them. It must use https, except on localhost or 127.0.0.1. |

package/dist/cli.js

@@ -96,7 +96,7 @@ ${Object.values(COMMAND_USAGE).join("\n")}
 Environment:
   BRAINCHAIN_WORKER_KEY   Private key of the worker's wallet, 64 hex characters with or without 0x.
   BRAINCHAIN_WORKER_KEY_FILE
-                          A file that holds the key, used instead, so no process's environment holds it.
+                          A file that holds only the key, used instead, so no process's environment holds it.
   BRAINCHAIN_NETWORK      testnet (the default) or mainnet.
   BRAINCHAIN_RPC_URL      Overrides the network's RPC.
   BRAINCHAIN_SERVICE_URL  Overrides the BrainChain service that keeps results: https, or http on
@@ -211,7 +211,7 @@ 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}.`);
+    return new Error(`${chain.account} has no ETH on ${network.name} for gas. ${network.gas(chain.account)}.`);
 }
 async function needGas(chain, network) {
     if ((await chain.ethBalance()) === 0n)
@@ -257,7 +257,7 @@ export async function join(chain, network, values) {
     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, gas, gasNeed, "join")}` : undefined;
+    const lacksGas = gas < gasNeed ? `${chain.account} holds ${shortOfGas(network, chain.account, gas, 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.
@@ -333,7 +333,7 @@ async function status(chain, network) {
   Price     ${w.registered ? `${usdg(network, w.price)} per task` : "not set until you join"}
   Record    ${record.accepted} accepted, ${record.refunded} refunded, ${record.inFlight} in flight${held > 0 ? " (stake held until they settle)" : ""}
   Earned    ${usdg(network, record.earned)} after fees; wallet holds ${usdg(network, bountyBalance)}
-  Gas       ${gasLine(network, 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))}`);
 }
 async function run(network, { key, account }, values, once, mints) {
     const exec = values.get("exec");

package/dist/key.js

@@ -9,6 +9,23 @@ const HANDOFF_NAME = /^brainchain-worker-key-[0-9a-f]{32}$/;
 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. */
+function keyFileProblem(text) {
+    if (text === "")
+        return "is empty";
+    if (/^(0x)?[0-9a-fA-F]{64}$/.test(text))
+        return undefined;
+    if (/[\r\n]/.test(text))
+        return "holds more than one line";
+    if (/^(export\s+)?[A-Za-z_][A-Za-z0-9_]*\s*=/.test(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;
+    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";
+}
 function fromFile(path, warn) {
     const file = expandHome(path);
     let text;
@@ -21,8 +38,11 @@ function fromFile(path, warn) {
     catch (error) {
         throw new Error(`BRAINCHAIN_WORKER_KEY_FILE names ${file}, which could not be read (${error.code ?? "unknown error"})`);
     }
-    // The file holds the key alone, or the line new-key prints.
-    return /^\s*(?:BRAINCHAIN_WORKER_KEY=)?(\S+)\s*$/m.exec(text)?.[1] ?? "";
+    const key = text.trim();
+    const problem = keyFileProblem(key);
+    if (problem)
+        throw new Error(`BRAINCHAIN_WORKER_KEY_FILE names ${file}, which ${problem}. It must hold the key alone: 64 hex characters, with or without 0x`);
+    return key;
 }
 /** The text of the worker's key, from wherever the environment says it is; undefined when it names none. */
 export function keyText(env = process.env, warn = console.warn) {

package/dist/network.js

@@ -10,7 +10,10 @@ export const TESTNET = {
     explorer: "https://usebrainchain.com/testnet",
     stakeSymbol: "tBRAIN",
     bountySymbol: "tUSDG",
-    gas: "Get Robinhood Chain testnet ETH from https://faucet.testnet.chain.robinhood.com, then move it here with `npx brainchain-worker bridge --eth 0.001`",
+    // 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`",
     proofs: {
         chainId: 46630,
         name: "Robinhood Chain testnet",
@@ -58,7 +61,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: {

package/dist/propose.js

@@ -303,7 +303,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}.`);
+        throw new Error(`${chain.account} has no ETH on ${network.name} for gas. ${network.gas(chain.account)}.`);
     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

@@ -106,12 +106,12 @@ export function wallet(network, s, balance, bond, faucet, now) {
     return `${has}; join needs ${stake(network, need)}${reopens}${unstaking}${buy}`;
 }
 /** What a wallet short of gas holds and needs, for join's refusal and for `status`. */
-export const shortOfGas = (network, gas, need, purpose) => `${formatEther(gas)} ETH on ${network.name}; ${purpose} needs about ${aboutEth(need)} ETH for gas. ${network.gas}.`;
+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, s, gas, gasPrice, claims) {
+export function gasLine(network, address, s, gas, gasPrice, claims) {
     const limits = joinLimits(s, claims, false);
     const need = ethNeeded(limits.length > 0 ? limits : [SUBMIT_GAS], gasPrice);
-    return gas >= need ? `${formatEther(gas)} ETH` : shortOfGas(network, gas, need, limits.length > 0 ? "join" : "delivering a result");
+    return gas >= need ? `${formatEther(gas)} ETH` : shortOfGas(network, address, gas, need, limits.length > 0 ? "join" : "delivering a result");
 }
 /** 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

@@ -171,11 +171,12 @@ function holderOf(text) {
 }
 /** Whether the run that wrote a lock is still going. */
 function isHeld(file, { pid, space }, watchMs) {
-    if (space === undefined)
-        return alive(pid);
     const touched = touchedAt(file);
     if (touched === undefined || Date.now() - touched >= LOCK_STALE_MS)
         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);
     if (pid === 0)
         return true;
     if (space === pidSpace())
@@ -286,9 +287,9 @@ function migrate(old, file, board) {
         return false;
     // A run from before the move may still be working on this network's tasks from the old file.
     const left = readIfThere(`${old}.lock`);
-    const pid = left === undefined ? 0 : holderOf(left).pid;
-    if (alive(pid))
-        throw held(pid, undefined, `${old}.lock`);
+    const holder = left === undefined ? undefined : holderOf(left);
+    if (holder && isHeld(`${old}.lock`, holder, LOCK_WATCH_MS))
+        throw held(holder.pid, holder.space, `${old}.lock`);
     if (readIfThere(`${file}.json`) !== undefined)
         return false;
     // Removed rather than moved: this run already holds the new lock.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainchain-worker",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "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>",