@toon-protocol/rig 4.6.0 → 5.0.0

package/README.md

@@ -9,7 +9,7 @@ lives in NIP-34 Nostr events and the objects live on Arweave.
 - **Writes are paid** — pushing objects and publishing events spends from a
   payment channel funded by your wallet. Writes are permanent and non-refundable.
 - **One node URL is the whole network configuration** — `rig` embeds its own
-  payment client (`@toon-protocol/client` 3.x) built from your seed phrase and
+  payment client (`@toon-protocol/client` 4.x) built from your seed phrase and
   pays the TOON connector you name with `rig entry <url>`. The node describes
   itself on `GET /ilp`; there is nothing to discover (see
   [Pointing at a node](#pointing-at-a-node)).
@@ -238,20 +238,27 @@ estimate — nothing is executed or paid).
 
 ## Money: fund, balance, channels
 
-Paid commands spend from a **payment channel** — an on-chain-collateralized channel
-between your wallet and a payment peer, from which each write draws an off-chain
-claim. You rarely touch this directly:
+Paid commands spend from a **payment channel**: an x402 `batch-settlement`
+channel between your wallet and the node, collateralized on chain, on which each
+write signs an off-chain voucher naming the running total (connector ADR 0075;
+there is no nonce). You rarely touch this directly:
 
 - **`rig fund`** tops up your wallet (devnet faucet, or prints addresses to fund
   externally). Both the native coin (gas) and USDC (collateral) are needed.
 - **`rig balance`** shows what your wallet holds across chains.
 - **Channels open lazily.** The first paid write opens a channel from your funded
-  wallet and records it under `~/.toon-client` (`rig-channels.json`); later writes
-  resume the same channel instead of opening a new one.
-- **`rig channel list`** (free) shows current holdings and nonce watermarks.
-  **`rig channel open`** pre-opens one (or `--deposit`s more collateral) using the
-  exact lazy-open path; **`rig channel close`** starts the settlement challenge
-  window; **`rig channel settle`** releases collateral once the window elapses.
+  wallet (on Solana the node sponsors the open: USDC for the deposit, no SOL) and
+  records it under `~/.toon-client` (`rig-channels-x402.json`); later writes
+  resume the same channel, and a write it can no longer cover opens a fresh one.
+- **`rig channel list`** (free) shows current holdings and the running totals
+  signed. **`rig channel open`** pre-opens one (or `--deposit`s more collateral,
+  Base only) using the exact lazy-open path; **`rig channel close`** starts the
+  exit window; **`rig channel settle`** releases collateral once the window
+  elapses.
+- **Upgrading from a client 3.x rig** (4.7.x and earlier): its toon-channel
+  files (`rig-channels.json`, `channels.json`) are never read or written, only
+  named. A current connector refuses those claims; take their deposits back
+  with the rig that opened them.
 
 The `open`/`close`/`settle` lifecycle commands are on-chain wallet operations (gas +
 collateral movement), so they follow the same confirm idiom as `push`: they print
@@ -459,10 +466,58 @@ rig ci serve --relay wss://<relay> --repo <owner-npub>/<repo-id> [--repo …]
 | `--gateway <url>` | `RIG_ARWEAVE_GATEWAY`, else rig's preferred Arweave gateway | the gateway that serves the store's raw bytes: prefix for log/artifact URLs (`<gateway>/raw/<txId>`) **and** the first gateway the coordinator reads a commit's objects from (same `/raw/` route), ahead of the shared public list — name a private or local gateway (the sandbox's) and the coordinator needs nothing else to read |
 | `--act-bin <path>` | `act` on PATH (or `RIG_ACT_BIN`) | the act binary |
 | `--platform <label>=<image>` | `ubuntu-latest=catthehacker/ubuntu:act-latest` | `runs-on` label → Docker image (repeatable) |
+| `--pull` / `--no-pull` | act's default (pull before each run) | whether act pulls the runner image named by `--platform` before each run |
 | `--workdir <dir>` | `<state-dir>/work` | where commits are materialized |
 | `--once` | | stop after the first run concludes (its 9842 and final 39842 are on the relay) — one `rig ci trigger` answered by one bounded serve; ignored or refused triggers do not count |
 | `--json` | | one JSON document with the coordinator, relay, repos and state dir on start |
 
