@toon-protocol/rig 2.0.1 → 2.1.0

package/dist/cli/rig.js

@@ -20,6 +20,11 @@ import {
   buildPatch,
   buildStatus
 } from "../chunk-HPSOQP7Q.js";
+import {
+  ChannelMapStore,
+  channelStatus,
+  resolveChannelPaths
+} from "../chunk-O6TXHKWG.js";
 import {
   MAX_OBJECT_SIZE
 } from "../chunk-X2CZPPDM.js";
@@ -30,16 +35,8 @@ import { createInterface } from "readline/promises";
 // src/cli/dispatch.ts
 import { createRequire } from "module";
 
-// src/cli/events.ts
-import { readFile } from "fs/promises";
+// src/cli/balance.ts
 import { parseArgs as parseArgs3 } from "util";
-import {
-  REPOSITORY_ANNOUNCEMENT_KIND,
-  STATUS_APPLIED_KIND,
-  STATUS_CLOSED_KIND,
-  STATUS_DRAFT_KIND,
-  STATUS_OPEN_KIND
-} from "@toon-protocol/core/nip34";
 
 // src/cli/errors.ts
 var UnconfiguredRepoAddressError = class extends Error {
@@ -221,12 +218,127 @@ function describeError(err, command = "push") {
       json: { error: "missing_uplink", detail: message }
     };
   }
+  if (name === "ChannelMapCorruptError") {
+    return {
+      code: "channel_map_corrupt",
+      lines: [message],
+      json: { error: "channel_map_corrupt", detail: message }
+    };
+  }
+  if (name === "SettleTooEarlyError") {
+    const settleableAt = err.settleableAt;
+    return {
+      code: "settle_too_early",
+      lines: [
+        message,
+        "The settlement challenge window is still open \u2014 nothing was spent. Re-run `rig channel settle` after the settleable time."
+      ],
+      json: {
+        error: "settle_too_early",
+        detail: message,
+        ...typeof settleableAt === "string" ? { settleableAt } : {}
+      }
+    };
+  }
   return {
     code: "error",
     lines: [`rig ${command} failed: ${message}`],
     json: { error: "error", detail: message }
   };
 }
+function emitCliError(io2, json, command, err) {
+  const described = describeError(err, command);
+  if (json) io2.emitJson({ command, ...described.json });
+  for (const line of described.lines) io2.err(line);
+  return 1;
+}
+
+// src/cli/push.ts
+import { parseArgs as parseArgs2 } from "util";
+
+// src/cli/render.ts
+function formatNumber(value) {
+  return String(value).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+function shortSha(sha) {
+  return sha ? sha.slice(0, 7) : "(none)";
+}
+function refLine(update) {
+  const arrow = `${shortSha(update.remoteSha)} \u2192 ${shortSha(update.localSha)}`;
+  return `  ${update.refname}  ${arrow}  (${update.kind})`;
+}
+function renderIdentityLine(identity) {
+  return `Identity: ${identity.pubkey} (from ${identity.sourceLabel})`;
+}
+function renderPlan(plan) {
+  const lines = [];
+  lines.push(
+    `Push plan for repo "${plan.repoId}"` + (plan.announceNeeded ? " \u2014 first push, will announce (kind:30617)" : "")
+  );
+  lines.push("Refs:");
+  for (const update of plan.refUpdates) lines.push(refLine(update));
+  const est = plan.estimate;
+  const skipped = Object.keys(plan.knownShaToTxId).length;
+  lines.push(
+    `Objects: ${est.objectCount} to upload (${formatNumber(est.totalObjectBytes)} bytes)` + (skipped > 0 ? `; ${skipped} already on Arweave (free)` : "")
+  );
+  lines.push("Fees (base units):");
+  lines.push(
+    `  upload   ${est.objectCount} object(s), ${formatNumber(est.totalObjectBytes)} bytes   ${formatNumber(est.uploadFee)}`
+  );
+  lines.push(`  events   ${est.eventCount} event(s)   ${formatNumber(est.eventFees)}`);
+  lines.push(`  total    ${formatNumber(est.totalFee)}`);
+  lines.push("Writes are permanent and non-refundable.");
+  return lines;
+}
+function feeLabel(fee) {
+  return fee !== void 0 ? `${formatNumber(fee)} base units` : "the publisher's configured per-event fee";
+}
+function renderEventPlan(opts) {
+  return [
+    `Publish ${opts.action}`,
+    `Repo: 30617:${opts.addr.ownerPubkey}:${opts.addr.repoId}`,
+    renderIdentityLine(opts.identity),
+    `Fee: ${feeLabel(opts.fee)}. Writes are permanent and non-refundable.`
+  ];
+}
+function renderEventReceipt(action, result) {
+  const lines = [
+    `Published ${action}: ${result.eventId}  paid ${formatNumber(result.feePaid)} base units`
+  ];
+  if (result.channelBalanceAfter !== void 0) {
+    lines.push(
+      `Channel balance after: ${formatNumber(result.channelBalanceAfter)} base units`
+    );
+  }
+  return lines;
+}
+function renderResult(result) {
+  const lines = [];
+  lines.push(`Pushed "${result.repoId}":`);
+  const paid = result.uploads.filter((u) => !u.skipped);
+  const skipped = result.uploads.filter((u) => u.skipped);
+  for (const upload of result.uploads) {
+    lines.push(
+      `  object ${upload.sha.slice(0, 12)}  ${upload.skipped ? "skipped (already stored)" : `paid ${formatNumber(upload.feePaid)}`}  ar:${upload.txId}`
+    );
+  }
+  lines.push(
+    `Uploads: ${paid.length} paid, ${skipped.length} skipped (content-addressed).`
+  );
+  if (result.announceReceipt) {
+    lines.push(
+      `Announcement (kind:30617): ${result.announceReceipt.eventId}  paid ${formatNumber(result.announceReceipt.feePaid)}`
+    );
+  }
+  lines.push(
+    `Refs event (kind:30618): ${result.refsReceipt.eventId}  paid ${formatNumber(result.refsReceipt.feePaid)}`
+  );
+  lines.push(
+    `Total paid: ${formatNumber(result.totalFeePaid)} base units (estimate was ${formatNumber(result.estimate.totalFee)})`
+  );
+  return lines;
+}
 
 // src/cli/git-config.ts
 import { execFile } from "child_process";
@@ -320,93 +432,6 @@ async function writeToonConfig(repoPath, config) {
   }
 }
 
-// src/cli/push.ts
-import { parseArgs as parseArgs2 } from "util";
-
-// src/cli/render.ts
-function formatNumber(value) {
-  return String(value).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
-}
-function shortSha(sha) {
-  return sha ? sha.slice(0, 7) : "(none)";
-}
-function refLine(update) {
-  const arrow = `${shortSha(update.remoteSha)} \u2192 ${shortSha(update.localSha)}`;
-  return `  ${update.refname}  ${arrow}  (${update.kind})`;
-}
-function renderIdentityLine(identity) {
-  return `Identity: ${identity.pubkey} (from ${identity.sourceLabel})`;
-}
-function renderPlan(plan) {
-  const lines = [];
-  lines.push(
-    `Push plan for repo "${plan.repoId}"` + (plan.announceNeeded ? " \u2014 first push, will announce (kind:30617)" : "")
-  );
-  lines.push("Refs:");
-  for (const update of plan.refUpdates) lines.push(refLine(update));
-  const est = plan.estimate;
-  const skipped = Object.keys(plan.knownShaToTxId).length;
-  lines.push(
-    `Objects: ${est.objectCount} to upload (${formatNumber(est.totalObjectBytes)} bytes)` + (skipped > 0 ? `; ${skipped} already on Arweave (free)` : "")
-  );
-  lines.push("Fees (base units):");
-  lines.push(
-    `  upload   ${est.objectCount} object(s), ${formatNumber(est.totalObjectBytes)} bytes   ${formatNumber(est.uploadFee)}`
-  );
-  lines.push(`  events   ${est.eventCount} event(s)   ${formatNumber(est.eventFees)}`);
-  lines.push(`  total    ${formatNumber(est.totalFee)}`);
-  lines.push("Writes are permanent and non-refundable.");
-  return lines;
-}
-function feeLabel(fee) {
-  return fee !== void 0 ? `${formatNumber(fee)} base units` : "the publisher's configured per-event fee";
-}
-function renderEventPlan(opts) {
-  return [
-    `Publish ${opts.action}`,
-    `Repo: 30617:${opts.addr.ownerPubkey}:${opts.addr.repoId}`,
-    renderIdentityLine(opts.identity),
-    `Fee: ${feeLabel(opts.fee)}. Writes are permanent and non-refundable.`
-  ];
-}
-function renderEventReceipt(action, result) {
-  const lines = [
-    `Published ${action}: ${result.eventId}  paid ${formatNumber(result.feePaid)} base units`
-  ];
-  if (result.channelBalanceAfter !== void 0) {
-    lines.push(
-      `Channel balance after: ${formatNumber(result.channelBalanceAfter)} base units`
-    );
-  }
-  return lines;
-}
-function renderResult(result) {
-  const lines = [];
-  lines.push(`Pushed "${result.repoId}":`);
-  const paid = result.uploads.filter((u) => !u.skipped);
-  const skipped = result.uploads.filter((u) => u.skipped);
-  for (const upload of result.uploads) {
-    lines.push(
-      `  object ${upload.sha.slice(0, 12)}  ${upload.skipped ? "skipped (already stored)" : `paid ${formatNumber(upload.feePaid)}`}  ar:${upload.txId}`
-    );
-  }
-  lines.push(
-    `Uploads: ${paid.length} paid, ${skipped.length} skipped (content-addressed).`
-  );
-  if (result.announceReceipt) {
-    lines.push(
-      `Announcement (kind:30617): ${result.announceReceipt.eventId}  paid ${formatNumber(result.announceReceipt.feePaid)}`
-    );
-  }
-  lines.push(
-    `Refs event (kind:30618): ${result.refsReceipt.eventId}  paid ${formatNumber(result.refsReceipt.feePaid)}`
-  );
-  lines.push(
-    `Total paid: ${formatNumber(result.totalFeePaid)} base units (estimate was ${formatNumber(result.estimate.totalFee)})`
-  );
-  return lines;
-}
-
 // src/cli/remote.ts
 import { parseArgs } from "util";
 var RELAY_PROTOCOLS = /* @__PURE__ */ new Set(["ws:", "wss:", "http:", "https:"]);