+**Two act behaviours decide whether a real workflow passes**, and a workflow
+whose steps only `echo` hides both:
+
+- **Write `actions/checkout@v4`, exactly as you would on GitHub.** act copies
+  the materialized tree into the job container *at that step*, not when the
+  container starts, and short-circuits it to a local `docker cp` — so the step
+  needs no network and no node in the image. A workflow without it
+  runs its tools against an **empty** container — the steps execute, the files
+  are not there:
+
+  ```
+  error: could not find `Cargo.toml` in `/…/work/<repo>-<sha>-1` or any parent directory
+  ```
+
+  That path is the checkout the coordinator materialized under `--workdir`
+  (`<repo-id>-<short sha>-<n>`), as the job container sees it.
+- **The default image is not GitHub's hosted runner.** `ubuntu-latest` maps to
+  `catthehacker/ubuntu:act-latest`, which carries no language toolchain, so a
+  workflow that expects a preinstalled `cargo`, `go` or JDK fails at its first
+  step. Either point `--platform` at an image that has one
+  (`--platform ubuntu-latest=rust:1-bookworm`) or install it in a step. The
+  official `rust` images ship neither rustfmt nor clippy —
+  `rustup component add rustfmt clippy` is a step, not a given — and an image
+  you built locally needs `--no-pull` (below).
+
+A workflow that survives both, run by a coordinator started with
+`--platform ubuntu-latest=rust:1-bookworm`:
+
+```yaml
+# .github/workflows/ci.yml
+name: ci
+on: [push]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4 # act resolves this to the local copy
+      - run: rustup component add rustfmt clippy
+      - run: cargo fmt --check
+      - run: cargo clippy -- -D warnings
+      - run: cargo test
+```
+
+A runner image built or loaded on the coordinator host and never pushed to a
+registry needs `--no-pull`: without it act force-pulls the image named by
+`--platform` and every run fails in *Set up job* with `pull access denied`.
+
 On start the coordinator publishes an **Advertisement** (19843: runner family
 `act`, its selectors, admission `maintainer-request`, execution
 `request-required`, billing `out-of-band`, and a fresh `secrets-key`) and renews
@@ -510,9 +565,10 @@ docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v rig-ci-state:/st
 The entrypoint is `rig`, so every verb works (`docker run --rm rig-ci --version`),
 and every environment variable rig honours means the same inside the image
 (`TOON_CLIENT_HOME` is `/state`). act launches each job as a container on the
-daemon behind the mounted socket and copies the checkout in, so no host path
-has to match. Against the [sandbox](#dogfooding-rigs-own-ciyml-on-the-sandbox)
-on the same host, run on the host network with the sandbox's own `localhost`
+daemon behind the mounted socket and copies the checkout in at the
+`actions/checkout` step, so no host path has to match. Against the
+[sandbox](#dogfooding-rigs-own-ciyml-on-the-sandbox) on the same host, run on
+the host network with the sandbox's own `localhost`
 addresses — a client dials the endpoint a node **advertises**, and the sandbox
 hub advertises `http://127.0.0.1:3200/ilp` so host-run smokes can reach it
 (sandbox-only; a real connector advertises its public URL, which the default
@@ -565,6 +621,11 @@ git commit --allow-empty -m 'ci: dogfood' && rig push --yes
 rig ci status HEAD --json | jq .summary
 ```
 
+`RIG_ARWEAVE_GATEWAY` in that common env also steers the READ path: `rig clone`
+and `rig fetch` try `http://localhost:3000/raw/<txId>` first, so a repo pushed to
+the sandbox clones back out of it even though the public gateways never see those
+objects (see [Reading through your own gateway](#reading-through-your-own-gateway)).
+
 The same flow, end to end and asserted, is
 `src/__integration__/ci-sandbox.integration.test.ts`; it runs only with
 `RIG_CI_SANDBOX=1` and skips itself unless the sandbox's relay, hub, store edge
@@ -583,7 +644,7 @@ network — there is no announce to discover (kind:10032 was removed by connecto
 ADR 0046) and no topology to negotiate.
 
 ```sh
-curl -s https://proxy.relay.devnet.toonprotocol.dev/ilp | jq '{ilpAddresses, routes, settlements: [.settlements[].chain]}'
+curl -s https://proxy.relay.devnet.toonprotocol.dev/ilp | jq '{ilpAddresses, routes, batchSettlements: [.batchSettlements[].network]}'
 ```
 
 What rig derives from it, and the knob that overrides each:
@@ -594,16 +655,17 @@ What rig derives from it, and the knob that overrides each:
 | where events go | the node's first own address it also prices | `TOON_CLIENT_PUBLISH_DESTINATION` / `publishDestination` |
 | where git objects go | the node's first priced `*.store` route, else `*.ario` | `TOON_CLIENT_STORE_DESTINATION` / `storeDestination`; `rig name --via` per invocation |
 | a store on another node | — | `storeConnectorUrl` (that node holds its own channel: uploads ride a second client and watermark) or `storeSealTo` (same channel, sealed to that node) |
-| settlement chain | the first chain in `settlements[]` your identity holds a key for | `TOON_CLIENT_CHAIN` / `chain` — `evm` or `solana` (`evm:8453` is read by its family) |
+| settlement chain | the first chain in `batchSettlements[]` your identity holds a key for (a phrase holds both: name one) | `TOON_CLIENT_CHAIN` / `chain`: `evm` or `solana` (`evm:8453` is read by its family) |
 | chain RPC | the client's devnet preset | `TOON_CLIENT_RPC_URL` / `rpcUrl` / `chainRpcUrls[<chain>]` — **set this for a mainnet node** |
 | who pays | the phrase's key on that chain | `RIG_SOLANA_KEY_FILE` / `solanaKeyFile` (a `solana-keygen` JSON), `RIG_EVM_PRIVATE_KEY` / `evmPrivateKey` |
-| claim watermark file | `<TOON_CLIENT_HOME>/channels.json` | `TOON_CLIENT_CHANNEL_STORE` / `channelStorePath` — one file per channel writer, or two processes replay each other's nonces |
-| first-open collateral | the client default | `TOON_CLIENT_DEPOSIT` / `deposit` (base units) |
+| x402 channel store | `<TOON_CLIENT_HOME>/channels-x402.json` (+ `.peers.json`, each channel's config: keep both) | `TOON_CLIENT_CHANNEL_STORE` / `channelStorePath`: one file per channel writer, or two processes race each other's running totals. A client 3.x store is refused |
+| channel collateral | the client default (Solana: at least the node's `minDeposit`) | `TOON_CLIENT_DEPOSIT` / `deposit` (base units) |
+| Base deposit facilitator | none on Solana; the client's own on EVM | `TOON_CLIENT_FACILITATOR_URL` / `facilitatorUrl` |
 | carriage | `auto` (HTTP unless the node requires BTP) | `TOON_CLIENT_TRANSPORT` / `transport` |
 
 **Prices are schedules.** A route publishes a base price and, when it meters by
 size, a `pricePerKib` (connector ADR 0065). `rig push`'s fee table prices every
-object by its sealed size with the same rule the client puts on the claim, so
+object by its sealed size with the same rule the client puts on the voucher, so
 the estimate equals what is paid.
 
 **Who pays and who signs are independent.** The repo owner is the phrase's
@@ -612,7 +674,7 @@ Its EVM wallet is that same key (the client's `keyDerivation: 'legacy'`, rig's
 default, so channels an existing identity funded are still its own); set
 `TOON_CLIENT_KEY_DERIVATION=standard` for a fresh identity you want to import
 into MetaMask. The payer key may be a different key entirely: the connector
-attributes payment from the claim, never from the event.
+attributes payment from the voucher, never from the event.
 
 ### Devnet
 
@@ -692,13 +754,13 @@ phrase itself is never printed and never written to git config or any repo file.
 ## What a paid command does first
 
 Every standalone paid command bootstraps the same way: resolve the identity,
-read the connector's `GET /ilp`, open or adopt the payment channel with that
-node, then sign one claim per packet. Adoption is free — a channel's id derives
-from its participants, so a node you have paid before is found again without a
-transaction. Money state (the claim watermark, the channel map) lives under
-`TOON_CLIENT_HOME` and is never cached away.
+read the connector's `GET /ilp`, open or resume the x402 channel with that
+node, then sign one voucher per packet. Resuming is free: the client keeps each
+channel's config in its store, so a node you have paid before is found again
+without a transaction. Money state (the voucher watermark, the channel configs,
+the channel map) lives under `TOON_CLIENT_HOME` and is never cached away.
 
-Two rig processes on one identity race the claim nonce, so a per-identity lock
+Two rig processes on one identity race the running total, so a per-identity lock
 refuses the second (`RIG_STANDALONE=1` skips only the check for a same-identity
 `toon-clientd`; the lock stays). The `rig` bin exits as soon as a command
 finishes and stdio is flushed.
@@ -774,6 +836,37 @@ clone never leaves a partial repo. `rig fetch [remote]` is the same pipeline as
 delta: only locally-missing objects are downloaded, and `refs/remotes/<remote>/*`
 (tags → `refs/tags/*`) move with a `git fetch`-style report.
 
+### Reading through your own gateway
+
+By default both commands read from rig's shared public gateway list. A repository
+whose objects live only on a **private, local or air-gapped** gateway is invisible
+there — so `--gateway <url>` (or `RIG_ARWEAVE_GATEWAY`, the same variable `rig push`,
+`rig site` and `rig ci serve` honour) puts that gateway **first**, on the store's
+raw-bytes route `<url>/raw/<txId>`, with the public list kept behind it as the
+fallback. It is the read-path twin of `rig ci serve --gateway`.
+
+```sh
+export RIG_ARWEAVE_GATEWAY=http://localhost:3000   # the dev sandbox's gateway
+rig clone ws://localhost:7100 <owner-npub>/<repo-id>
+rig fetch                                          # or: rig fetch --gateway http://localhost:3000
+```
+
+`/raw/` and not `/<txId>`: an ar.io node serves raw transaction bytes there whether
+or not it does sandboxed-subdomain redirects, and the TOON store's own gateway
+answers on that route alone. Public gateways serve the same bytes on both, so with
+nothing configured the list is exactly as it always was.
+
+The **`Git-SHA` lookup follows the gateway too**. A kind:30618 object map is capped,
+so a SHA it does not carry is resolved by asking a gateway's GraphQL endpoint which
+transaction carries that object — and a configured gateway is asked at
+`<url>/graphql`, never `arweave.net` (which would answer about a *different*
+network, or leak the query off an air-gapped stack). Object bytes are
+content-addressed and SHA-verified, so any mirror may serve them; a tag query is a
+statement about one network, so it goes only to the network you named. Configure
+nothing and it is the shared `arweave.net` resolver, unchanged. A gateway that does
+not serve GraphQL therefore resolves nothing — name one that does (every ar.io node
+does), or leave the variable unset.
+
 `rig issue list|show` and `rig pr list|show` are pure relay reads (kind:1621/1617 by
 the repo `#a` tag; state from kind:1630-1633, latest wins; comments under `show` —
 NIP-22 kind:1111 matched on the uppercase `E` root tag, merged with legacy kind:1622

package/dist/{chunk-X232W4TG.js → chunk-2TG4YHEC.js}

@@ -52,9 +52,14 @@ import {
   updateRef,
   writeGitObjects,
   writeToonConfig
-} from "./chunk-DCGV6ALH.js";
+} from "./chunk-4WVH2ITA.js";
+import {
+  PREFERRED_GATEWAY,
+  mirrorGatewaysFor,
+  readGateways,
+  shaResolverFor
+} from "./chunk-CHVOXCDV.js";
 import {
-  ARWEAVE_GATEWAYS,
   COMMENT_KIND,
   DEFAULT_KEYSTORE_PASSWORD,
   LEGACY_COMMENT_KIND,
@@ -77,33 +82,19 @@ import {
   readClientConfigFile,
   resolveAccountIndex,
   resolveIdentity
-} from "./chunk-JBFBD7HV.js";
+} from "./chunk-QKL53YZS.js";
 import {
   ChannelMapStore,
   channelStatus,
+  legacyChannelFiles,
   resolveChannelPaths,
   resolveConflictingPath
-} from "./chunk-XCLUB2CY.js";
+} from "./chunk-LMZSAFAB.js";
 import {
   RIG_STANDALONE_ENV,
   deriveNostrKeyFromMnemonic,
   uploadChargeFor
-} from "./chunk-U5A7MHBP.js";
-
-// src/gateway-preference.ts
-var TESTNET_GATEWAY = /(^|\.)ar-io\.dev$/i;
-function isMainnetGateway(url) {
-  try {
-    return !TESTNET_GATEWAY.test(new URL(url).hostname);
-  } catch {
-    return false;
-  }
-}
-var PREFERRED_GATEWAY = ARWEAVE_GATEWAYS.find(isMainnetGateway) ?? "https://arweave.net";
-function mirrorGatewaysFor(primary) {
-  const p = primary.replace(/\/+$/, "");
-  return ARWEAVE_GATEWAYS.filter((g) => g.replace(/\/+$/, "") !== p);
-}
+} from "./chunk-7VIVQHRG.js";
 
 // src/cli/render.ts
 function describeAnnouncementDiff(diff) {
@@ -320,7 +311,7 @@ function loadPaidSession(deps, relayUrl) {
   });
 }
 var defaultLoadStandalone = async (options) => {
-  const mod = await import("./standalone-mode-UQSP4677.js");
+  const mod = await import("./standalone-mode-AT4S5EZG.js");
   return mod.createStandaloneContext(options);
 };
 function identityReport(ctx) {
@@ -1037,7 +1028,10 @@ async function readWalletBounded(read, timeoutMs) {
   if (timeoutMs <= 0) return settled;
   let timer;
   const guard = new Promise((_resolve, reject) => {
-    timer = setTimeout(() => reject(new WalletReadTimeoutError(timeoutMs)), timeoutMs);
+    timer = setTimeout(
+      () => reject(new WalletReadTimeoutError(timeoutMs)),
+      timeoutMs
+    );
   });
   settled.catch(() => void 0);
   try {
@@ -1097,7 +1091,6 @@ async function runBalance(args, deps) {
         status: channelStatus(watermark),
         depositTotal: deposited ?? null,
         cumulativeClaimed: claimed ?? null,
-        nonce: watermark?.nonce ?? null,
         available,
         overdrawn
       };
@@ -1433,39 +1426,44 @@ async function runChain(args, deps) {
 
 // src/cli/channel.ts
 import { parseArgs as parseArgs4 } from "util";
+import { dirname as dirname2 } from "path";
 var CHANNEL_USAGE = `Usage: rig channel <subcommand>
 
-Manage the payment channels paid rig commands hold with relay/store peers.
-Paid commands open a channel lazily on first use and record it under
-TOON_CLIENT_HOME (default ~/.toon-client, rig-channels.json), so later
-invocations resume the same channel instead of opening a new one per run.
+Manage the x402 payment channels paid rig commands pay a node from. Every
+paid packet carries a voucher naming the channel's running total (client 4.x).
+Paid commands open a channel on first use and resume it from the client's
+store (TOON_CLIENT_HOME, default ~/.toon-client, channels-x402.json);
+\`rig channel open\` also records it in rig-channels-x402.json there.
 
 Subcommands:
   list [--json]    show recorded channels \u2014 peer, chain, channel id, deposit,
-                   cumulative claimed, status. Free: reads local state only.
+                   cumulative signed, status. Free: reads local state only.
 
   open [--peer <ilp-destination>] [--deposit <base-units>]
-                   explicitly open the payment channel for a peer \u2014 the SAME
-                   path paid commands use lazily: resumes the recorded live
-                   channel if one exists (no on-chain spend), else opens and
-                   records a fresh one (locks the peer-negotiated initial
-                   deposit on-chain). --peer is the ILP destination to anchor
-                   to (default: the configured destination, e.g. the devnet
-                   apex); --deposit adds that much extra collateral after the
-                   open/resume. On-chain: asks for confirmation (--yes skips).
+                   explicitly open the channel paid commands draw on: resumes
+                   the client's open channel if there is one (no on-chain
+                   spend), else opens and records a fresh one, locking the
+                   configured deposit (TOON_CLIENT_DEPOSIT) from your wallet.
+                   On Solana the node sponsors the open (USDC, no SOL).
+                   --peer is the ILP destination to record it under (default:
+                   the configured publish destination); --deposit adds that
+                   much extra collateral after the open/resume (Base only: a
+                   Solana channel is replaced when it runs out, never topped
+                   up). Asks for confirmation (--yes skips).
 
   close <channelId>
-                   close a recorded channel \u2014 an on-chain tx that starts the
-                   settlement challenge window (the peer's settlementTimeout).
-                   The channel stops paying immediately; the remaining
+                   close a recorded channel: an on-chain tx (Solana
+                   request_close, Base timed withdrawal) that starts its exit
+                   window, and that of every other channel still open with the
+                   node. The channel stops paying immediately; the remaining
                    collateral stays locked until \`rig channel settle\` after
                    the window elapses. Asks for confirmation (--yes skips).
 
   settle <channelId>
-                   settle a closed channel once its challenge window elapsed \u2014
-                   an on-chain tx that releases the remaining collateral back
-                   to your wallet. Refused (without spending gas) while the
-                   window is still open. Asks for confirmation (--yes skips).
+                   settle a closed channel once its exit window elapsed: an
+                   on-chain tx that releases the remaining collateral back to
+                   your wallet. Nothing is sent while the window is still
+                   open. Asks for confirmation (--yes skips).
 
 Common options: --json (machine-readable envelopes; without --yes lifecycle
 commands emit a pure plan and execute nothing), --yes, -h/--help.`;
@@ -1521,10 +1519,17 @@ function runChannelList(args, deps) {
     const store = new ChannelMapStore(paths);
     const records = store.list();
     const rows = records.map((record) => describeChannel(record, store));
+    const legacy = legacyChannelFiles(dirname2(paths.mapPath));
+    const legacyNote = `client 3.x toon-channel state not shown: ${legacy.join(", ")} (its deposits are left to the rig that opened them: \`npm i -g @toon-protocol/rig@4.7.0\`, then \`rig channel close\`)`;
     if (json) {
-      io.emitJson({ command: "channel list", channels: rows });
+      io.emitJson({
+        command: "channel list",
+        channels: rows,
+        ...legacy.length > 0 ? { legacyStateFiles: legacy } : {}
+      });
       return 0;
     }
+    if (legacy.length > 0) io.err(`rig: ${legacyNote}`);
     if (rows.length === 0) {
       io.out(
         "No payment channels recorded \u2014 paid rig commands (push, issue, comment, pr) record the channel they open on first use, and `rig channel open` records an explicit one."
@@ -1556,14 +1561,13 @@ function describeChannel(record, store) {
     tokenNetwork: record.tokenNetwork,
     depositTotal: record.depositTotal ?? null,
     cumulativeClaimed: watermark?.cumulativeAmount ?? null,
-    nonce: watermark?.nonce ?? null,
     status: channelStatus(watermark),
     openedAt: record.openedAt,
     lastUsedAt: record.lastUsedAt
   };
 }
 function renderChannel(row) {
-  const claimed = row.cumulativeClaimed === null ? "unknown (no local claim state)" : `${row.cumulativeClaimed} base units (nonce ${row.nonce})`;
+  const claimed = row.cumulativeClaimed === null ? "unknown (no local voucher state)" : `${row.cumulativeClaimed} base units signed`;
   return [
     `channel ${row.channelId} [${row.status}]`,
     `  peer        ${row.destination} (${row.peerId})`,
@@ -1711,7 +1715,9 @@ async function runChannelOpen(args, deps) {
     io.out(
       outcome.resumed ? `Resumed recorded channel ${outcome.channelId} \u2014 no on-chain open was needed.` : `Opened channel ${outcome.channelId}${outcome.chain ? ` on ${outcome.chain}` : ""} and recorded it for reuse.`
     );
-    io.out(`  peer        ${outcome.destination}${outcome.peerId ? ` (${outcome.peerId})` : ""}`);
+    io.out(
+      `  peer        ${outcome.destination}${outcome.peerId ? ` (${outcome.peerId})` : ""}`
+    );
     if (outcome.depositAdded) {
       io.out(
         `  deposited   +${outcome.depositAdded} base units` + (outcome.depositTxHash ? `  (tx ${outcome.depositTxHash})` : "")
@@ -1805,7 +1811,9 @@ async function runChannelWithdrawStep(args, deps, step) {
     if (!json) {
       const claimed = watermark?.cumulativeAmount;
       io.out(`Channel ${step} plan:`);
-      io.out(`  channel     ${channelId} [${channelStatus(watermark, nowSec)}]`);
+      io.out(
+        `  channel     ${channelId} [${channelStatus(watermark, nowSec)}]`
+      );
       io.out(`  peer        ${record.destination} (${record.peerId})`);
       io.out(`  chain       ${record.chain}`);
       io.out(
@@ -2485,7 +2493,7 @@ async function runCi(args, deps) {
     case "status":
       return runCiStatus(rest, deps);
     case "serve":
-      return (await import("./ci-serve-AYFZOY4O.js")).runCiServe(rest, deps);
+      return (await import("./ci-serve-BU7NDT7O.js")).runCiServe(rest, deps);
     case "--help":
     case "-h":
     case "help":
@@ -2504,7 +2512,7 @@ async function runCi(args, deps) {
 
 // src/cli/clone.ts
 import { mkdtemp, mkdir, readdir, rename, rm, rmdir } from "fs/promises";
-import { basename, dirname as dirname2, join as join3, resolve } from "path";
+import { basename, dirname as dirname3, join as join3, resolve } from "path";
 import { parseArgs as parseArgs6 } from "util";
 var CLONE_USAGE = `Usage: rig clone <relay-url> <owner>/<repo-id> [dir] [options]
 
@@ -2525,6 +2533,11 @@ from Arweave gateways. A clone right after a push may report missing
 objects \u2014 retry after propagation.
 
 Options:
+  --gateway <url>      gateway to read objects through FIRST, on its raw-bytes
+                       route <url>/raw/<txId>, ahead of the public gateway
+                       list \u2014 name a private, local or air-gapped gateway to
+                       clone a repo the public ones do not carry
+                       (env RIG_ARWEAVE_GATEWAY also sets it)
   --concurrency <n>    parallel gateway downloads (default 8)
   --json               machine-readable result envelope
   -h, --help           show this help`;
@@ -2551,6 +2564,7 @@ function parseCloneArgs(args) {
     options: {
       json: { type: "boolean", default: false },
       concurrency: { type: "string" },
+      gateway: { type: "string" },
       help: { type: "boolean", short: "h", default: false }
     },
     allowPositionals: true
@@ -2586,6 +2600,7 @@ function parseCloneArgs(args) {
     repoId,
     dir,
     concurrency,
+    gateway: values.gateway,
     json: values.json === true
   };
 }
@@ -2634,7 +2649,9 @@ async function runClone(args, deps) {
       ownerPubkey: owner,
       repoId,
       ...deps.webSocketFactory ? { webSocketFactory: deps.webSocketFactory } : {},
-      ...deps.resolveSha ? { resolveSha: deps.resolveSha } : {}
+      // The GraphQL fallback for SHAs the map does not cover asks the SAME
+      // permaweb the objects are read from (#183).
+      resolveSha: deps.resolveSha ?? shaResolverFor(parsed.gateway, deps.env)
     });
     if (!remoteState.announced && remoteState.refsEvent === null) {
       throw new RepoNotFoundError(relayUrl, owner, repoId);
@@ -2659,6 +2676,8 @@ async function runClone(args, deps) {
       tips,
       shaToTxId: remoteState.shaToTxId,
       resolveMissing: (shas) => remoteState.resolveMissing(shas),
+      // `--gateway` / RIG_ARWEAVE_GATEWAY first, public list behind it (#176).
+      gateways: readGateways(parsed.gateway, deps.env),
       ...deps.fetchFn ? { fetchFn: deps.fetchFn } : {},
       ...parsed.concurrency !== void 0 ? { concurrency: parsed.concurrency } : {}
     });
@@ -2673,7 +2692,7 @@ async function runClone(args, deps) {
         `warning: unreachable object ${sha} (tx ${txId}) could not be downloaded \u2014 not needed by any ref, continuing`
       );
     }
-    const parent = dirname2(dest);
+    const parent = dirname3(dest);
     await mkdir(parent, { recursive: true });
     tempDir = await mkdtemp(join3(parent, `.${basename(dest)}.rig-clone-`));
     await runGit(tempDir, [
@@ -4020,7 +4039,7 @@ async function warnIfNotMaintainer(deps, args) {
 // src/cli/entry.ts
 import { mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
 import { homedir as homedir3 } from "os";
-import { dirname as dirname3, join as join4 } from "path";
+import { dirname as dirname4, join as join4 } from "path";
 import { parseArgs as parseArgs9 } from "util";
 var ENTRY_USAGE = `Usage: rig entry [<connector-url> | clear] [options]
 
@@ -4059,7 +4078,7 @@ function readEntryConfig(configPath) {
   }
 }
 function writeEntryConfig(configPath, file) {
-  mkdirSync3(dirname3(configPath), { recursive: true });
+  mkdirSync3(dirname4(configPath), { recursive: true });
   writeFileSync3(configPath, `${JSON.stringify(file, null, 2)}
 `, "utf8");
 }
@@ -4256,6 +4275,11 @@ Options:
   --repo-id <id>       repository id / NIP-34 d-tag (default: git config)
   --owner <pubkey>     repository owner (npub or 64-char hex; default: git config)
   --relay <url>        ad-hoc relay override \u2014 bypasses the remote's URL
+  --gateway <url>      gateway to read objects through FIRST, on its raw-bytes
+                       route <url>/raw/<txId>, ahead of the public gateway
+                       list \u2014 name a private, local or air-gapped gateway to
+                       fetch objects the public ones do not carry
+                       (env RIG_ARWEAVE_GATEWAY also sets it)
   --concurrency <n>    parallel gateway downloads (default 8)
   --json               machine-readable result envelope
   -h, --help           show this help`;
@@ -4288,6 +4312,7 @@ async function runFetch(args, deps) {
   let relayFlag;
   let repoIdFlag;
   let ownerFlag;
+  let gatewayFlag;
   let concurrency;
   try {
     const { values, positionals } = parseArgs10({
@@ -4297,6 +4322,7 @@ async function runFetch(args, deps) {
         relay: { type: "string" },
         "repo-id": { type: "string" },
         owner: { type: "string" },
+        gateway: { type: "string" },
         concurrency: { type: "string" },
         help: { type: "boolean", short: "h", default: false }
       },
@@ -4316,6 +4342,7 @@ async function runFetch(args, deps) {
     relayFlag = values.relay;
     repoIdFlag = values["repo-id"];
     ownerFlag = values.owner !== void 0 ? ownerToHex(values.owner) : void 0;
+    gatewayFlag = values.gateway;
     if (values.concurrency !== void 0) {
       concurrency = Number.parseInt(values.concurrency, 10);
       if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
@@ -4354,7 +4381,9 @@ async function runFetch(args, deps) {
       ownerPubkey: owner,
       repoId,
       ...deps.webSocketFactory ? { webSocketFactory: deps.webSocketFactory } : {},
-      ...deps.resolveSha ? { resolveSha: deps.resolveSha } : {}
+      // The GraphQL fallback for SHAs the map does not cover asks the SAME
+      // permaweb the objects are read from (#183).
+      resolveSha: deps.resolveSha ?? shaResolverFor(gatewayFlag, deps.env)
     });
     const planned = [];
     for (const [refname, sha] of remoteState.refs) {
@@ -4381,6 +4410,8 @@ async function runFetch(args, deps) {
       shaToTxId: remoteState.shaToTxId,
       resolveMissing: (shas) => remoteState.resolveMissing(shas),
       presentLocally,
+      // `--gateway` / RIG_ARWEAVE_GATEWAY first, public list behind it (#176).
+      gateways: readGateways(gatewayFlag, deps.env),
       ...deps.fetchFn ? { fetchFn: deps.fetchFn } : {},
       ...concurrency !== void 0 ? { concurrency } : {}
     });
@@ -4837,7 +4868,7 @@ var runGitPassthrough = (argv, options = {}) => {
 
 // src/cli/identity-cmd.ts
 import { existsSync, mkdirSync as mkdirSync4 } from "fs";
-import { dirname as dirname4 } from "path";
+import { dirname as dirname5 } from "path";
 import { createInterface } from "readline/promises";
 import { parseArgs as parseArgs12 } from "util";
 async function loadKeyOps() {
@@ -4889,7 +4920,7 @@ async function prepareKeystoreTarget(input) {
   const envPassword = input.env["TOON_CLIENT_KEYSTORE_PASSWORD"]?.trim() || void 0;
   const autoPassword = envPassword === void 0;
   const password = envPassword ?? DEFAULT_KEYSTORE_PASSWORD;
-  mkdirSync4(dirname4(keystorePath), { recursive: true });
+  mkdirSync4(dirname5(keystorePath), { recursive: true });
   return { keystorePath, password, autoPassword, existing, keyOps };
 }
 function readAccountIndex(env) {
@@ -7967,7 +7998,6 @@ async function dispatch(argv, deps) {
 }
 
 export {
-  PREFERRED_GATEWAY,
   renderIdentityLine,
   withForcedStandalone,
   loadPaidSession,
@@ -7976,4 +8006,4 @@ export {
   rigVersion,
   dispatch
 };
-//# sourceMappingURL=chunk-X232W4TG.js.map
+//# sourceMappingURL=chunk-2TG4YHEC.js.map