@@ -471,10 +496,10 @@ Commands:
   list                     list remote names + URLs (the default subcommand)
 
 Options:
-  --json                   machine-readable output (list)
+  --json                   machine-readable envelope (all subcommands)
   -h, --help               show this help`;
 async function runRemote(args, deps) {
-  const { io } = deps;
+  const { io: io2 } = deps;
   let sub;
   let rest;
   let json;
@@ -488,34 +513,34 @@ async function runRemote(args, deps) {
       allowPositionals: true
     });
     if (values.help) {
-      io.out(REMOTE_USAGE);
+      io2.out(REMOTE_USAGE);
       return 0;
     }
     json = values.json ?? false;
     [sub, ...rest] = positionals;
   } catch (err) {
-    io.err(err instanceof Error ? err.message : String(err));
-    io.err(REMOTE_USAGE);
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(REMOTE_USAGE);
     return 2;
   }
   switch (sub) {
     case void 0:
     case "list":
       if (rest.length > 0) {
-        io.err(`rig remote list takes no arguments (got ${rest.join(" ")})`);
-        io.err(REMOTE_USAGE);
+        io2.err(`rig remote list takes no arguments (got ${rest.join(" ")})`);
+        io2.err(REMOTE_USAGE);
         return 2;
       }
       break;
     case "add": {
       if (rest.length !== 2) {
-        io.err("usage: rig remote add <name> <relay-url>");
-        io.err(REMOTE_USAGE);
+        io2.err("usage: rig remote add <name> <relay-url>");
+        io2.err(REMOTE_USAGE);
         return 2;
       }
       const url = rest[1];
       if (!isRelayUrl(url)) {
-        io.err(
+        io2.err(
           `cannot add remote: ${JSON.stringify(url)} is not a relay URL \u2014 relays are ws://, wss://, http://, or https://`
         );
         return 2;
@@ -524,14 +549,14 @@ async function runRemote(args, deps) {
     }
     case "remove":
       if (rest.length !== 1) {
-        io.err("usage: rig remote remove <name>");
-        io.err(REMOTE_USAGE);
+        io2.err("usage: rig remote remove <name>");
+        io2.err(REMOTE_USAGE);
         return 2;
       }
       break;
     default:
-      io.err(`unknown rig remote subcommand: ${sub}`);
-      io.err(REMOTE_USAGE);
+      io2.err(`unknown rig remote subcommand: ${sub}`);
+      io2.err(REMOTE_USAGE);
       return 2;
   }
   try {
@@ -546,23 +571,23 @@ async function runRemote(args, deps) {
       case "list": {
         const remotes = await listGitRemotes(repoRoot);
         if (json) {
-          io.out(JSON.stringify({ command: "remote", remotes }, null, 2));
+          io2.emitJson({ command: "remote", remotes });
           return 0;
         }
         if (remotes.length === 0) {
-          io.out(
+          io2.out(
             "no remotes configured \u2014 add one: rig remote add origin <relay-url>"
           );
           return 0;
         }
         for (const remote of remotes) {
           for (const url of remote.urls) {
-            io.out(
+            io2.out(
               `${remote.name}	${url}` + (isRelayUrl(url) ? "" : "	(not a relay URL \u2014 ignored by rig)")
             );
           }
           if (remote.urls.length > 1) {
-            io.err(
+            io2.err(
               `warning: remote "${remote.name}" has ${remote.urls.length} URLs \u2014 rig supports one relay URL per remote (fix with \`git remote set-url ${remote.name} <relay-url>\`)`
             );
           }
@@ -573,37 +598,61 @@ async function runRemote(args, deps) {
         const [name, url] = rest;
         const existing = await getGitRemoteUrls(repoRoot, name);
         if (existing.length > 0) {
-          io.err(
-            `remote ${JSON.stringify(name)} already exists (${existing.join(", ")}) \u2014 nothing changed. Point it somewhere else with \`git remote set-url ${name} <relay-url>\`, or \`rig remote remove ${name}\` first.`
-          );
+          const detail = `remote ${JSON.stringify(name)} already exists (${existing.join(", ")}) \u2014 nothing changed. Point it somewhere else with \`git remote set-url ${name} <relay-url>\`, or \`rig remote remove ${name}\` first.`;
+          if (json) {
+            io2.emitJson({
+              command: "remote",
+              error: "remote_exists",
+              detail,
+              remote: name,
+              urls: existing
+            });
+          }
+          io2.err(detail);
           return 1;
         }
         await addGitRemote(repoRoot, name, url);
-        io.out(`Added remote ${name} \u2192 ${url}`);
+        if (!json) io2.out(`Added remote ${name} \u2192 ${url}`);
         if (name === "origin") {
-          io.out(
-            "`rig push` and the event commands now publish here by default."
-          );
+          if (!json) {
+            io2.out(
+              "`rig push` and the event commands now publish here by default."
+            );
+          }
           const toonConfig = await readToonConfig(repoRoot);
           if (toonConfig.relays.length > 0) {
-            io.err(
+            io2.err(
               `note: git config toon.relay (${toonConfig.relays.join(", ")}) is deprecated and now shadowed by the origin remote \u2014 drop it with \`git config --unset-all toon.relay\` (the key is removed in v0.3).`
             );
           }
         }
+        if (json) {
+          io2.emitJson({ command: "remote", action: "add", name, url });
+        }
         return 0;
       }
       case "remove": {
         const name = rest[0];
         const existing = await getGitRemoteUrls(repoRoot, name);
         if (existing.length === 0) {
-          io.err(
-            `no remote named ${JSON.stringify(name)} \u2014 \`rig remote list\` shows configured remotes.`
-          );
+          const detail = `no remote named ${JSON.stringify(name)} \u2014 \`rig remote list\` shows configured remotes.`;
+          if (json) {
+            io2.emitJson({
+              command: "remote",
+              error: "unknown_remote",
+              detail,
+              remote: name
+            });
+          }
+          io2.err(detail);
           return 1;
         }
         await removeGitRemote(repoRoot, name);
-        io.out(`Removed remote ${name}`);
+        if (json) {
+          io2.emitJson({ command: "remote", action: "remove", name });
+        } else {
+          io2.out(`Removed remote ${name}`);
+        }
         return 0;
       }
       /* v8 ignore next 2 -- unreachable: validated above */
@@ -611,19 +660,13 @@ async function runRemote(args, deps) {
         return 2;
     }
   } catch (err) {
-    const described = describeError(err, "remote");
-    if (json) {
-      io.out(JSON.stringify({ command: "remote", ...described.json }, null, 2));
-    } else {
-      for (const line of described.lines) io.err(line);
-    }
-    return 1;
+    return emitCliError(io2, json, "remote", err);
   }
 }
 
 // src/cli/push.ts
 var defaultLoadStandalone = async (options) => {
-  const mod = await import("../standalone-mode-Q3FFZUXE.js");
+  const mod = await import("../standalone-mode-FCKTQ33Y.js");
   return mod.createStandaloneContext(options);
 };
 function identityReport(ctx) {
@@ -734,172 +777,758 @@ function parsePushArgs(args) {
   return flags;
 }
 async function runPush(args, deps) {
-  const { io, env } = deps;
+  const { io: io2, env } = deps;
   let flags;
   try {
     flags = parsePushArgs(args);
   } catch (err) {
-    io.err(err instanceof Error ? err.message : String(err));
-    io.err(PUSH_USAGE);
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(PUSH_USAGE);
+    return 2;
+  }
+  if (flags.help) {
+    io2.out(PUSH_USAGE);
+    return 0;
+  }
+  let standaloneCtx;
+  try {
+    const repoRoot = await resolveRepoRoot(deps.cwd);
+    const toonConfig = await readToonConfig(repoRoot);
+    const repoId = flags.repoId ?? toonConfig.repoId;
+    if (!repoId) throw new UnconfiguredRepoAddressError("repository id");
+    const reader = new GitRepoReader(repoRoot);
+    let remoteName;
+    let refspecArgs = flags.positionals;
+    if (flags.relay.length === 0 && refspecArgs.length > 0) {
+      const first = refspecArgs[0];
+      const remoteNames = new Set(
+        (await listGitRemotes(repoRoot)).map((r) => r.name)
+      );
+      if (remoteNames.has(first)) {
+        remoteName = first;
+        refspecArgs = refspecArgs.slice(1);
+      } else {
+        const { refs } = await reader.listRefs();
+        const known = new Set(refs.map((r) => r.refname));
+        if (!known.has(first) && !known.has(`refs/heads/${first}`) && !known.has(`refs/tags/${first}`)) {
+          throw new Error(
+            `${JSON.stringify(first)} is neither a configured remote nor a local branch/tag \u2014 add the relay remote (\`rig remote add ${first} <relay-url>\`; \`rig remote list\` shows configured remotes) or fix the refspec`
+          );
+        }
+      }
+    }
+    const refspecs = await selectRefspecs(
+      reader,
+      refspecArgs,
+      flags.all,
+      flags.tags
+    );
+    const resolved = await resolveRelays({
+      relayFlags: flags.relay,
+      remoteName,
+      repoRoot,
+      toonRelays: toonConfig.relays
+    });
+    if (resolved.nudge !== void 0) io2.err(resolved.nudge);
+    const relaysUsed = resolved.relays;
+    if (relaysUsed.length > 1) {
+      io2.err(singleRelayRefusal(resolved, "Nothing was uploaded or paid."));
+      return 1;
+    }
+    standaloneCtx = await (deps.loadStandalone ?? defaultLoadStandalone)({
+      env,
+      cwd: deps.cwd,
+      warn: (line) => io2.err(line),
+      // Relay-origin for #264 network bootstrap (announce discovery).
+      ...relaysUsed[0] !== void 0 ? { relayUrl: relaysUsed[0] } : {}
+    });
+    const identity = identityReport(standaloneCtx);
+    if (toonConfig.owner && toonConfig.owner !== identity.pubkey) {
+      io2.err(
+        `warning: git config toon.owner (${toonConfig.owner.slice(0, 8)}\u2026) differs from the active identity (${identity.pubkey.slice(0, 8)}\u2026) \u2014 this push publishes under the ACTIVE identity's repo namespace, not the configured owner's. Re-run \`rig init\` to adopt the active identity.`
+      );
+    }
+    const remoteState = await standaloneCtx.fetchRemote({
+      ownerPubkey: standaloneCtx.ownerPubkey,
+      repoId,
+      relayUrls: relaysUsed
+    });
+    const feeRates = await standaloneCtx.publisher.getFeeRates();
+    const pushPlan = await planPush({
+      repoReader: reader,
+      remoteState,
+      feeRates,
+      repoId,
+      refs: refspecs,
+      force: flags.force
+    });
+    const plan = serializePushPlan(pushPlan);
+    const upToDate = plan.refUpdates.every((u) => u.kind === "up-to-date");
+    if (upToDate) {
+      if (flags.json) {
+        io2.emitJson({
+          command: "push",
+          repoId,
+          identity,
+          executed: false,
+          upToDate: true,
+          plan
+        });
+      } else {
+        io2.out("Everything up-to-date \u2014 nothing to push (and nothing paid).");
+      }
+      return 0;
+    }
+    if (!flags.json) {
+      for (const line of renderPlan(plan)) io2.out(line);
+      io2.out(renderIdentityLine(identity));
+    }
+    if (!flags.yes) {
+      if (flags.json) {
+        io2.emitJson({
+          command: "push",
+          repoId,
+          identity,
+          executed: false,
+          upToDate: false,
+          plan,
+          hint: "estimate only \u2014 re-run with --yes to upload and publish (permanent, non-refundable)"
+        });
+        return 0;
+      }
+      if (!io2.isInteractive) {
+        io2.err(
+          "refusing to spend channel funds without confirmation in a non-interactive session \u2014 re-run with --yes (or use --json for an estimate)"
+        );
+        return 1;
+      }
+      const proceed = await io2.confirm(
+        `Proceed with paid push (total ${plan.estimate.totalFee} base units)? [y/N] `
+      );
+      if (!proceed) {
+        io2.err("aborted \u2014 nothing was uploaded or published.");
+        return 1;
+      }
+    }
+    const pushResult = await executePush({
+      plan: pushPlan,
+      publisher: standaloneCtx.publisher,
+      remoteState,
+      repoReader: reader,
+      relayUrls: relaysUsed
+    });
+    const result = serializePushResult(pushPlan, pushResult);
+    if (flags.json) {
+      io2.emitJson({
+        command: "push",
+        repoId,
+        identity,
+        executed: true,
+        upToDate: false,
+        plan,
+        result
+      });
+    } else {
+      for (const line of renderResult(result)) io2.out(line);
+    }
+    return 0;
+  } catch (err) {
+    return emitCliError(io2, flags.json, "push", err);
+  } finally {
+    if (standaloneCtx) {
+      try {
+        await standaloneCtx.stop();
+      } catch {
+      }
+    }
+  }
+}
+
+// src/cli/balance.ts
+var BALANCE_USAGE = `Usage: rig balance [--json]
+
+Show the active identity's money: on-chain wallet balances (per configured
+chain, read from the settlement chain the payment channels actually use) and
+recorded payment-channel holdings (deposited / claimed / available). Free \u2014
+reads chain RPCs and local state only; nothing is signed or paid.
+
+Options:
+  --json      machine-readable envelope (base units as strings)
+  -h, --help  show this help`;
+async function runBalance(args, deps) {
+  const { io: io2, env } = deps;
+  let json = false;
+  try {
+    const { values } = parseArgs3({
+      args,
+      options: {
+        json: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false }
+      }
+    });
+    if (values.help) {
+      io2.out(BALANCE_USAGE);
+      return 0;
+    }
+    json = values.json ?? false;
+  } catch (err) {
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(BALANCE_USAGE);
+    return 2;
+  }
+  let ctx;
+  try {
+    ctx = await (deps.loadStandalone ?? defaultLoadStandalone)({
+      env,
+      cwd: deps.cwd,
+      warn: (line) => io2.err(line),
+      // Free read: works without a proxy/BTP write uplink.
+      requireUplink: false
+    });
+    const identity = identityReport(ctx);
+    const wallet = ctx.money ? await ctx.money.walletBalances() : [];
+    const store = new ChannelMapStore(resolveChannelPaths(env));
+    const channels = store.list().filter((record) => record.identity === identity.pubkey).map((record) => {
+      const watermark = store.readWatermark(record.channelId);
+      const deposited = record.depositTotal;
+      const claimed = watermark?.cumulativeAmount;
+      let available = null;
+      if (deposited !== void 0 && claimed !== void 0) {
+        const remaining = BigInt(deposited) - BigInt(claimed);
+        available = (remaining > 0n ? remaining : 0n).toString();
+      }
+      return {
+        channelId: record.channelId,
+        destination: record.destination,
+        peerId: record.peerId,
+        chain: record.chain,
+        status: channelStatus(watermark),
+        depositTotal: deposited ?? null,
+        cumulativeClaimed: claimed ?? null,
+        nonce: watermark?.nonce ?? null,
+        available
+      };
+    });
+    if (json) {
+      io2.emitJson({
+        command: "balance",
+        identity,
+        wallet,
+        channels
+      });
+      return 0;
+    }
+    io2.out(renderIdentityLine(identity));
+    io2.out("");
+    io2.out("Wallet (on-chain):");
+    if (wallet.length === 0) {
+      io2.out(
+        "  (no balance readable \u2014 no chain configured, the RPC is unreachable, or the chain's keys derive only during a client start)"
+      );
+    }
+    for (const balance of wallet) {
+      io2.out(
+        `  ${balance.chain.padEnd(7)} ${balance.address}  ${balance.amount}` + (balance.asset ? ` ${balance.asset}` : " base units") + (balance.assetScale !== void 0 ? ` (scale ${balance.assetScale})` : "")
+      );
+    }
+    io2.out("");
+    io2.out("Channels (recorded):");
+    if (channels.length === 0) {
+      io2.out(
+        "  none \u2014 paid commands record their channel on first use; `rig channel open` records one explicitly."
+      );
+    }
+    for (const c of channels) {
+      io2.out(
+        `  ${c.channelId} [${c.status}]  deposited ${c.depositTotal ?? "?"}  claimed ${c.cumulativeClaimed ?? "?"}  available ${c.available ?? "?"}  (${c.chain} \u2192 ${c.destination})`
+      );
+    }
+    return 0;
+  } catch (err) {
+    return emitCliError(io2, json, "balance", err);
+  } finally {
+    if (ctx) {
+      try {
+        await ctx.stop();
+      } catch {
+      }
+    }
+  }
+}
+
+// src/cli/channel.ts
+import { parseArgs as parseArgs4 } from "util";
+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.
+
+Subcommands:
+  list [--json]    show recorded channels \u2014 peer, chain, channel id, deposit,
+                   cumulative claimed, 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).
+
+  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
+                   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).
+
+Common options: --json (machine-readable envelopes; without --yes lifecycle
+commands emit a pure plan and execute nothing), --yes, -h/--help.`;
+async function runChannel(args, deps) {
+  const { io: io2 } = deps;
+  const [sub, ...rest] = args;
+  switch (sub) {
+    case "list":
+      return runChannelList(rest, deps);
+    case "open":
+      return runChannelOpen(rest, deps);
+    case "close":
+      return runChannelWithdrawStep(rest, deps, "close");
+    case "settle":
+      return runChannelWithdrawStep(rest, deps, "settle");
+    case "help":
+    case "--help":
+    case "-h":
+      io2.out(CHANNEL_USAGE);
+      return 0;
+    case void 0:
+      io2.err(CHANNEL_USAGE);
+      return 2;
+    default:
+      io2.err(`rig channel: unknown subcommand ${JSON.stringify(sub)}`);
+      io2.err(CHANNEL_USAGE);
+      return 2;
+  }
+}
+function runChannelList(args, deps) {
+  const { io: io2, env } = deps;
+  let json = false;
+  try {
+    const { values } = parseArgs4({
+      args,
+      options: {
+        json: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false }
+      }
+    });
+    if (values.help) {
+      io2.out(CHANNEL_USAGE);
+      return 0;
+    }
+    json = values.json ?? false;
+  } catch (err) {
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(CHANNEL_USAGE);
+    return 2;
+  }
+  try {
+    const paths = resolveChannelPaths(env);
+    const store = new ChannelMapStore(paths);
+    const records = store.list();
+    const rows = records.map((record) => describeChannel(record, store));
+    if (json) {
+      io2.emitJson({ command: "channel list", channels: rows });
+      return 0;
+    }
+    if (rows.length === 0) {
+      io2.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."
+      );
+      return 0;
+    }
+    io2.out(
+      `${rows.length} payment channel${rows.length === 1 ? "" : "s"} recorded in ${paths.mapPath}:`
+    );
+    for (const row of rows) {
+      io2.out("");
+      for (const line of renderChannel(row)) io2.out(line);
+    }
+    return 0;
+  } catch (err) {
+    return emitCliError(io2, json, "channel list", err);
+  }
+}
+function describeChannel(record, store) {
+  const watermark = store.readWatermark(
+    record.channelId
+  );
+  return {
+    channelId: record.channelId,
+    peerId: record.peerId,
+    identity: record.identity,
+    destination: record.destination,
+    chain: record.chain,
+    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})`;
+  return [
+    `channel ${row.channelId} [${row.status}]`,
+    `  peer        ${row.destination} (${row.peerId})`,
+    `  identity    ${row.identity.slice(0, 8)}\u2026`,
+    `  chain       ${row.chain}` + (row.tokenNetwork ? `  token-network ${row.tokenNetwork}` : ""),
+    `  deposited   ${row.depositTotal ?? "unrecorded"}` + (row.depositTotal ? " base units" : ""),
+    `  claimed     ${claimed}`,
+    `  opened      ${row.openedAt}  (last used ${row.lastUsedAt})`
+  ];
+}
+async function loadMoneyContext(deps, options) {
+  const ctx = await (deps.loadStandalone ?? defaultLoadStandalone)({
+    env: deps.env,
+    cwd: deps.cwd,
+    warn: (line) => deps.io.err(line),
+    ...options?.channelDestination ? { channelDestination: options.channelDestination } : {}
+  });
+  const money = ctx.money;
+  if (!money) {
+    await ctx.stop().catch(() => void 0);
+    throw new Error(
+      "this standalone loader does not expose money operations \u2014 channel open/close/settle need the #263 loader"
+    );
+  }
+  return { ctx, money };
+}
+async function confirmOnChain(io2, flags, question) {
+  if (flags.yes) return "proceed";
+  if (flags.json) return "json-plan";
+  if (!io2.isInteractive) {
+    io2.err(
+      "refusing to move on-chain funds without confirmation in a non-interactive session \u2014 re-run with --yes (or use --json for a plan)"
+    );
+    return 1;
+  }
+  const proceed = await io2.confirm(question);
+  if (proceed) return "proceed";
+  io2.err("aborted \u2014 no on-chain transaction was sent.");
+  return 1;
+}
+function formatUnixSeconds(value) {
+  const ms = Number(value) * 1e3;
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : `t=${value}s`;
+}
+function secondsUntil(value, nowSec) {
+  return Number(value) - nowSec;
+}
+async function runChannelOpen(args, deps) {
+  const { io: io2 } = deps;
+  let peer;
+  let deposit;
+  let yes = false;
+  let json = false;
+  try {
+    const { values } = parseArgs4({
+      args,
+      options: {
+        peer: { type: "string" },
+        deposit: { type: "string" },
+        yes: { type: "boolean", default: false },
+        json: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false }
+      }
+    });
+    if (values.help) {
+      io2.out(CHANNEL_USAGE);
+      return 0;
+    }
+    peer = values.peer;
+    yes = values.yes ?? false;
+    json = values.json ?? false;
+    if (values.deposit !== void 0) {
+      if (!/^\d+$/.test(values.deposit) || BigInt(values.deposit) <= 0n) {
+        throw new Error(
+          `--deposit must be a positive base-unit integer, got ${JSON.stringify(values.deposit)}`
+        );
+      }
+      deposit = BigInt(values.deposit);
+    }
+  } catch (err) {
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(CHANNEL_USAGE);
+    return 2;
+  }
+  let ctx;
+  try {
+    const loaded = await loadMoneyContext(deps, {
+      ...peer ? { channelDestination: peer } : {}
+    });
+    ctx = loaded.ctx;
+    const identity = identityReport(ctx);
+    const plan = {
+      destination: peer ?? null,
+      deposit: deposit?.toString() ?? null
+    };
+    if (!json) {
+      io2.out("Channel open plan:");
+      io2.out(`  peer (ILP)  ${peer ?? "(configured default destination)"}`);
+      io2.out(
+        `  deposit     ${deposit !== void 0 ? `+${deposit} base units of extra collateral after the open/resume` : "none beyond the peer-negotiated initial deposit"}`
+      );
+      io2.out(renderIdentityLine(identity));
+      io2.out(
+        "If a live channel is already recorded for this peer it is RESUMED (no on-chain spend); otherwise an on-chain channel open locks the peer-negotiated initial deposit from your wallet (plus gas)."
+      );
+    }
+    const gate = await confirmOnChain(
+      io2,
+      { yes, json },
+      "Proceed with on-chain channel open? [y/N] "
+    );
+    if (gate === "json-plan") {
+      io2.emitJson({
+        command: "channel open",
+        identity,
+        executed: false,
+        plan,
+        hint: "plan only \u2014 re-run with --yes to open (on-chain: locks collateral and spends gas)"
+      });
+      return 0;
+    }
+    if (gate !== "proceed") return gate;
+    const outcome = await loaded.money.openChannel(
+      deposit !== void 0 ? { deposit } : void 0
+    );
+    if (json) {
+      io2.emitJson({
+        command: "channel open",
+        identity,
+        executed: true,
+        plan,
+        result: {
+          channelId: outcome.channelId,
+          resumed: outcome.resumed,
+          destination: outcome.destination,
+          chain: outcome.chain ?? null,
+          peerId: outcome.peerId ?? null,
+          depositTotal: outcome.depositTotal ?? null,
+          depositAdded: outcome.depositAdded ?? null,
+          depositTxHash: outcome.depositTxHash ?? null
+        }
+      });
+      return 0;
+    }
+    io2.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.`
+    );
+    io2.out(`  peer        ${outcome.destination}${outcome.peerId ? ` (${outcome.peerId})` : ""}`);
+    if (outcome.depositAdded) {
+      io2.out(
+        `  deposited   +${outcome.depositAdded} base units` + (outcome.depositTxHash ? `  (tx ${outcome.depositTxHash})` : "")
+      );
+    }
+    if (outcome.depositTotal) {
+      io2.out(`  collateral  ${outcome.depositTotal} base units total on-chain`);
+    }
+    return 0;
+  } catch (err) {
+    return emitCliError(io2, json, "channel open", err);
+  } finally {
+    await stopQuietly(ctx);
+  }
+}
+function withdrawPrecheck(step, channelId, watermark, nowSec) {
+  const status = channelStatus(watermark, nowSec);
+  if (status === "settled") {
+    return `channel ${channelId} is already settled \u2014 nothing left to ${step}.`;
+  }
+  if (step === "close") {
+    if (status === "closing" || status === "settleable") {
+      const at = watermark?.settleableAt;
+      return `channel ${channelId} is already closing \u2014 ` + (status === "settleable" ? "its challenge window has elapsed; run `rig channel settle` to release the collateral." : `settleable at ${at ? formatUnixSeconds(at) : "the end of its challenge window"} (run \`rig channel settle\` then).`);
+    }
+    return void 0;
+  }
+  if (status === "open") {
+    return `channel ${channelId} is not closed \u2014 run \`rig channel close ${channelId}\` first (settle only releases collateral after the challenge window of a closed channel).`;
+  }
+  if (status === "closing" && watermark?.settleableAt !== void 0) {
+    const remain = secondsUntil(watermark.settleableAt, nowSec);
+    return `channel ${channelId} is not settleable yet \u2014 the challenge window is still open (${remain}s remain, settleable at ${formatUnixSeconds(watermark.settleableAt)}). Nothing was spent; re-run after that time.`;
+  }
+  return void 0;
+}
+async function runChannelWithdrawStep(args, deps, step) {
+  const { io: io2, env } = deps;
+  const command = `channel ${step}`;
+  let channelId;
+  let yes = false;
+  let json = false;
+  try {
+    const { values, positionals } = parseArgs4({
+      args,
+      options: {
+        yes: { type: "boolean", default: false },
+        json: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false }
+      },
+      allowPositionals: true
+    });
+    if (values.help) {
+      io2.out(CHANNEL_USAGE);
+      return 0;
+    }
+    yes = values.yes ?? false;
+    json = values.json ?? false;
+    if (positionals.length !== 1) {
+      throw new Error(
+        `rig channel ${step} takes exactly one <channelId> (got ${positionals.length}) \u2014 \`rig channel list\` shows recorded channels`
+      );
+    }
+    channelId = positionals[0];
+  } catch (err) {
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(CHANNEL_USAGE);
     return 2;
   }
-  if (flags.help) {
-    io.out(PUSH_USAGE);
-    return 0;
-  }
-  let standaloneCtx;
+  let ctx;
   try {
-    const repoRoot = await resolveRepoRoot(deps.cwd);
-    const toonConfig = await readToonConfig(repoRoot);
-    const repoId = flags.repoId ?? toonConfig.repoId;
-    if (!repoId) throw new UnconfiguredRepoAddressError("repository id");
-    const reader = new GitRepoReader(repoRoot);
-    let remoteName;
-    let refspecArgs = flags.positionals;
-    if (flags.relay.length === 0 && refspecArgs.length > 0) {
-      const first = refspecArgs[0];
-      const remoteNames = new Set(
-        (await listGitRemotes(repoRoot)).map((r) => r.name)
+    const store = new ChannelMapStore(resolveChannelPaths(env));
+    const record = store.list().find((r) => r.channelId === channelId);
+    if (!record) {
+      throw new Error(
+        `no recorded channel ${JSON.stringify(channelId)} \u2014 \`rig channel list\` shows the channels this identity holds`
       );
-      if (remoteNames.has(first)) {
-        remoteName = first;
-        refspecArgs = refspecArgs.slice(1);
-      } else {
-        const { refs } = await reader.listRefs();
-        const known = new Set(refs.map((r) => r.refname));
-        if (!known.has(first) && !known.has(`refs/heads/${first}`) && !known.has(`refs/tags/${first}`)) {
-          throw new Error(
-            `${JSON.stringify(first)} is neither a configured remote nor a local branch/tag \u2014 add the relay remote (\`rig remote add ${first} <relay-url>\`; \`rig remote list\` shows configured remotes) or fix the refspec`
-          );
-        }
-      }
-    }
-    const refspecs = await selectRefspecs(
-      reader,
-      refspecArgs,
-      flags.all,
-      flags.tags
-    );
-    const resolved = await resolveRelays({
-      relayFlags: flags.relay,
-      remoteName,
-      repoRoot,
-      toonRelays: toonConfig.relays
-    });
-    if (resolved.nudge !== void 0) io.err(resolved.nudge);
-    const relaysUsed = resolved.relays;
-    if (relaysUsed.length > 1) {
-      io.err(singleRelayRefusal(resolved, "Nothing was uploaded or paid."));
-      return 1;
     }
-    standaloneCtx = await (deps.loadStandalone ?? defaultLoadStandalone)({
-      env,
-      cwd: deps.cwd,
-      warn: (line) => io.err(line)
-    });
-    const identity = identityReport(standaloneCtx);
-    if (toonConfig.owner && toonConfig.owner !== identity.pubkey) {
-      io.err(
-        `warning: git config toon.owner (${toonConfig.owner.slice(0, 8)}\u2026) differs from the active identity (${identity.pubkey.slice(0, 8)}\u2026) \u2014 this push publishes under the ACTIVE identity's repo namespace, not the configured owner's. Re-run \`rig init\` to adopt the active identity.`
+    const watermark = store.readWatermark(channelId);
+    const nowSec = Math.floor(Date.now() / 1e3);
+    const refusal = withdrawPrecheck(step, channelId, watermark, nowSec);
+    if (refusal) throw new Error(refusal);
+    const loaded = await loadMoneyContext(deps);
+    ctx = loaded.ctx;
+    const identity = identityReport(ctx);
+    if (record.identity !== identity.pubkey) {
+      throw new Error(
+        `channel ${channelId} was opened by identity ${record.identity.slice(0, 8)}\u2026 but the active identity is ${identity.pubkey.slice(0, 8)}\u2026 (from ${identity.sourceLabel}) \u2014 on-chain ${step} must be signed by the opener's wallet key. Switch RIG_MNEMONIC (or the keystore) to that identity.`
       );
     }
-    const remoteState = await standaloneCtx.fetchRemote({
-      ownerPubkey: standaloneCtx.ownerPubkey,
-      repoId,
-      relayUrls: relaysUsed
-    });
-    const feeRates = await standaloneCtx.publisher.getFeeRates();
-    const pushPlan = await planPush({
-      repoReader: reader,
-      remoteState,
-      feeRates,
-      repoId,
-      refs: refspecs,
-      force: flags.force
-    });
-    const plan = serializePushPlan(pushPlan);
-    const upToDate = plan.refUpdates.every((u) => u.kind === "up-to-date");
-    if (upToDate) {
-      if (flags.json) {
-        io.out(
-          jsonOut({ command: "push", repoId, identity, executed: false, upToDate: true, plan })
+    if (!json) {
+      const claimed = watermark?.cumulativeAmount;
+      io2.out(`Channel ${step} plan:`);
+      io2.out(`  channel     ${channelId} [${channelStatus(watermark, nowSec)}]`);
+      io2.out(`  peer        ${record.destination} (${record.peerId})`);
+      io2.out(`  chain       ${record.chain}`);
+      io2.out(
+        `  deposited   ${record.depositTotal ?? "unrecorded"}` + (claimed !== void 0 ? `   claimed ${claimed} base units` : "")
+      );
+      io2.out(renderIdentityLine(identity));
+      if (step === "close") {
+        io2.out(
+          "Closing is an ON-CHAIN transaction (gas) that starts the settlement challenge window: the channel stops paying immediately, and the remaining collateral stays locked until `rig channel settle` succeeds after the window elapses."
         );
       } else {
-        io.out("Everything up-to-date \u2014 nothing to push (and nothing paid).");
+        io2.out(
+          "Settling is an ON-CHAIN transaction (gas) that releases the remaining collateral back to your wallet. The chain's challenge window is authoritative \u2014 a too-early settle is refused before any gas is spent."
+        );
       }
-      return 0;
     }
-    if (!flags.json) {
-      for (const line of renderPlan(plan)) io.out(line);
-      io.out(renderIdentityLine(identity));
+    const gate = await confirmOnChain(
+      io2,
+      { yes, json },
+      `Proceed with on-chain channel ${step}? [y/N] `
+    );
+    if (gate === "json-plan") {
+      io2.emitJson({
+        command,
+        identity,
+        executed: false,
+        channelId,
+        hint: `plan only \u2014 re-run with --yes to ${step} (on-chain transaction)`
+      });
+      return 0;
     }
-    if (!flags.yes) {
-      if (flags.json) {
-        io.out(
-          jsonOut({
-            command: "push",
-            repoId,
-            identity,
-            executed: false,
-            upToDate: false,
-            plan,
-            hint: "estimate only \u2014 re-run with --yes to upload and publish (permanent, non-refundable)"
-          })
-        );
+    if (gate !== "proceed") return gate;
+    if (step === "close") {
+      const result2 = await loaded.money.closeChannel(record);
+      if (json) {
+        io2.emitJson({
+          command,
+          identity,
+          executed: true,
+          channelId,
+          result: {
+            txHash: result2.txHash ?? null,
+            closedAt: result2.closedAt,
+            settleableAt: result2.settleableAt
+          }
+        });
         return 0;
       }
-      if (!io.isInteractive) {
-        io.err(
-          "refusing to spend channel funds without confirmation in a non-interactive session \u2014 re-run with --yes (or use --json for an estimate)"
-        );
-        return 1;
-      }
-      const proceed = await io.confirm(
-        `Proceed with paid push (total ${plan.estimate.totalFee} base units)? [y/N] `
+      io2.out(
+        `Channel ${channelId} is closing` + (result2.txHash ? ` (tx ${result2.txHash})` : "") + "."
       );
-      if (!proceed) {
-        io.err("aborted \u2014 nothing was uploaded or published.");
-        return 1;
-      }
-    }
-    const pushResult = await executePush({
-      plan: pushPlan,
-      publisher: standaloneCtx.publisher,
-      remoteState,
-      repoReader: reader,
-      relayUrls: relaysUsed
-    });
-    const result = serializePushResult(pushPlan, pushResult);
-    if (flags.json) {
-      io.out(
-        jsonOut({ command: "push", repoId, identity, executed: true, upToDate: false, plan, result })
+      io2.out(
+        `  challenge window: settleable at ${formatUnixSeconds(result2.settleableAt)} (~${Math.max(0, secondsUntil(result2.settleableAt, nowSec))}s from now)`
       );
-    } else {
-      for (const line of renderResult(result)) io.out(line);
+      io2.out(
+        `  run \`rig channel settle ${channelId}\` after that time to release the collateral.`
+      );
+      return 0;
+    }
+    const result = await loaded.money.settleChannel(record);
+    if (json) {
+      io2.emitJson({
+        command,
+        identity,
+        executed: true,
+        channelId,
+        result: { txHash: result.txHash ?? null }
+      });
+      return 0;
     }
+    io2.out(
+      `Channel ${channelId} settled` + (result.txHash ? ` (tx ${result.txHash})` : "") + " \u2014 the remaining collateral was released to your wallet."
+    );
     return 0;
   } catch (err) {
-    const described = describeError(err);
-    if (flags.json) {
-      io.out(JSON.stringify({ command: "push", ...described.json }, null, 2));
-    } else {
-      for (const line of described.lines) io.err(line);
-    }
-    return 1;
+    return emitCliError(io2, json, command, err);
   } finally {
-    if (standaloneCtx) {
-      try {
-        await standaloneCtx.stop();
-      } catch {
-      }
-    }
+    await stopQuietly(ctx);
   }
 }
-function jsonOut(output) {
-  return JSON.stringify(output, null, 2);
+async function stopQuietly(ctx) {
+  if (!ctx) return;
+  try {
+    await ctx.stop();
+  } catch {
+  }
 }
 
 // src/cli/events.ts
+import { readFile } from "fs/promises";
+import { parseArgs as parseArgs5 } from "util";
+import {
+  REPOSITORY_ANNOUNCEMENT_KIND,
+  STATUS_APPLIED_KIND,
+  STATUS_CLOSED_KIND,
+  STATUS_DRAFT_KIND,
+  STATUS_OPEN_KIND
+} from "@toon-protocol/core/nip34";
 var defaultReadStdin = async () => {
   if (process.stdin.isTTY) return "";
   const chunks = [];
@@ -1014,7 +1643,7 @@ function pickCommon(values) {
 }
 async function runEvent(opts) {
   const { command, flags, deps, actionLabel } = opts;
-  const { io, env } = deps;
+  const { io: io2, env } = deps;
   let standaloneCtx;
   try {
     let repoRoot;
@@ -1032,16 +1661,18 @@ async function runEvent(opts) {
       repoRoot,
       toonRelays: toonConfig.relays
     });
-    if (resolved.nudge !== void 0) io.err(resolved.nudge);
+    if (resolved.nudge !== void 0) io2.err(resolved.nudge);
     const relaysUsed = resolved.relays;
     if (relaysUsed.length > 1) {
-      io.err(singleRelayRefusal(resolved, "Nothing was published or paid."));
+      io2.err(singleRelayRefusal(resolved, "Nothing was published or paid."));
       return 1;
     }
     standaloneCtx = await (deps.loadStandalone ?? defaultLoadStandalone)({
       env,
       cwd: deps.cwd,
-      warn: (line) => io.err(line)
+      warn: (line) => io2.err(line),
+      // Relay-origin for #264 network bootstrap (announce discovery).
+      ...relaysUsed[0] !== void 0 ? { relayUrl: relaysUsed[0] } : {}
     });
     const identity = identityReport(standaloneCtx);
     const fee = (await standaloneCtx.publisher.getFeeRates()).eventFee.toString();
@@ -1051,64 +1682,54 @@ async function runEvent(opts) {
     const action = `kind:${event.kind} ${actionLabel}`;
     if (!flags.json) {
       for (const line of renderEventPlan({ action, addr, identity, fee })) {
-        io.out(line);
+        io2.out(line);
       }
     }
     if (!flags.yes) {
       if (flags.json) {
-        io.out(
-          jsonOut2({
-            command,
-            repoAddr: addr,
-            identity,
-            kind: event.kind,
-            executed: false,
-            feeEstimate: fee,
-            hint: "estimate only \u2014 re-run with --yes to publish (permanent, non-refundable)"
-          })
-        );
+        io2.emitJson({
+          command,
+          repoAddr: addr,
+          identity,
+          kind: event.kind,
+          executed: false,
+          feeEstimate: fee,
+          hint: "estimate only \u2014 re-run with --yes to publish (permanent, non-refundable)"
+        });
         return 0;
       }
-      if (!io.isInteractive) {
-        io.err(
+      if (!io2.isInteractive) {
+        io2.err(
           "refusing to spend channel funds without confirmation in a non-interactive session \u2014 re-run with --yes (or use --json for an estimate)"
         );
         return 1;
       }
-      const proceed = await io.confirm(
+      const proceed = await io2.confirm(
         `Proceed with paid publish (${feeLabel(fee)})? [y/N] `
       );
       if (!proceed) {
-        io.err("aborted \u2014 nothing was published.");
+        io2.err("aborted \u2014 nothing was published.");
         return 1;
       }
     }
     const receipt = await standaloneCtx.publisher.publishEvent(event, relaysUsed);
     const result = serializeEventReceipt(event.kind, receipt);
     if (flags.json) {
-      io.out(
-        jsonOut2({
-          command,
-          repoAddr: addr,
-          identity,
-          kind: result.kind,
-          executed: true,
-          feeEstimate: fee,
-          result
-        })
-      );
+      io2.emitJson({
+        command,
+        repoAddr: addr,
+        identity,
+        kind: result.kind,
+        executed: true,
+        feeEstimate: fee,
+        result
+      });
     } else {
-      for (const line of renderEventReceipt(action, result)) io.out(line);
+      for (const line of renderEventReceipt(action, result)) io2.out(line);
     }
     return 0;
   } catch (err) {
-    const described = describeError(err, command);
-    if (flags.json) {
-      io.out(JSON.stringify({ command, ...described.json }, null, 2));
-    } else {
-      for (const line of described.lines) io.err(line);
-    }
-    return 1;
+    return emitCliError(io2, flags.json, command, err);
   } finally {
     if (standaloneCtx) {
       try {
@@ -1118,21 +1739,18 @@ async function runEvent(opts) {
     }
   }
 }
-function jsonOut2(output) {
-  return JSON.stringify(output, null, 2);
-}
 async function runIssue(args, deps) {
-  const { io } = deps;
+  const { io: io2 } = deps;
   const [sub, ...rest] = args;
   if (sub === "--help" || sub === "-h" || sub === "help") {
-    io.out(ISSUE_USAGE);
+    io2.out(ISSUE_USAGE);
     return 0;
   }
   if (sub !== "create") {
-    io.err(
+    io2.err(
       sub === void 0 ? "missing subcommand: rig issue create" : `unknown rig issue subcommand: ${sub}`
     );
-    io.err(ISSUE_USAGE);
+    io2.err(ISSUE_USAGE);
     return 2;
   }
   let flags;
@@ -1141,7 +1759,7 @@ async function runIssue(args, deps) {
   let bodyFile;
   let labels;
   try {
-    const { values } = parseArgs3({
+    const { values } = parseArgs5({
       args: rest,
       options: {
         ...COMMON_OPTIONS,
@@ -1164,12 +1782,12 @@ async function runIssue(args, deps) {
     bodyFile = values["body-file"];
     labels = values.label ?? [];
   } catch (err) {
-    io.err(err instanceof Error ? err.message : String(err));
-    io.err(ISSUE_USAGE);
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(ISSUE_USAGE);
     return 2;
   }
   if (flags.help) {
-    io.out(ISSUE_USAGE);
+    io2.out(ISSUE_USAGE);
     return 0;
   }
   let body;
@@ -1179,20 +1797,20 @@ async function runIssue(args, deps) {
     try {
       body = await readFile(bodyFile, "utf-8");
     } catch (err) {
-      io.err(
+      io2.err(
         `cannot read --body-file ${bodyFile}: ${err instanceof Error ? err.message : String(err)}`
       );
       return 2;
     }
-  } else if (!io.isInteractive) {
+  } else if (!io2.isInteractive) {
     body = await (deps.readStdin ?? defaultReadStdin)();
   } else {
-    io.err("an issue body is required: pass --body/--body-file or pipe stdin");
-    io.err(ISSUE_USAGE);
+    io2.err("an issue body is required: pass --body/--body-file or pipe stdin");
+    io2.err(ISSUE_USAGE);
     return 2;
   }
   if (body.trim() === "") {
-    io.err("the issue body is empty \u2014 nothing to publish");
+    io2.err("the issue body is empty \u2014 nothing to publish");
     return 2;
   }
   return runEvent({
@@ -1204,14 +1822,14 @@ async function runIssue(args, deps) {
   });
 }
 async function runComment(args, deps) {
-  const { io } = deps;
+  const { io: io2 } = deps;
   let flags;
   let rootEventId;
   let body;
   let parentAuthor;
   let marker;
   try {
-    const { values, positionals } = parseArgs3({
+    const { values, positionals } = parseArgs5({
       args,
       options: {
         ...COMMON_OPTIONS,
@@ -1223,7 +1841,7 @@ async function runComment(args, deps) {
     });
     flags = pickCommon(values);
     if (flags.help) {
-      io.out(COMMENT_USAGE);
+      io2.out(COMMENT_USAGE);
       return 0;
     }
     if (positionals.length !== 1) {
@@ -1245,8 +1863,8 @@ async function runComment(args, deps) {
     }
     marker = rawMarker;
   } catch (err) {
-    io.err(err instanceof Error ? err.message : String(err));
-    io.err(COMMENT_USAGE);
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(COMMENT_USAGE);
     return 2;
   }
   return runEvent({
@@ -1269,7 +1887,7 @@ function extractPatchShas(patchText) {
   return [...patchText.matchAll(PATCH_FROM_RE)].map((m) => m[1]);
 }
 async function runPr(args, deps) {
-  const { io } = deps;
+  const { io: io2 } = deps;
   const [sub, ...rest] = args;
   switch (sub) {
     case "create":
@@ -1279,25 +1897,25 @@ async function runPr(args, deps) {
     case "--help":
     case "-h":
     case "help":
-      io.out(PR_USAGE);
+      io2.out(PR_USAGE);
       return 0;
     default:
-      io.err(
+      io2.err(
         sub === void 0 ? "missing subcommand: rig pr <create|status>" : `unknown rig pr subcommand: ${sub}`
       );
-      io.err(PR_USAGE);
+      io2.err(PR_USAGE);
       return 2;
   }
 }
 async function runPrCreate(rest, deps) {
-  const { io } = deps;
+  const { io: io2 } = deps;
   let flags;
   let title;
   let range;
   let patchFile;
   let branch;
   try {
-    const { values } = parseArgs3({
+    const { values } = parseArgs5({
       args: rest,
       options: {
         ...COMMON_OPTIONS,
@@ -1310,7 +1928,7 @@ async function runPrCreate(rest, deps) {
     });
     flags = pickCommon(values);
     if (flags.help) {
-      io.out(PR_CREATE_USAGE);
+      io2.out(PR_CREATE_USAGE);
       return 0;
     }
     if (values.title === void 0 || values.title === "") {
@@ -1324,8 +1942,8 @@ async function runPrCreate(rest, deps) {
     patchFile = values["patch-file"];
     branch = values.branch;
   } catch (err) {
-    io.err(err instanceof Error ? err.message : String(err));
-    io.err(PR_CREATE_USAGE);
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(PR_CREATE_USAGE);
     return 2;
   }
   return runEvent({
@@ -1378,19 +1996,19 @@ function isStatusValue(value) {
   return Object.hasOwn(STATUS_KIND_BY_VALUE, value);
 }
 async function runPrStatus(args, deps) {
-  const { io } = deps;
+  const { io: io2 } = deps;
   let flags;
   let targetEventId;
   let status;
   try {
-    const { values, positionals } = parseArgs3({
+    const { values, positionals } = parseArgs5({
       args,
       options: COMMON_OPTIONS,
       allowPositionals: true
     });
     flags = pickCommon(values);
     if (flags.help) {
-      io.out(PR_STATUS_USAGE);
+      io2.out(PR_STATUS_USAGE);
       return 0;
     }
     if (positionals.length !== 2) {
@@ -1408,8 +2026,8 @@ async function runPrStatus(args, deps) {
     }
     status = rawStatus;
   } catch (err) {
-    io.err(err instanceof Error ? err.message : String(err));
-    io.err(PR_STATUS_USAGE);
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(PR_STATUS_USAGE);
     return 2;
   }
   return runEvent({
@@ -1428,6 +2046,169 @@ async function runPrStatus(args, deps) {
   });
 }
 
+// src/cli/fund.ts
+import { readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { parseArgs as parseArgs6 } from "util";
+var DEVNET_FAUCET_URL = "https://faucet.devnet.toonprotocol.dev";
+var CHAINS = ["evm", "solana", "mina"];
+var FUND_USAGE = `Usage: rig fund [options]
+
+Drip devnet test funds to the active identity's wallet \u2014 free (the faucet
+pays). The identity comes from RIG_MNEMONIC (env or a project .env) or the
+~/.toon-client keystore/config; the faucet from TOON_CLIENT_FAUCET_URL, the
+faucetUrl config field, or the deployed devnet faucet when the configured
+network is devnet. The faucet drips a FIXED amount per chain (there is no
+--amount). On a network without a faucet, prints the wallet address(es) to
+fund externally instead.
+
+Options:
+  --chain <chain>      evm | solana | mina (default: TOON_CLIENT_CHAIN, the
+                       \`chain\` config field, else evm)
+  --address <address>  fund this address instead of the identity's own
+  --json               machine-readable envelope
+  -h, --help           show this help`;
+function readFundConfig(env) {
+  const dir = env["TOON_CLIENT_HOME"] ?? join(homedir(), ".toon-client");
+  const configPath = join(dir, "config.json");
+  try {
+    return {
+      file: JSON.parse(readFileSync(configPath, "utf8")),
+      configPath
+    };
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { file: {}, configPath };
+    }
+    throw new Error(
+      `failed to read client config at ${configPath}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+async function runFund(args, deps) {
+  const { io: io2, env } = deps;
+  let chainFlag;
+  let addressFlag;
+  let json = false;
+  try {
+    const { values } = parseArgs6({
+      args,
+      options: {
+        chain: { type: "string" },
+        address: { type: "string" },
+        json: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false }
+      }
+    });
+    if (values.help) {
+      io2.out(FUND_USAGE);
+      return 0;
+    }
+    chainFlag = values.chain;
+    addressFlag = values.address;
+    json = values.json ?? false;
+    if (chainFlag !== void 0 && !CHAINS.includes(chainFlag)) {
+      throw new Error(
+        `--chain must be one of ${CHAINS.join(" | ")}, got ${JSON.stringify(chainFlag)}`
+      );
+    }
+  } catch (err) {
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(FUND_USAGE);
+    return 2;
+  }
+  try {
+    const { file } = readFundConfig(env);
+    const chain = chainFlag ?? env["TOON_CLIENT_CHAIN"] ?? file.chain ?? "evm";
+    if (!CHAINS.includes(chain)) {
+      throw new Error(
+        `configured settlement chain ${JSON.stringify(chain)} has no faucet \u2014 pass --chain ${CHAINS.join(" | ")}`
+      );
+    }
+    const network = env["TOON_CLIENT_NETWORK"] ?? file.network;
+    const faucetUrl = env["TOON_CLIENT_FAUCET_URL"] ?? file.faucetUrl ?? (network === "devnet" ? DEVNET_FAUCET_URL : void 0);
+    const resolved = await resolveIdentity({
+      env,
+      cwd: deps.cwd,
+      warn: (line) => io2.err(line)
+    });
+    const identity = {
+      pubkey: resolved.pubkey,
+      source: resolved.source,
+      sourceLabel: resolved.sourceLabel
+    };
+    const client = await import("@toon-protocol/client");
+    const derived = await client.deriveFullIdentity(
+      resolved.mnemonic,
+      resolved.accountIndex
+    );
+    const addresses = {
+      evm: derived.evm.address || null,
+      solana: derived.solana.publicKey || null,
+      mina: derived.mina.publicKey || null
+    };
+    if (!faucetUrl) {
+      const guidance = `no faucet on network ${JSON.stringify(network ?? "custom")} \u2014 fund the wallet externally (send the settlement token + native gas to the address for the chain your channels settle on), or set TOON_CLIENT_FAUCET_URL / the faucetUrl config field if this network has one.`;
+      if (json) {
+        io2.emitJson({
+          command: "fund",
+          identity,
+          funded: false,
+          network: network ?? null,
+          chain,
+          addresses,
+          guidance
+        });
+        return 0;
+      }
+      io2.out(renderIdentityLine(identity));
+      io2.out(guidance);
+      io2.out("Wallet addresses:");
+      io2.out(`  evm     ${addresses.evm ?? "(no key derived)"}`);
+      io2.out(`  solana  ${addresses.solana ?? "(no key derived)"}`);
+      io2.out(`  mina    ${addresses.mina ?? "(no key derived \u2014 optional mina-signer dependency missing)"}`);
+      return 0;
+    }
+    const address = addressFlag ?? addresses[chain];
+    if (!address) {
+      throw new Error(
+        `no ${chain} address could be derived for this identity \u2014 pass an explicit --address (for mina, install the optional mina-signer dependency)`
+      );
+    }
+    const timeoutEnv = env["TOON_CLIENT_FAUCET_TIMEOUT_MS"];
+    const timeout = timeoutEnv && Number.isFinite(Number(timeoutEnv)) ? Number(timeoutEnv) : file.faucetTimeoutMs ?? (chain === "mina" ? 13e4 : 9e4);
+    if (!json) {
+      io2.out(
+        `Requesting ${chain} drip from ${faucetUrl} for ${address} \u2026` + (chain === "mina" ? " (mina settles slowly; this can take ~2 minutes)" : "")
+      );
+    }
+    const { response } = await client.fundWallet(faucetUrl, address, chain, {
+      timeout,
+      ...deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}
+    });
+    if (json) {
+      io2.emitJson({
+        command: "fund",
+        identity,
+        funded: true,
+        network: network ?? null,
+        chain,
+        address,
+        faucetUrl,
+        response
+      });
+      return 0;
+    }
+    io2.out(`Faucet drip succeeded: ${chain} \u2192 ${address}`);
+    io2.out(renderIdentityLine(identity));
+    io2.out("Re-check with `rig balance` (a drip can take a few blocks to land).");
+    return 0;
+  } catch (err) {
+    return emitCliError(io2, json, "fund", err);
+  }
+}
+
 // src/cli/git-passthrough.ts
 import { spawn } from "child_process";
 import { constants as osConstants } from "os";
@@ -1437,11 +2218,11 @@ function signalExitCode(signal) {
   const num = osConstants.signals[signal];
   return num === void 0 ? 1 : 128 + num;
 }
-var runGitPassthrough = (argv, options = {}) => {
+var runGitPassthrough = (argv2, options = {}) => {
   const err = options.err ?? ((line) => process.stderr.write(`${line}
 `));
   return new Promise((resolve) => {
-    const child = spawn("git", argv, {
+    const child = spawn("git", argv2, {
       stdio: "inherit",
       ...options.cwd !== void 0 ? { cwd: options.cwd } : {},
       env: options.env ?? process.env
@@ -1461,7 +2242,7 @@ var runGitPassthrough = (argv, options = {}) => {
       restoreSignals();
       if (spawnErr.code === "ENOENT") {
         err(
-          `rig: git not found \u2014 \`rig ${argv[0] ?? ""}\` is not a rig command, so it is passed through to the system \`git\`, which is not on your PATH. Install git (https://git-scm.com) or fix your PATH.`
+          `rig: git not found \u2014 \`rig ${argv2[0] ?? ""}\` is not a rig command, so it is passed through to the system \`git\`, which is not on your PATH. Install git (https://git-scm.com) or fix your PATH.`
         );
         resolve(GIT_NOT_FOUND_EXIT);
         return;
@@ -1478,7 +2259,7 @@ var runGitPassthrough = (argv, options = {}) => {
 
 // src/cli/init.ts
 import { basename } from "path";
-import { parseArgs as parseArgs4 } from "util";
+import { parseArgs as parseArgs7 } from "util";
 var INIT_USAGE = `Usage: rig init [options]
 
 Set up the current git repository for rig (one-shot, idempotent, free):
@@ -1498,7 +2279,7 @@ Options:
   --json             machine-readable report
   -h, --help         show this help`;
 function parseInitArgs(args) {
-  const { values, positionals } = parseArgs4({
+  const { values, positionals } = parseArgs7({
     args,
     options: {
       "repo-id": { type: "string" },
@@ -1522,17 +2303,17 @@ function parseInitArgs(args) {
   return flags;
 }
 async function runInit(args, deps) {
-  const { io, env } = deps;
+  const { io: io2, env } = deps;
   let flags;
   try {
     flags = parseInitArgs(args);
   } catch (err) {
-    io.err(err instanceof Error ? err.message : String(err));
-    io.err(INIT_USAGE);
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(INIT_USAGE);
     return 2;
   }
   if (flags.help) {
-    io.out(INIT_USAGE);
+    io2.out(INIT_USAGE);
     return 0;
   }
   try {
@@ -1545,7 +2326,7 @@ async function runInit(args, deps) {
     const identity = await (deps.resolveIdentityImpl ?? resolveIdentity)({
       env,
       cwd: deps.cwd,
-      warn: (line) => io.err(line)
+      warn: (line) => io2.err(line)
     });
     const existing = await readToonConfig(repoRoot);
     const repoId = flags.repoId ?? existing.repoId ?? basename(repoRoot);
@@ -1582,50 +2363,44 @@ async function runInit(args, deps) {
         migratedToonRelay,
         changed
       };
-      io.out(JSON.stringify(output, null, 2));
+      io2.emitJson(output);
       return 0;
     }
-    io.out(`Initialized rig for ${repoRoot}`);
-    io.out(renderIdentityLine(identity));
-    io.out(
+    io2.out(`Initialized rig for ${repoRoot}`);
+    io2.out(renderIdentityLine(identity));
+    io2.out(
       `  toon.repoid = ${repoId}` + (changed.repoId ? "" : " (unchanged)") + (existing.repoId && changed.repoId ? ` (was ${existing.repoId})` : "")
     );
-    io.out(
+    io2.out(
       `  toon.owner  = ${identity.pubkey}` + (changed.owner ? "" : " (unchanged)") + (existing.owner && changed.owner ? ` (was ${existing.owner})` : "")
     );
     if (originRelay !== void 0) {
-      io.out(
+      io2.out(
         `  origin      = ${originRelay}` + (migratedToonRelay ? " (migrated from git config toon.relay)" : "")
       );
       if (migratedToonRelay) {
-        io.out(
+        io2.out(
           "note: toon.relay is deprecated \u2014 it stays readable as a fallback and is removed in v0.3; drop it now with `git config --unset-all toon.relay`."
         );
       }
-      io.out('Ready: `rig push` publishes this repo via remote "origin".');
+      io2.out('Ready: `rig push` publishes this repo via remote "origin".');
     } else if (existing.relays.length > 0) {
-      io.out(`  toon.relay  = ${existing.relays.join(", ")} (deprecated)`);
-      io.out(
+      io2.out(`  toon.relay  = ${existing.relays.join(", ")} (deprecated)`);
+      io2.out(
         origin !== void 0 ? `The "origin" remote (${origin.urls.join(", ")}) is not a single relay URL, so toon.relay stays the fallback \u2014 add the relay under another name (\`rig remote add toon <relay-url>\`) and push with \`rig push toon\`.` : existing.relays.length > 1 ? `toon.relay has ${existing.relays.length} values and rig publishes to one relay \u2014 migrate the right one: \`rig remote add origin <relay-url>\`.` : "This value is not a relay URL (ws://, wss://, http://, or https://) \u2014 set a real one: `rig remote add origin <relay-url>`."
       );
     } else if (origin !== void 0) {
-      io.out(
+      io2.out(
         `No relay configured yet \u2014 "origin" (${origin.urls.join(", ")}) is not a relay URL, so add the relay under another name: \`rig remote add toon <relay-url>\`, then \`rig push toon\`.`
       );
     } else {
-      io.out(
+      io2.out(
         "No relay configured yet \u2014 add one as the follow-up step: `rig remote add origin <relay-url>` (a real git remote; `git remote -v` shows it). One-off pushes can pass --relay <url>."
       );
     }
     return 0;
   } catch (err) {
-    const described = describeError(err, "init");
-    if (flags.json) {
-      io.out(JSON.stringify({ command: "init", ...described.json }, null, 2));
-    } else {
-      for (const line of described.lines) io.err(line);
-    }
-    return 1;
+    return emitCliError(io2, flags.json, "init", err);
   }
 }
 
@@ -1651,15 +2426,35 @@ Commands rig owns:
                              \`git format-patch\` content
   pr status <event-id> <state>  set an issue/patch status (kind:1630-1633):
                              open | applied | closed | draft
+  fund                       drip devnet faucet funds to this identity's
+                             wallet (free); on other networks prints the
+                             address(es) to fund externally
+  balance                    wallet balances + payment-channel holdings
+                             (free \u2014 chain reads and local state only)
+  channel list               show the payment channels paid commands hold
+                             (free \u2014 reads local state)
+  channel open               explicitly open (or resume) the channel for a
+                             peer; --deposit adds collateral (on-chain)
+  channel close <channelId>  start the settlement challenge window (on-chain)
+  channel settle <channelId> release collateral after the window (on-chain)
 
 Any other command is passed through to git verbatim: \`rig status\` runs
 \`git status\`, and \`rig add -p\`, \`rig commit\`, \`rig log --oneline\`,
 \`rig rebase -i\`, \u2026 behave exactly like git (same output, same exit code).
 
-Run \`rig <command> --help\` for a rig command's flags. \`rig init\` and
-\`rig remote\` are free; the other rig commands are paid writes \u2014 permanent
-and non-refundable; each quotes its fee and asks for confirmation before
-spending (--yes skips, --json emits machine output).`;
+Run \`rig <command> --help\` for a rig command's flags. \`rig init\`,
+\`rig remote\`, \`rig fund\`, \`rig balance\`, and \`rig channel list\` are
+free; push/issue/comment/pr are paid writes \u2014 permanent and non-refundable \u2014
+and channel open/close/settle are on-chain wallet transactions; each states
+what it will spend and asks for confirmation before doing so (--yes skips,
+--json emits machine output).
+
+With --json, stdout carries exactly ONE JSON document (everything human-facing
+goes to stderr), so \`rig <command> --json | jq\` always parses. --json is a
+per-subcommand flag on the commands rig owns, NOT a global rig flag: it does
+not apply to the git passthrough (\`rig status --json\` runs
+\`git status --json\`), and flags placed before the subcommand
+(\`rig --json status\`) pass through to git untouched.`;
 function rigVersion() {
   const require2 = createRequire(import.meta.url);
   for (const rel of ["../package.json", "../../package.json", "../../../package.json"]) {
@@ -1671,9 +2466,9 @@ function rigVersion() {
   }
   return "unknown";
 }
-async function dispatch(argv, deps) {
-  const [command, ...rest] = argv;
-  const { io } = deps;
+async function dispatch(argv2, deps) {
+  const [command, ...rest] = argv2;
+  const { io: io2 } = deps;
   switch (command) {
     case "init":
       return runInit(rest, deps);
@@ -1687,35 +2482,124 @@ async function dispatch(argv, deps) {
       return runComment(rest, deps);
     case "pr":
       return runPr(rest, deps);
+    case "channel":
+      return runChannel(rest, deps);
+    case "fund":
+      return runFund(rest, deps);
+    case "balance":
+      return runBalance(rest, deps);
     case "help":
     case "--help":
     case "-h":
-      io.out(USAGE);
-      io.out("");
-      io.out(PUSH_USAGE);
+      io2.out(USAGE);
+      io2.out("");
+      io2.out(PUSH_USAGE);
       return 0;
     case "--version":
-      io.out(`rig ${rigVersion()}`);
+      io2.out(`rig ${rigVersion()}`);
       return 0;
     case void 0:
-      io.err(USAGE);
+      io2.err(USAGE);
       return 2;
     default:
-      return (deps.runGit ?? runGitPassthrough)(argv, {
+      return (deps.runGit ?? runGitPassthrough)(argv2, {
         cwd: deps.cwd,
         env: deps.env,
-        err: (line) => io.err(line)
+        err: (line) => io2.err(line)
       });
   }
 }
 
-// src/cli/rig.ts
-function makeIo() {
+// src/cli/output.ts
+function makeCliIo(options) {
+  const { jsonMode, writeStdout, writeStderr } = options;
+  let emittedJson = false;
+  const humanLines = [];
+  const toStderr = (line) => {
+    if (jsonMode) humanLines.push(line);
+    writeStderr(`${line}
+`);
+  };
+  return {
+    jsonMode,
+    get emittedJson() {
+      return emittedJson;
+    },
+    out: (line) => {
+      if (jsonMode) {
+        toStderr(line);
+      } else {
+        writeStdout(`${line}
+`);
+      }
+    },
+    err: toStderr,
+    emitJson: (payload) => {
+      emittedJson = true;
+      writeStdout(`${JSON.stringify(payload, null, 2)}
+`);
+    },
+    isInteractive: options.isInteractive,
+    confirm: options.confirm,
+    ensureSingleJsonDoc(exitCode) {
+      if (!jsonMode || emittedJson) return;
+      const detail = humanLines.join("\n") || (exitCode === 0 ? "the command produced no machine output" : "the command failed before emitting machine output \u2014 see stderr");
+      this.emitJson(
+        exitCode === 0 ? { error: null, exitCode, detail } : { error: "error", exitCode, detail }
+      );
+    }
+  };
+}
+var RIG_OWNED_VERBS = /* @__PURE__ */ new Set([
+  "init",
+  "remote",
+  "push",
+  "issue",
+  "comment",
+  "pr",
+  "channel",
+  "fund",
+  "balance"
+]);
+function isJsonInvocation(argv2) {
+  const [verb, ...rest] = argv2;
+  if (verb === void 0 || !RIG_OWNED_VERBS.has(verb)) return false;
+  for (const arg of rest) {
+    if (arg === "--") return false;
+    if (arg === "--json") return true;
+  }
+  return false;
+}
+function redirectStdoutToStderr(realWrite) {
+  const original = process.stdout.write;
+  const real = realWrite ?? original.bind(process.stdout);
+  const patched = ((chunk, encodingOrCb, cb) => typeof encodingOrCb === "function" ? process.stderr.write(chunk, encodingOrCb) : process.stderr.write(
+    chunk,
+    encodingOrCb,
+    cb
+  ));
+  process.stdout.write = patched;
   return {
-    out: (line) => process.stdout.write(`${line}
-`),
-    err: (line) => process.stderr.write(`${line}
-`),
+    write: (text) => {
+      real(text);
+    },
+    restore: () => {
+      if (process.stdout.write === patched) process.stdout.write = original;
+    }
+  };
+}
+
+// src/cli/rig.ts
+function makeIo(jsonMode) {
+  const guard = jsonMode ? redirectStdoutToStderr() : void 0;
+  return makeCliIo({
+    jsonMode,
+    writeStdout: guard ? guard.write : (text) => {
+      process.stdout.write(text);
+    },
+    writeStderr: (text) => {
+      process.stderr.write(text);
+    },
     isInteractive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
     confirm: async (question) => {
       const rl = createInterface({
@@ -1729,14 +2613,17 @@ function makeIo() {
         rl.close();
       }
     }
-  };
+  });
 }
-dispatch(process.argv.slice(2), {
-  io: makeIo(),
+var argv = process.argv.slice(2);
+var io = makeIo(isJsonInvocation(argv));
+dispatch(argv, {
+  io,
   env: process.env,
   cwd: process.cwd()
 }).then(
   (code) => {
+    io.ensureSingleJsonDoc(code);
     process.exitCode = code;
   },
   (err) => {
@@ -1744,6 +2631,7 @@ dispatch(process.argv.slice(2), {
       `rig: unexpected error: ${err instanceof Error ? err.stack ?? err.message : String(err)}
 `
     );
+    io.ensureSingleJsonDoc(1);
     process.exitCode = 1;
   }
 );