@toon-protocol/rig 2.1.0 → 2.2.0

package/dist/cli/rig.js

@@ -4,27 +4,39 @@ import {
   GitRepoReader,
   NonFastForwardError,
   OversizeObjectsError,
+  collectRepoObjects,
   executePush,
+  isSafeRefname,
+  missingObjectsMessage,
+  ownerToHex,
   planPush,
+  runGit,
   serializeEventReceipt,
   serializePushPlan,
-  serializePushResult
-} from "../chunk-LFGDLD6J.js";
+  serializePushResult,
+  setHeadSymref,
+  updateRef,
+  writeGitObjects
+} from "../chunk-PS5QOT62.js";
 import {
   MissingIdentityError,
   resolveIdentity
 } from "../chunk-CW4HJNMU.js";
 import {
+  COMMENT_KIND,
   buildComment,
   buildIssue,
   buildPatch,
-  buildStatus
-} from "../chunk-HPSOQP7Q.js";
+  buildStatus,
+  fetchRemoteState,
+  queryRelay
+} from "../chunk-JBB7HBQC.js";
 import {
   ChannelMapStore,
   channelStatus,
+  defaultDaemonPort,
   resolveChannelPaths
-} from "../chunk-O6TXHKWG.js";
+} from "../chunk-SW7ZHMGS.js";
 import {
   MAX_OBJECT_SIZE
 } from "../chunk-X2CZPPDM.js";
@@ -38,6 +50,155 @@ import { createRequire } from "module";
 // src/cli/balance.ts
 import { parseArgs as parseArgs3 } from "util";
 
+// src/cli/daemon-session.ts
+function daemonBaseUrl(env) {
+  const raw = env["TOON_CLIENT_HTTP_PORT"];
+  const parsed = raw ? Number(raw) : NaN;
+  const port = Number.isFinite(parsed) && parsed > 0 ? parsed : defaultDaemonPort();
+  return `http://127.0.0.1:${port}`;
+}
+async function probeDaemon(env, fetchImpl, timeoutMs = 1500) {
+  const baseUrl = daemonBaseUrl(env);
+  try {
+    const res = await fetchImpl(`${baseUrl}/status`, {
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!res.ok) return { baseUrl, reachable: false };
+    const body = await res.json();
+    const probe = { baseUrl, reachable: true };
+    const pubkey = body?.identity?.nostrPubkey;
+    if (typeof pubkey === "string" && pubkey !== "") probe.identity = pubkey;
+    if (typeof body?.ready === "boolean") probe.ready = body.ready;
+    if (typeof body?.relay?.url === "string" && body.relay.url !== "") {
+      probe.relayUrl = body.relay.url;
+    }
+    if (typeof body?.feePerEvent === "string" && body.feePerEvent !== "") {
+      probe.feePerEvent = body.feePerEvent;
+    }
+    return probe;
+  } catch {
+    return { baseUrl, reachable: false };
+  }
+}
+var DaemonRouteError = class extends Error {
+  constructor(status, envelope) {
+    super(envelope.detail ?? envelope.error);
+    this.status = status;
+    this.envelope = envelope;
+    this.name = "DaemonRouteError";
+  }
+  status;
+  envelope;
+};
+var DaemonUnreachableError = class extends Error {
+  constructor(baseUrl, cause) {
+    super(
+      `toon-clientd stopped answering at ${baseUrl} after the identity probe \u2014 nothing was paid. Re-run: rig falls back to standalone automatically when no daemon responds` + (cause instanceof Error ? ` (${cause.message})` : "")
+    );
+    this.baseUrl = baseUrl;
+    this.name = "DaemonUnreachableError";
+  }
+  baseUrl;
+};
+var DaemonGitClient = class {
+  constructor(baseUrl, fetchImpl) {
+    this.baseUrl = baseUrl;
+    this.fetchImpl = fetchImpl;
+  }
+  baseUrl;
+  fetchImpl;
+  gitEstimate(req) {
+    return this.post("/git/estimate", req);
+  }
+  gitPush(req) {
+    return this.post("/git/push", req);
+  }
+  gitIssue(req) {
+    return this.post("/git/issue", req);
+  }
+  gitComment(req) {
+    return this.post("/git/comment", req);
+  }
+  gitPatch(req) {
+    return this.post("/git/patch", req);
+  }
+  gitStatus(req) {
+    return this.post("/git/status", req);
+  }
+  async post(path, body) {
+    let res;
+    try {
+      res = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body)
+      });
+    } catch (err) {
+      throw new DaemonUnreachableError(this.baseUrl, err);
+    }
+    const text = await res.text();
+    let parsed;
+    try {
+      parsed = text === "" ? {} : JSON.parse(text);
+    } catch {
+      throw new DaemonRouteError(res.status, {
+        error: "invalid_response",
+        detail: `daemon returned non-JSON (HTTP ${res.status}): ${text.slice(0, 200)}`
+      });
+    }
+    if (!res.ok) {
+      const envelope = parsed && typeof parsed === "object" && "error" in parsed ? parsed : { error: "http_error", detail: `HTTP ${res.status}` };
+      throw new DaemonRouteError(res.status, envelope);
+    }
+    return parsed;
+  }
+};
+async function resolvePaidSession(options) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const probe = await (options.probeDaemon ?? probeDaemon)(
+    options.env,
+    fetchImpl
+  );
+  if (probe.reachable && probe.identity !== void 0) {
+    const identity = await resolveIdentity({
+      env: options.env,
+      cwd: options.cwd,
+      warn: options.warn
+    });
+    if (identity.pubkey === probe.identity) {
+      options.warn(
+        `rig: paid path: daemon \u2014 toon-clientd at ${probe.baseUrl} holds this identity (${identity.pubkey.slice(0, 8)}\u2026), delegating`
+      );
+      return {
+        path: "daemon",
+        client: new DaemonGitClient(probe.baseUrl, fetchImpl),
+        baseUrl: probe.baseUrl,
+        identity: {
+          pubkey: identity.pubkey,
+          source: identity.source,
+          sourceLabel: identity.sourceLabel
+        },
+        ...probe.feePerEvent !== void 0 ? { feePerEvent: probe.feePerEvent } : {},
+        ...probe.relayUrl !== void 0 ? { daemonRelayUrl: probe.relayUrl } : {}
+      };
+    }
+    options.warn(
+      `rig: paid path: standalone \u2014 the toon-clientd at ${probe.baseUrl} runs a different identity (${probe.identity.slice(0, 8)}\u2026), no shared channel state`
+    );
+  } else {
+    options.warn(
+      `rig: paid path: standalone (no toon-clientd at ${probe.baseUrl})`
+    );
+  }
+  const ctx = await options.loadStandalone({
+    env: options.env,
+    cwd: options.cwd,
+    warn: options.warn,
+    ...options.relayUrl !== void 0 ? { relayUrl: options.relayUrl } : {}
+  });
+  return { path: "standalone", ctx };
+}
+
 // src/cli/errors.ts
 var UnconfiguredRepoAddressError = class extends Error {
   constructor(missing) {
@@ -199,6 +360,39 @@ function describeError(err, command = "push") {
       json: { error: "git_error", detail: err.message }
     };
   }
+  if (err instanceof DaemonRouteError) {
+    const envelope = err.envelope;
+    if (envelope.error === "non_fast_forward" && Array.isArray(envelope["refs"])) {
+      return {
+        code: "non_fast_forward",
+        lines: nonFastForwardLines(envelope["refs"]),
+        json: { ...envelope }
+      };
+    }
+    if (envelope.error === "oversize_objects" && Array.isArray(envelope["objects"])) {
+      return {
+        code: "oversize_objects",
+        lines: oversizeLines(envelope["objects"]),
+        json: { ...envelope }
+      };
+    }
+    const retryHint = envelope.retryable === true ? ["The daemon reports this as retryable \u2014 re-run shortly."] : [];
+    return {
+      code: envelope.error,
+      lines: [
+        `daemon rejected the operation (HTTP ${err.status}): ` + (envelope.detail ?? envelope.error),
+        ...retryHint
+      ],
+      json: { ...envelope }
+    };
+  }
+  if (err instanceof DaemonUnreachableError) {
+    return {
+      code: "daemon_unreachable",
+      lines: err.message.split("\n"),
+      json: { error: "daemon_unreachable", detail: err.message }
+    };
+  }
   const name = err instanceof Error ? err.name : "";
   const message = err instanceof Error ? err.message : String(err);
   if (name === "DaemonIdentityConflictError") {
@@ -206,7 +400,7 @@ function describeError(err, command = "push") {
       code: "daemon_identity_conflict",
       lines: [
         message,
-        "Stop the toon-clientd daemon (or publish through its toon_git_* MCP tools) and re-run."
+        "Paid writes delegate to a same-identity daemon automatically; seeing this means the daemon appeared mid-run or this operation has no daemon route \u2014 stop the daemon and re-run."
       ],
       json: { error: "daemon_identity_conflict", detail: message }
     };
@@ -240,6 +434,32 @@ function describeError(err, command = "push") {
       }
     };
   }
+  if (name === "RepoNotFoundError") {
+    return {
+      code: "repo_not_found",
+      lines: message.split("\n"),
+      json: { error: "repo_not_found", detail: message }
+    };
+  }
+  if (name === "MissingRemoteObjectsError") {
+    const missing = err.missing;
+    return {
+      code: "missing_remote_objects",
+      lines: message.split("\n"),
+      json: {
+        error: "missing_remote_objects",
+        detail: message,
+        ...Array.isArray(missing) ? { missing } : {}
+      }
+    };
+  }
+  if (name === "ObjectIntegrityError" || name === "ObjectWriteMismatchError") {
+    return {
+      code: "object_integrity",
+      lines: message.split("\n"),
+      json: { error: "object_integrity", detail: message }
+    };
+  }
   return {
     code: "error",
     lines: [`rig ${command} failed: ${message}`],
@@ -665,8 +885,19 @@ async function runRemote(args, deps) {
 }
 
 // src/cli/push.ts
+function loadPaidSession(deps, relayUrl) {
+  return resolvePaidSession({
+    env: deps.env,
+    cwd: deps.cwd,
+    warn: (line) => deps.io.err(line),
+    loadStandalone: deps.loadStandalone ?? defaultLoadStandalone,
+    ...relayUrl !== void 0 ? { relayUrl } : {},
+    ...deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {},
+    ...deps.probeDaemon ? { probeDaemon: deps.probeDaemon } : {}
+  });
+}
 var defaultLoadStandalone = async (options) => {
-  const mod = await import("../standalone-mode-FCKTQ33Y.js");
+  const mod = await import("../standalone-mode-64CKUVU2.js");
   return mod.createStandaloneContext(options);
 };
 function identityReport(ctx) {
@@ -777,7 +1008,7 @@ function parsePushArgs(args) {
   return flags;
 }
 async function runPush(args, deps) {
-  const { io: io2, env } = deps;
+  const { io: io2 } = deps;
   let flags;
   try {
     flags = parsePushArgs(args);
@@ -835,40 +1066,74 @@ async function runPush(args, deps) {
       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);
+    const session = await loadPaidSession(deps, relaysUsed[0]);
+    const path = session.path;
+    let identity;
+    if (session.path === "standalone") {
+      standaloneCtx = session.ctx;
+      identity = identityReport(standaloneCtx);
+    } else {
+      identity = session.identity;
+    }
     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);
+    let plan;
+    let execute;
+    if (session.path === "standalone") {
+      const ctx = session.ctx;
+      const remoteState = await ctx.fetchRemote({
+        ownerPubkey: ctx.ownerPubkey,
+        repoId,
+        relayUrls: relaysUsed
+      });
+      const feeRates = await ctx.publisher.getFeeRates();
+      const pushPlan = await planPush({
+        repoReader: reader,
+        remoteState,
+        feeRates,
+        repoId,
+        refs: refspecs,
+        force: flags.force
+      });
+      plan = serializePushPlan(pushPlan);
+      execute = async () => serializePushResult(
+        pushPlan,
+        await executePush({
+          plan: pushPlan,
+          publisher: ctx.publisher,
+          remoteState,
+          repoReader: reader,
+          relayUrls: relaysUsed
+        })
+      );
+    } else {
+      const client = session.client;
+      plan = await client.gitEstimate({
+        repoPath: repoRoot,
+        repoId,
+        refspecs,
+        force: flags.force,
+        relayUrls: relaysUsed
+      });
+      execute = () => client.gitPush({
+        repoPath: repoRoot,
+        repoId,
+        refspecs,
+        force: flags.force,
+        relayUrls: relaysUsed,
+        confirm: true
+      });
+    }
     const upToDate = plan.refUpdates.every((u) => u.kind === "up-to-date");
     if (upToDate) {
       if (flags.json) {
         io2.emitJson({
           command: "push",
           repoId,
+          path,
           identity,
           executed: false,
           upToDate: true,
@@ -888,6 +1153,7 @@ async function runPush(args, deps) {
         io2.emitJson({
           command: "push",
           repoId,
+          path,
           identity,
           executed: false,
           upToDate: false,
@@ -910,18 +1176,12 @@ async function runPush(args, deps) {
         return 1;
       }
     }
-    const pushResult = await executePush({
-      plan: pushPlan,
-      publisher: standaloneCtx.publisher,
-      remoteState,
-      repoReader: reader,
-      relayUrls: relaysUsed
-    });
-    const result = serializePushResult(pushPlan, pushResult);
+    const result = await execute();
     if (flags.json) {
       io2.emitJson({
         command: "push",
         repoId,
+        path,
         identity,
         executed: true,
         upToDate: false,
@@ -1210,7 +1470,7 @@ async function loadMoneyContext(deps, options) {
   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"
+      "this standalone loader does not expose money operations \u2014 channel open/close/settle need a loader with the money lifecycle"
     );
   }
   return { ctx, money };
@@ -1519,84 +1779,794 @@ async function stopQuietly(ctx) {
   }
 }
 
+// src/cli/clone.ts
+import { mkdtemp, mkdir, readdir, rename, rm, rmdir } from "fs/promises";
+import { basename, dirname, join, resolve } from "path";
+import { parseArgs as parseArgs5 } from "util";
+var CLONE_USAGE = `Usage: rig clone <relay-url> <owner>/<repo-id> [dir] [options]
+
+Clone a TOON repository \u2014 FREE (relay reads + Arweave gateway downloads; no
+payments, no channel, no identity needed). <relay-url> is a ws:// or wss://
+NIP-01 relay; <owner> is the repo owner's pubkey as npub1\u2026 or 64-char hex;
+[dir] defaults to <repo-id>.
+
+Fetches the kind:30617/30618 repository state, downloads every git object
+the refs need from Arweave gateways (SHA-1 verified \u2014 corrupt content is
+rejected), and materializes a real git repository: objects via git plumbing,
+refs, HEAD, checked-out worktree, toon.* config, and the relay preconfigured
+as the "origin" remote \u2014 so \`rig fetch\`, \`rig push\`, and the issue/pr
+commands work immediately.
+
+Note: recently pushed objects can take 10-20 minutes to become fetchable
+from Arweave gateways. A clone right after a push may report missing
+objects \u2014 retry after propagation.
+
+Options:
+  --concurrency <n>    parallel gateway downloads (default 8)
+  --json               machine-readable result envelope
+  -h, --help           show this help`;
+var RepoNotFoundError = class extends Error {
+  constructor(relay, owner, repoId) {
+    super(
+      `repository 30617:${owner}:${repoId} not found on ${relay} \u2014 no kind:30617 announcement or kind:30618 state event exists there. Check the relay URL, the owner pubkey (npub or hex), and the repo id.`
+    );
+    this.name = "RepoNotFoundError";
+  }
+};
+var MissingRemoteObjectsError = class extends Error {
+  constructor(missing, context) {
+    super(missingObjectsMessage(missing, context));
+    this.missing = missing;
+    this.name = "MissingRemoteObjectsError";
+  }
+  missing;
+};
+var WS_URL_RE = /^wss?:\/\//i;
+function parseCloneArgs(args) {
+  const { values, positionals } = parseArgs5({
+    args,
+    options: {
+      json: { type: "boolean", default: false },
+      concurrency: { type: "string" },
+      help: { type: "boolean", short: "h", default: false }
+    },
+    allowPositionals: true
+  });
+  if (values.help) return { help: true };
+  if (positionals.length < 2 || positionals.length > 3) {
+    throw new Error("expected: rig clone <relay-url> <owner>/<repo-id> [dir]");
+  }
+  const [relayUrl, addr, dir] = positionals;
+  if (!WS_URL_RE.test(relayUrl)) {
+    throw new Error(
+      `<relay-url> must be ws:// or wss:// (got ${JSON.stringify(relayUrl)})`
+    );
+  }
+  const slash = addr.indexOf("/");
+  if (slash <= 0 || slash === addr.length - 1) {
+    throw new Error(
+      `expected <owner>/<repo-id> (npub or 64-char hex owner), got ${JSON.stringify(addr)}`
+    );
+  }
+  const owner = ownerToHex(addr.slice(0, slash));
+  const repoId = addr.slice(slash + 1);
+  let concurrency;
+  if (values.concurrency !== void 0) {
+    concurrency = Number.parseInt(values.concurrency, 10);
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+      throw new Error(`--concurrency must be a positive integer`);
+    }
+  }
+  return {
+    relayUrl,
+    owner,
+    repoId,
+    dir,
+    concurrency,
+    json: values.json === true
+  };
+}
+async function isUsableDestination(dir) {
+  try {
+    const entries = await readdir(dir);
+    return entries.length === 0;
+  } catch (err) {
+    return err.code === "ENOENT";
+  }
+}
+function initialBranch(headSymref) {
+  if (headSymref?.startsWith("refs/heads/")) {
+    const name = headSymref.slice("refs/heads/".length);
+    if (name && isSafeRefname(headSymref)) return name;
+  }
+  return "main";
+}
+async function runClone(args, deps) {
+  const { io: io2 } = deps;
+  let parsed;
+  try {
+    const result = parseCloneArgs(args);
+    if ("help" in result) {
+      io2.out(CLONE_USAGE);
+      return 0;
+    }
+    parsed = result;
+  } catch (err) {
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(CLONE_USAGE);
+    return 2;
+  }
+  const { relayUrl, owner, repoId, json } = parsed;
+  const dest = resolve(deps.cwd, parsed.dir ?? repoId);
+  let tempDir;
+  try {
+    if (!await isUsableDestination(dest)) {
+      throw new Error(
+        `destination path ${JSON.stringify(dest)} already exists and is not an empty directory`
+      );
+    }
+    if (!json) io2.out(`Cloning into '${basename(dest)}'...`);
+    const remoteState = await fetchRemoteState({
+      relayUrls: [relayUrl],
+      ownerPubkey: owner,
+      repoId,
+      ...deps.webSocketFactory ? { webSocketFactory: deps.webSocketFactory } : {},
+      ...deps.resolveSha ? { resolveSha: deps.resolveSha } : {}
+    });
+    if (!remoteState.announced && remoteState.refsEvent === null) {
+      throw new RepoNotFoundError(relayUrl, owner, repoId);
+    }
+    const refs = /* @__PURE__ */ new Map();
+    for (const [refname, sha] of remoteState.refs) {
+      if (!isSafeRefname(refname)) {
+        io2.err(
+          `warning: skipping unsafe ref name from relay: ${JSON.stringify(refname)}`
+        );
+        continue;
+      }
+      refs.set(refname, sha);
+    }
+    if (refs.size === 0) {
+      io2.err(
+        "warning: the repository has no refs yet (announced but never pushed) \u2014 cloning an empty repository"
+      );
+    }
+    const tips = [...new Set(refs.values())];
+    const collected = await collectRepoObjects({
+      tips,
+      shaToTxId: remoteState.shaToTxId,
+      resolveMissing: (shas) => remoteState.resolveMissing(shas),
+      ...deps.fetchFn ? { fetchFn: deps.fetchFn } : {},
+      ...parsed.concurrency !== void 0 ? { concurrency: parsed.concurrency } : {}
+    });
+    if (collected.missing.length > 0) {
+      throw new MissingRemoteObjectsError(
+        collected.missing,
+        `cannot clone ${owner.slice(0, 8)}\u2026/${repoId}`
+      );
+    }
+    for (const { sha, txId } of collected.skippedUnavailable) {
+      io2.err(
+        `warning: unreachable object ${sha} (tx ${txId}) could not be downloaded \u2014 not needed by any ref, continuing`
+      );
+    }
+    const parent = dirname(dest);
+    await mkdir(parent, { recursive: true });
+    tempDir = await mkdtemp(join(parent, `.${basename(dest)}.rig-clone-`));
+    await runGit(tempDir, [
+      "init",
+      "--quiet",
+      `--initial-branch=${initialBranch(remoteState.headSymref)}`
+    ]);
+    const written = await writeGitObjects(tempDir, collected.objects.values());
+    for (const [refname, sha] of refs) {
+      await updateRef(tempDir, refname, sha);
+      if (refname.startsWith("refs/heads/")) {
+        const branch = refname.slice("refs/heads/".length);
+        await updateRef(tempDir, `refs/remotes/origin/${branch}`, sha);
+      }
+    }
+    const head = remoteState.headSymref !== null && isSafeRefname(remoteState.headSymref) && refs.has(remoteState.headSymref) ? remoteState.headSymref : [...refs.keys()].find((r) => r.startsWith("refs/heads/")) ?? null;
+    if (head !== null) {
+      await setHeadSymref(tempDir, head);
+      await runGit(tempDir, ["reset", "--hard", "--quiet"]);
+    }
+    await runGit(tempDir, ["config", "toon.repoid", repoId]);
+    await runGit(tempDir, ["config", "toon.owner", owner]);
+    await runGit(tempDir, ["remote", "add", "origin", relayUrl]);
+    if (head !== null) {
+      const branch = head.slice("refs/heads/".length);
+      await runGit(tempDir, ["config", `branch.${branch}.remote`, "origin"]);
+      await runGit(tempDir, ["config", `branch.${branch}.merge`, head]);
+    }
+    try {
+      await rmdir(dest);
+    } catch {
+    }
+    await rename(tempDir, dest);
+    tempDir = void 0;
+    if (json) {
+      io2.emitJson({
+        command: "clone",
+        repoAddr: { ownerPubkey: owner, repoId },
+        relay: relayUrl,
+        directory: dest,
+        head,
+        refs: Object.fromEntries(refs),
+        name: remoteState.name,
+        objectsDownloaded: written,
+        executed: true
+      });
+    } else {
+      io2.out(`Downloaded ${written} object(s) from Arweave (SHA-1 verified).`);
+      for (const [refname, sha] of refs) {
+        io2.out(`  ${sha.slice(0, 7)}  ${refname}`);
+      }
+      if (head !== null) io2.out(`HEAD is now at ${head}`);
+      io2.out(
+        `Configured toon.repoid=${repoId}, toon.owner=${owner.slice(0, 8)}\u2026, origin \u2192 ${relayUrl}`
+      );
+      io2.out("Done.");
+    }
+    return 0;
+  } catch (err) {
+    return emitCliError(io2, json, "clone", err);
+  } finally {
+    if (tempDir !== void 0) {
+      await rm(tempDir, { recursive: true, force: true }).catch(
+        () => void 0
+      );
+    }
+  }
+}
+
 // src/cli/events.ts
 import { readFile } from "fs/promises";
-import { parseArgs as parseArgs5 } from "util";
+import { parseArgs as parseArgs7 } from "util";
+import {
+  REPOSITORY_ANNOUNCEMENT_KIND as REPOSITORY_ANNOUNCEMENT_KIND2,
+  STATUS_APPLIED_KIND as STATUS_APPLIED_KIND2,
+  STATUS_CLOSED_KIND as STATUS_CLOSED_KIND2,
+  STATUS_DRAFT_KIND as STATUS_DRAFT_KIND2,
+  STATUS_OPEN_KIND as STATUS_OPEN_KIND2
+} from "@toon-protocol/core/nip34";
+
+// src/cli/tracker.ts
+import { parseArgs as parseArgs6 } from "util";
 import {
+  ISSUE_KIND,
+  PATCH_KIND,
   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 = [];
-  for await (const chunk of process.stdin) chunks.push(chunk);
-  return Buffer.concat(chunks).toString("utf-8");
-};
-var COMMON_FLAGS_USAGE = `  --repo-id <id>       repository id / NIP-34 d-tag (default: git config
-                       toon.repoid \u2014 run \`rig init\` to set it)
-  --owner <pubkey>     repository owner pubkey, 64-char hex (default: git config
-                       toon.owner, then the active identity)
-  --remote <name>      publish via this configured git remote (default: the
-                       "origin" remote \u2014 \`rig remote add origin <relay-url>\`)
-  --relay <url>        ad-hoc relay override (exactly one) \u2014 bypasses the
-                       configured remotes. The deprecated v0.1 \`git config
-                       toon.relay\` still works as a fallback, with a nudge
-  --yes                skip the fee confirmation (required when not a TTY)
-  --json               machine-readable receipt; without --yes it is a pure
-                       estimate (nothing published, exit 0)
+var READ_COMMON_FLAGS = `  --repo-id <id>       repository id / NIP-34 d-tag (default: git config)
+  --owner <pubkey>     repository owner (npub or 64-char hex; default: git config)
+  --remote <name>      read via this configured git remote (default: origin)
+  --relay <url>        ad-hoc relay override; repeatable \u2014 reads are merged
+  --json               machine-readable envelope
   -h, --help           show this help`;
-var ISSUE_USAGE = `Usage: rig issue create --title <title> [options]
-
-File an issue (kind:1621) against a TOON repo \u2014 a paid publish; writes are
-permanent and non-refundable. The repo address (30617:<owner>:<repoId>) comes
-from the toon.* git config keys \`rig init\` writes.
+var ISSUE_LIST_USAGE = `Usage: rig issue list [--state open|closed|all] [options]
 
-Body source (exactly one): --body, --body-file, or piped stdin.
+List the repo's issues (kind:1621) with their derived state \u2014 FREE (relay
+reads only). State comes from kind:1630-1633 status events: the latest status
+wins; an issue with no status events is open.
 
 Options:
-  --title <title>      issue title (subject tag) [required]
-  --body <text>        issue body (Markdown)
-  --body-file <path>   read the issue body from a file
-  --label <label>      label (t tag); repeatable
-${COMMON_FLAGS_USAGE}`;
-var COMMENT_USAGE = `Usage: rig comment <root-event-id> --body <text> [options]
+  --state <state>      open | closed | all (default: all)
+${READ_COMMON_FLAGS}`;
+var ISSUE_SHOW_USAGE = `Usage: rig issue show <event-id> [options]
 
-Comment (kind:1622) on an issue or patch \u2014 a paid publish; writes are
-permanent and non-refundable. <root-event-id> is the 64-char hex id of the
-kind:1621 issue / kind:1617 patch being commented on.
+Show one issue (kind:1621): metadata, derived state, body, and its
+kind:1622 comments \u2014 FREE (relay reads only). <event-id> is the 64-char hex
+id \`rig issue create\` printed (also visible in \`rig issue list\`).
 
 Options:
-  --body <text>            comment body (Markdown) [required]
-  --parent-author <pubkey> pubkey of the TARGET event's author (p threading
-                           tag; default: the repo owner)
-  --marker <root|reply>    e-tag marker (default: root \u2014 commenting directly
-                           on the issue/patch)
-${COMMON_FLAGS_USAGE}`;
-var PR_CREATE_USAGE = `Usage: rig pr create --title <title> (--range <range> | --patch-file <path>) [options]
+${READ_COMMON_FLAGS}`;
+var PR_LIST_USAGE = `Usage: rig pr list [--state open|applied|closed|draft|all] [options]
 
-Publish a patch (kind:1617) whose content is REAL \`git format-patch\` output \u2014
-a paid publish; writes are permanent and non-refundable. --range runs
-\`git format-patch --stdout <range>\` in the local repository and derives the
-commit/parent-commit tags; --patch-file publishes a pre-generated patch
-verbatim. A multi-commit range publishes ONE kind:1617 event carrying the
-full series text \u2014 cover-letter threading (one event per commit) is out of
-scope in v1.
+List the repo's patches/PRs (kind:1617) with their derived state \u2014 FREE
+(relay reads only). State comes from kind:1630-1633 status events: the
+latest status wins; a patch with no status events is open.
 
 Options:
-  --title <title>      patch/PR title (subject tag) [required]
-  --range <range>      revision range for format-patch: <rev>, <rev>..<rev>,
-                       or <rev>...<rev> (mutually exclusive with --patch-file)
-  --patch-file <path>  literal patch text to publish
-  --branch <name>      branch name (t tag)
-${COMMON_FLAGS_USAGE}`;
-var PR_STATUS_USAGE = `Usage: rig pr status <target-event-id> <open|applied|closed|draft> [options]
+  --state <state>      open | applied | closed | draft | all (default: all)
+${READ_COMMON_FLAGS}`;
+var PR_SHOW_USAGE = `Usage: rig pr show <event-id> [options]
 
-Set the status of an issue or patch \u2014 a paid publish; writes are permanent
-and non-refundable. Publishes kind:1630 (open), 1631 (applied), 1632
-(closed), or 1633 (draft) against the 64-char hex id of the target event,
+Show one patch/PR (kind:1617): metadata, derived state, the FULL patch text
+(real \`git format-patch\` output \u2014 pipe it to \`git am\` to apply), and its
+kind:1622 comments \u2014 FREE (relay reads only).
+
+Options:
+${READ_COMMON_FLAGS}`;
+var STATUS_BY_KIND = {
+  [STATUS_OPEN_KIND]: "open",
+  [STATUS_APPLIED_KIND]: "applied",
+  [STATUS_CLOSED_KIND]: "closed",
+  [STATUS_DRAFT_KIND]: "draft"
+};
+var STATUS_KINDS = [
+  STATUS_OPEN_KIND,
+  STATUS_APPLIED_KIND,
+  STATUS_CLOSED_KIND,
+  STATUS_DRAFT_KIND
+];
+function tagValue(tags, name) {
+  return tags.find((t) => t[0] === name)?.[1];
+}
+function tagValues(tags, name) {
+  return tags.filter((t) => t[0] === name && t[1]).map((t) => t[1]);
+}
+function deriveStatus(targetEventId, statusEvents) {
+  let winner = null;
+  for (const event of statusEvents) {
+    if (STATUS_BY_KIND[event.kind] === void 0) continue;
+    if (!event.tags.some((t) => t[0] === "e" && t[1] === targetEventId))
+      continue;
+    if (winner === null || event.created_at > winner.created_at || event.created_at === winner.created_at && event.id < winner.id) {
+      winner = event;
+    }
+  }
+  return winner === null ? "open" : STATUS_BY_KIND[winner.kind];
+}
+var RELAY_TIMEOUT_MS = 1e4;
+var HEX64_RE = /^[0-9a-f]{64}$/;
+var WS_URL_RE2 = /^wss?:\/\//i;
+function defaultWebSocketFactory(url) {
+  const ctor = globalThis.WebSocket;
+  if (!ctor) {
+    throw new Error(
+      "No global WebSocket constructor (Node >= 22 required) \u2014 pass webSocketFactory"
+    );
+  }
+  return new ctor(url);
+}
+async function queryAll(relays, filters, webSocketFactory) {
+  const jobs = relays.flatMap(
+    (relay) => filters.map(
+      (filter) => queryRelay(relay, filter, RELAY_TIMEOUT_MS, webSocketFactory)
+    )
+  );
+  const results = await Promise.allSettled(jobs);
+  const byId = /* @__PURE__ */ new Map();
+  let failures = 0;
+  let firstError;
+  for (const result of results) {
+    if (result.status === "rejected") {
+      failures += 1;
+      firstError ??= result.reason;
+      continue;
+    }
+    for (const event of result.value) {
+      if (typeof event.id === "string" && !byId.has(event.id)) {
+        byId.set(event.id, event);
+      }
+    }
+  }
+  if (failures === results.length && results.length > 0) {
+    throw firstError instanceof Error ? firstError : new Error(String(firstError));
+  }
+  return byId;
+}
+var TRACKER_OPTIONS = {
+  json: { type: "boolean", default: false },
+  state: { type: "string" },
+  relay: { type: "string", multiple: true },
+  remote: { type: "string" },
+  "repo-id": { type: "string" },
+  owner: { type: "string" },
+  help: { type: "boolean", short: "h", default: false }
+};
+function pickTrackerFlags(values) {
+  const flags = {
+    json: values["json"] === true,
+    help: values["help"] === true,
+    relay: Array.isArray(values["relay"]) ? values["relay"] : []
+  };
+  if (typeof values["state"] === "string") flags.state = values["state"];
+  if (typeof values["remote"] === "string") flags.remote = values["remote"];
+  if (typeof values["repo-id"] === "string") flags.repoId = values["repo-id"];
+  if (typeof values["owner"] === "string")
+    flags.owner = ownerToHex(values["owner"]);
+  return flags;
+}
+async function resolveTrackerContext(flags, deps, needRepoAddr) {
+  let repoRoot;
+  let toonConfig = {
+    relays: []
+  };
+  try {
+    repoRoot = await resolveRepoRoot(deps.cwd);
+    toonConfig = await readToonConfig(repoRoot);
+  } catch {
+  }
+  let repoAddr = null;
+  if (needRepoAddr) {
+    const repoId = flags.repoId ?? toonConfig.repoId;
+    if (!repoId) throw new UnconfiguredRepoAddressError("repository id");
+    const owner = flags.owner ?? toonConfig.owner;
+    if (!owner) throw new UnconfiguredRepoAddressError("repository owner");
+    repoAddr = { ownerPubkey: owner, repoId };
+  }
+  const resolved = await resolveRelays({
+    relayFlags: flags.relay,
+    remoteName: flags.remote,
+    repoRoot,
+    toonRelays: toonConfig.relays
+  });
+  const wsRelays = resolved.relays.filter((url) => WS_URL_RE2.test(url));
+  if (wsRelays.length === 0) {
+    throw new InvalidRelayUrlError(
+      resolved.relays[0] ?? "",
+      "reads need a ws:// or wss:// relay"
+    );
+  }
+  return {
+    relays: wsRelays,
+    repoAddr,
+    webSocketFactory: deps.webSocketFactory ?? defaultWebSocketFactory
+  };
+}
+function repoATag(addr) {
+  return `${REPOSITORY_ANNOUNCEMENT_KIND}:${addr.ownerPubkey}:${addr.repoId}`;
+}
+function parseTrackerItem(event, status) {
+  const item = {
+    eventId: event.id,
+    kind: event.kind,
+    title: tagValue(event.tags, "subject") ?? (event.content.split("\n")[0] ?? "").slice(0, 120),
+    status,
+    authorPubkey: event.pubkey,
+    createdAt: event.created_at,
+    labels: tagValues(event.tags, "t"),
+    content: event.content
+  };
+  if (event.kind === PATCH_KIND) {
+    item.commitShas = tagValues(event.tags, "commit");
+    const branch = tagValue(event.tags, "branch");
+    if (branch !== void 0) item.branch = branch;
+    const description = tagValue(event.tags, "description");
+    if (description !== void 0) item.description = description;
+  }
+  return item;
+}
+function isoDate(createdAt) {
+  return new Date(createdAt * 1e3).toISOString().slice(0, 10);
+}
+async function fetchItems(ctx, kind) {
+  const aTag = repoATag(
+    ctx.repoAddr
+  );
+  const [itemEvents, aStatusEvents] = await Promise.all([
+    queryAll(
+      ctx.relays,
+      [{ kinds: [kind], "#a": [aTag] }],
+      ctx.webSocketFactory
+    ),
+    queryAll(
+      ctx.relays,
+      [{ kinds: STATUS_KINDS, "#a": [aTag] }],
+      ctx.webSocketFactory
+    )
+  ]);
+  const items = [...itemEvents.values()].filter(
+    (e) => e.kind === kind && e.tags.some((t) => t[0] === "a" && t[1] === aTag)
+  );
+  const statuses = new Map(aStatusEvents);
+  if (items.length > 0) {
+    const byE = await queryAll(
+      ctx.relays,
+      [{ kinds: STATUS_KINDS, "#e": items.map((i) => i.id) }],
+      ctx.webSocketFactory
+    );
+    for (const [id, event] of byE)
+      if (!statuses.has(id)) statuses.set(id, event);
+  }
+  return items.map(
+    (event) => parseTrackerItem(event, deriveStatus(event.id, statuses.values()))
+  ).sort((a, b) => b.createdAt - a.createdAt);
+}
+async function fetchItem(ctx, eventId, expectedKind) {
+  const found = await queryAll(
+    ctx.relays,
+    [{ ids: [eventId] }],
+    ctx.webSocketFactory
+  );
+  const event = found.get(eventId);
+  if (!event) {
+    throw new Error(`event ${eventId} not found on ${ctx.relays.join(", ")}`);
+  }
+  if (event.kind !== expectedKind) {
+    const hint = event.kind === PATCH_KIND ? " (it is a kind:1617 patch \u2014 use `rig pr show`)" : event.kind === ISSUE_KIND ? " (it is a kind:1621 issue \u2014 use `rig issue show`)" : "";
+    throw new Error(
+      `event ${eventId} has kind ${event.kind}, expected ${expectedKind}${hint}`
+    );
+  }
+  const [statusEvents, commentEvents] = await Promise.all([
+    queryAll(
+      ctx.relays,
+      [{ kinds: STATUS_KINDS, "#e": [eventId] }],
+      ctx.webSocketFactory
+    ),
+    queryAll(
+      ctx.relays,
+      [{ kinds: [COMMENT_KIND], "#e": [eventId] }],
+      ctx.webSocketFactory
+    )
+  ]);
+  const comments = [...commentEvents.values()].filter(
+    (e) => e.kind === COMMENT_KIND && e.tags.some((t) => t[0] === "e" && t[1] === eventId)
+  ).sort((a, b) => a.created_at - b.created_at).map((e) => ({
+    eventId: e.id,
+    authorPubkey: e.pubkey,
+    createdAt: e.created_at,
+    content: e.content
+  }));
+  return {
+    item: parseTrackerItem(event, deriveStatus(eventId, statusEvents.values())),
+    comments,
+    repoATag: tagValue(event.tags, "a") ?? null
+  };
+}
+async function runList(args, deps, spec) {
+  const { io: io2 } = deps;
+  let flags;
+  try {
+    const { values, positionals } = parseArgs6({
+      args,
+      options: TRACKER_OPTIONS,
+      allowPositionals: true
+    });
+    if (positionals.length > 0) {
+      throw new Error(`rig ${spec.command} takes no positional arguments`);
+    }
+    flags = pickTrackerFlags(values);
+    if (flags.state !== void 0 && flags.state !== "all" && !spec.states.includes(flags.state)) {
+      throw new Error(
+        `--state must be one of ${[...spec.states, "all"].join(" | ")} (got ${JSON.stringify(flags.state)})`
+      );
+    }
+  } catch (err) {
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(spec.usage);
+    return 2;
+  }
+  if (flags.help) {
+    io2.out(spec.usage);
+    return 0;
+  }
+  try {
+    const ctx = await resolveTrackerContext(flags, deps, true);
+    const all = await fetchItems(ctx, spec.kind);
+    const state = flags.state ?? "all";
+    const items = state === "all" ? all : all.filter((i) => i.status === state);
+    if (flags.json) {
+      io2.emitJson({
+        command: spec.command,
+        repoAddr: ctx.repoAddr,
+        relays: ctx.relays,
+        state,
+        count: items.length,
+        [spec.jsonKey]: items
+      });
+      return 0;
+    }
+    if (items.length === 0) {
+      io2.out(
+        `no ${state === "all" ? "" : `${state} `}${spec.jsonKey} found for ${repoATag(ctx.repoAddr)}`
+      );
+      return 0;
+    }
+    for (const item of items) {
+      const labels = item.labels.length > 0 ? `  [${item.labels.join(", ")}]` : "";
+      io2.out(
+        `${item.status.padEnd(7)}  ${item.eventId.slice(0, 8)}  ${item.title}  (${item.authorPubkey.slice(0, 8)}, ${isoDate(item.createdAt)})${labels}`
+      );
+    }
+    io2.out(
+      `${items.length} ${spec.jsonKey}${state === "all" ? "" : ` (${state})`}`
+    );
+    return 0;
+  } catch (err) {
+    return emitCliError(io2, flags.json, spec.command, err);
+  }
+}
+async function runShow(args, deps, spec) {
+  const { io: io2 } = deps;
+  let flags;
+  let eventId;
+  try {
+    const { values, positionals } = parseArgs6({
+      args,
+      options: TRACKER_OPTIONS,
+      allowPositionals: true
+    });
+    flags = pickTrackerFlags(values);
+    if (flags.help) {
+      io2.out(spec.usage);
+      return 0;
+    }
+    if (positionals.length !== 1) {
+      throw new Error("expected exactly one <event-id>");
+    }
+    eventId = positionals[0];
+    if (!HEX64_RE.test(eventId)) {
+      throw new Error(
+        `<event-id> must be a 64-char lowercase hex id (got ${JSON.stringify(eventId)})`
+      );
+    }
+  } catch (err) {
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(spec.usage);
+    return 2;
+  }
+  try {
+    const ctx = await resolveTrackerContext(flags, deps, false);
+    const shown = await fetchItem(ctx, eventId, spec.kind);
+    if (flags.json) {
+      io2.emitJson({
+        command: spec.command,
+        relays: ctx.relays,
+        repoATag: shown.repoATag,
+        [spec.jsonKey]: shown.item,
+        comments: shown.comments
+      });
+      return 0;
+    }
+    const { item } = shown;
+    io2.out(`${spec.jsonKey} ${item.eventId}`);
+    io2.out(`Title:   ${item.title}`);
+    io2.out(`Status:  ${item.status}`);
+    io2.out(`Author:  ${item.authorPubkey}`);
+    io2.out(`Date:    ${isoDate(item.createdAt)}`);
+    if (item.labels.length > 0) io2.out(`Labels:  ${item.labels.join(", ")}`);
+    if (item.branch !== void 0) io2.out(`Branch:  ${item.branch}`);
+    if (item.commitShas && item.commitShas.length > 0) {
+      io2.out(`Commits: ${item.commitShas.join(", ")}`);
+    }
+    if (shown.repoATag !== null) io2.out(`Repo:    ${shown.repoATag}`);
+    if (item.description !== void 0) {
+      io2.out("");
+      io2.out("Body:");
+      for (const line of item.description.split("\n")) io2.out(line);
+    }
+    io2.out("");
+    io2.out(`${spec.bodyLabel}:`);
+    for (const line of item.content.split("\n")) io2.out(line);
+    io2.out("");
+    io2.out(`Comments (${shown.comments.length}):`);
+    for (const comment of shown.comments) {
+      io2.out(
+        `--- ${comment.eventId.slice(0, 8)} by ${comment.authorPubkey.slice(0, 8)} on ${isoDate(comment.createdAt)}`
+      );
+      for (const line of comment.content.split("\n")) io2.out(line);
+    }
+    return 0;
+  } catch (err) {
+    return emitCliError(io2, flags.json, spec.command, err);
+  }
+}
+var ISSUE_STATES = ["open", "closed", "applied", "draft"];
+var PR_STATES = ["open", "applied", "closed", "draft"];
+function runIssueList(args, deps) {
+  return runList(args, deps, {
+    command: "issue list",
+    kind: ISSUE_KIND,
+    usage: ISSUE_LIST_USAGE,
+    states: ISSUE_STATES,
+    jsonKey: "issues"
+  });
+}
+function runIssueShow(args, deps) {
+  return runShow(args, deps, {
+    command: "issue show",
+    kind: ISSUE_KIND,
+    usage: ISSUE_SHOW_USAGE,
+    jsonKey: "issue",
+    bodyLabel: "Body"
+  });
+}
+function runPrList(args, deps) {
+  return runList(args, deps, {
+    command: "pr list",
+    kind: PATCH_KIND,
+    usage: PR_LIST_USAGE,
+    states: PR_STATES,
+    jsonKey: "prs"
+  });
+}
+function runPrShow(args, deps) {
+  return runShow(args, deps, {
+    command: "pr show",
+    kind: PATCH_KIND,
+    usage: PR_SHOW_USAGE,
+    jsonKey: "pr",
+    bodyLabel: "Patch"
+  });
+}
+
+// src/cli/events.ts
+var defaultReadStdin = async () => {
+  if (process.stdin.isTTY) return "";
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8");
+};
+var COMMON_FLAGS_USAGE = `  --repo-id <id>       repository id / NIP-34 d-tag (default: git config
+                       toon.repoid \u2014 run \`rig init\` to set it)
+  --owner <pubkey>     repository owner pubkey, 64-char hex (default: git config
+                       toon.owner, then the active identity)
+  --remote <name>      publish via this configured git remote (default: the
+                       "origin" remote \u2014 \`rig remote add origin <relay-url>\`)
+  --relay <url>        ad-hoc relay override (exactly one) \u2014 bypasses the
+                       configured remotes. The deprecated v0.1 \`git config
+                       toon.relay\` still works as a fallback, with a nudge
+  --yes                skip the fee confirmation (required when not a TTY)
+  --json               machine-readable receipt; without --yes it is a pure
+                       estimate (nothing published, exit 0)
+  -h, --help           show this help`;
+var ISSUE_USAGE = `Usage: rig issue create --title <title> [options]
+
+File an issue (kind:1621) against a TOON repo \u2014 a paid publish; writes are
+permanent and non-refundable. The repo address (30617:<owner>:<repoId>) comes
+from the toon.* git config keys \`rig init\` writes.
+
+Body source (exactly one): --body, --body-file, or piped stdin.
+
+Options:
+  --title <title>      issue title (subject tag) [required]
+  --body <text>        issue body (Markdown)
+  --body-file <path>   read the issue body from a file
+  --label <label>      label (t tag); repeatable
+${COMMON_FLAGS_USAGE}
+
+Related (FREE reads \u2014 no payment):
+  rig issue list [--state open|closed|all]   list the repo's issues
+  rig issue show <event-id>                  one issue + its comments`;
+var COMMENT_USAGE = `Usage: rig comment <root-event-id> --body <text> [options]
+
+Comment (kind:1622) on an issue or patch \u2014 a paid publish; writes are
+permanent and non-refundable. <root-event-id> is the 64-char hex id of the
+kind:1621 issue / kind:1617 patch being commented on.
+
+Options:
+  --body <text>            comment body (Markdown) [required]
+  --parent-author <pubkey> pubkey of the TARGET event's author (p threading
+                           tag; default: the repo owner)
+  --marker <root|reply>    e-tag marker (default: root \u2014 commenting directly
+                           on the issue/patch)
+${COMMON_FLAGS_USAGE}`;
+var PR_CREATE_USAGE = `Usage: rig pr create --title <title> (--range <range> | --patch-file <path>) [options]
+
+Publish a patch (kind:1617) whose content is REAL \`git format-patch\` output \u2014
+a paid publish; writes are permanent and non-refundable. --range runs
+\`git format-patch --stdout <range>\` in the local repository and derives the
+commit/parent-commit tags; --patch-file publishes a pre-generated patch
+verbatim. A multi-commit range publishes ONE kind:1617 event carrying the
+full series text \u2014 cover-letter threading (one event per commit) is out of
+scope in v1.
+
+The PR body (--body/--body-file) is carried in a dedicated \`description\`
+tag, not in the event content \u2014 the content stays pure format-patch output so
+\`rig pr show \u2026 | git am\` keeps working.
+
+Options:
+  --title <title>      patch/PR title (subject tag) [required]
+  --range <range>      revision range for format-patch: <rev>, <rev>..<rev>,
+                       or <rev>...<rev> (mutually exclusive with --patch-file)
+  --patch-file <path>  literal patch text to publish
+  --body <text>        PR description (Markdown; description tag)
+  --body-file <path>   read the PR description from a file
+  --branch <name>      branch name (t tag)
+${COMMON_FLAGS_USAGE}`;
+var PR_STATUS_USAGE = `Usage: rig pr status <target-event-id> <open|applied|closed|draft> [options]
+
+Set the status of an issue or patch \u2014 a paid publish; writes are permanent
+and non-refundable. Publishes kind:1630 (open), 1631 (applied), 1632
+(closed), or 1633 (draft) against the 64-char hex id of the target event,
 with the repo a-tag attached so readers can scope a status stream to the
 repository. (This command was \`rig status\` before v2 \u2014 bare \`rig status\`
 now passes through to \`git status\`.)
@@ -1605,10 +2575,14 @@ Options:
 ${COMMON_FLAGS_USAGE}`;
 var PR_USAGE = `${PR_CREATE_USAGE}
 
-${PR_STATUS_USAGE}`;
-var HEX64_RE = /^[0-9a-f]{64}$/;
+${PR_STATUS_USAGE}
+
+${PR_LIST_USAGE}
+
+${PR_SHOW_USAGE}`;
+var HEX64_RE2 = /^[0-9a-f]{64}$/;
 function assertHex64(value, what) {
-  if (!HEX64_RE.test(value)) {
+  if (!HEX64_RE2.test(value)) {
     throw new Error(
       `${what} must be a 64-char lowercase hex id (got ${JSON.stringify(value)})`
     );
@@ -1643,7 +2617,7 @@ function pickCommon(values) {
 }
 async function runEvent(opts) {
   const { command, flags, deps, actionLabel } = opts;
-  const { io: io2, env } = deps;
+  const { io: io2 } = deps;
   let standaloneCtx;
   try {
     let repoRoot;
@@ -1667,21 +2641,35 @@ async function runEvent(opts) {
       io2.err(singleRelayRefusal(resolved, "Nothing was published 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);
-    const fee = (await standaloneCtx.publisher.getFeeRates()).eventFee.toString();
+    const session = await loadPaidSession(deps, relaysUsed[0]);
+    const path = session.path;
+    let identity;
+    let fee;
+    if (session.path === "standalone") {
+      standaloneCtx = session.ctx;
+      identity = identityReport(standaloneCtx);
+      fee = (await standaloneCtx.publisher.getFeeRates()).eventFee.toString();
+    } else {
+      identity = session.identity;
+      fee = session.feePerEvent;
+      const resolvedRelay = relaysUsed[0];
+      if (resolvedRelay !== void 0 && session.daemonRelayUrl !== void 0 && session.daemonRelayUrl !== resolvedRelay) {
+        io2.err(
+          `rig: the daemon publishes via its configured relay (${session.daemonRelayUrl}), not the resolved relay (${resolvedRelay}) \u2014 stop the daemon to force the standalone path if that matters`
+        );
+      }
+    }
     const owner = flags.owner ?? toonConfig.owner ?? identity.pubkey;
     const addr = { ownerPubkey: owner, repoId };
     const event = await opts.buildEvent(addr);
     const action = `kind:${event.kind} ${actionLabel}`;
     if (!flags.json) {
-      for (const line of renderEventPlan({ action, addr, identity, fee })) {
+      for (const line of renderEventPlan({
+        action,
+        addr,
+        identity,
+        ...fee !== void 0 ? { fee } : {}
+      })) {
         io2.out(line);
       }
     }
@@ -1690,10 +2678,11 @@ async function runEvent(opts) {
         io2.emitJson({
           command,
           repoAddr: addr,
+          path,
           identity,
           kind: event.kind,
           executed: false,
-          feeEstimate: fee,
+          feeEstimate: fee ?? null,
           hint: "estimate only \u2014 re-run with --yes to publish (permanent, non-refundable)"
         });
         return 0;
@@ -1712,16 +2701,25 @@ async function runEvent(opts) {
         return 1;
       }
     }
-    const receipt = await standaloneCtx.publisher.publishEvent(event, relaysUsed);
-    const result = serializeEventReceipt(event.kind, receipt);
+    let result;
+    if (session.path === "standalone") {
+      const receipt = await session.ctx.publisher.publishEvent(
+        event,
+        relaysUsed
+      );
+      result = serializeEventReceipt(event.kind, receipt);
+    } else {
+      result = await opts.sendDaemon(session.client, addr);
+    }
     if (flags.json) {
       io2.emitJson({
         command,
         repoAddr: addr,
+        path,
         identity,
         kind: result.kind,
         executed: true,
-        feeEstimate: fee,
+        feeEstimate: fee ?? null,
         result
       });
     } else {
@@ -1744,11 +2742,17 @@ async function runIssue(args, deps) {
   const [sub, ...rest] = args;
   if (sub === "--help" || sub === "-h" || sub === "help") {
     io2.out(ISSUE_USAGE);
+    io2.out("");
+    io2.out(ISSUE_LIST_USAGE);
+    io2.out("");
+    io2.out(ISSUE_SHOW_USAGE);
     return 0;
   }
+  if (sub === "list") return runIssueList(rest, deps);
+  if (sub === "show") return runIssueShow(rest, deps);
   if (sub !== "create") {
     io2.err(
-      sub === void 0 ? "missing subcommand: rig issue create" : `unknown rig issue subcommand: ${sub}`
+      sub === void 0 ? "missing subcommand: rig issue <create|list|show>" : `unknown rig issue subcommand: ${sub}`
     );
     io2.err(ISSUE_USAGE);
     return 2;
@@ -1759,7 +2763,7 @@ async function runIssue(args, deps) {
   let bodyFile;
   let labels;
   try {
-    const { values } = parseArgs5({
+    const { values } = parseArgs7({
       args: rest,
       options: {
         ...COMMON_OPTIONS,
@@ -1818,7 +2822,13 @@ async function runIssue(args, deps) {
     flags,
     deps,
     actionLabel: `issue ${JSON.stringify(title)}`,
-    buildEvent: async (addr) => buildIssue(addr.ownerPubkey, addr.repoId, title, body, labels)
+    buildEvent: async (addr) => buildIssue(addr.ownerPubkey, addr.repoId, title, body, labels),
+    sendDaemon: (client, addr) => client.gitIssue({
+      repoAddr: addr,
+      title,
+      body,
+      ...labels.length > 0 ? { labels } : {}
+    })
   });
 }
 async function runComment(args, deps) {
@@ -1829,7 +2839,7 @@ async function runComment(args, deps) {
   let parentAuthor;
   let marker;
   try {
-    const { values, positionals } = parseArgs5({
+    const { values, positionals } = parseArgs7({
       args,
       options: {
         ...COMMON_OPTIONS,
@@ -1879,7 +2889,14 @@ async function runComment(args, deps) {
       parentAuthor ?? addr.ownerPubkey,
       body,
       marker
-    )
+    ),
+    sendDaemon: (client, addr) => client.gitComment({
+      repoAddr: addr,
+      rootEventId,
+      body,
+      ...parentAuthor !== void 0 ? { parentAuthorPubkey: parentAuthor } : {},
+      marker
+    })
   });
 }
 var PATCH_FROM_RE = /^From ([0-9a-f]{40}) /gm;
@@ -1894,6 +2911,11 @@ async function runPr(args, deps) {
       return runPrCreate(rest, deps);
     case "status":
       return runPrStatus(rest, deps);
+    // FREE read subcommands (#278): relay queries only, no payment path.
+    case "list":
+      return runPrList(rest, deps);
+    case "show":
+      return runPrShow(rest, deps);
     case "--help":
     case "-h":
     case "help":
@@ -1901,7 +2923,7 @@ async function runPr(args, deps) {
       return 0;
     default:
       io2.err(
-        sub === void 0 ? "missing subcommand: rig pr <create|status>" : `unknown rig pr subcommand: ${sub}`
+        sub === void 0 ? "missing subcommand: rig pr <create|status|list|show>" : `unknown rig pr subcommand: ${sub}`
       );
       io2.err(PR_USAGE);
       return 2;
@@ -1914,14 +2936,18 @@ async function runPrCreate(rest, deps) {
   let range;
   let patchFile;
   let branch;
+  let bodyFlag;
+  let bodyFile;
   try {
-    const { values } = parseArgs5({
+    const { values } = parseArgs7({
       args: rest,
       options: {
         ...COMMON_OPTIONS,
         title: { type: "string" },
         range: { type: "string" },
         "patch-file": { type: "string" },
+        body: { type: "string" },
+        "body-file": { type: "string" },
         branch: { type: "string" }
       },
       allowPositionals: false
@@ -1937,15 +2963,39 @@ async function runPrCreate(rest, deps) {
     if (values.range === void 0 === (values["patch-file"] === void 0)) {
       throw new Error("exactly one of --range or --patch-file is required");
     }
+    if (values.body !== void 0 && values["body-file"] !== void 0) {
+      throw new Error("--body and --body-file are mutually exclusive");
+    }
     title = values.title;
     range = values.range;
     patchFile = values["patch-file"];
     branch = values.branch;
+    bodyFlag = values.body;
+    bodyFile = values["body-file"];
   } catch (err) {
     io2.err(err instanceof Error ? err.message : String(err));
     io2.err(PR_CREATE_USAGE);
     return 2;
   }
+  let body;
+  if (bodyFlag !== void 0) {
+    body = bodyFlag;
+  } else if (bodyFile !== void 0) {
+    try {
+      body = await readFile(bodyFile, "utf-8");
+    } catch (err) {
+      io2.err(
+        `cannot read --body-file ${bodyFile}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return 2;
+    }
+  }
+  if (body !== void 0 && body.trim() === "") {
+    io2.err("the PR body is empty \u2014 drop --body/--body-file or pass text");
+    return 2;
+  }
+  let builtPatchText;
+  let builtCommits = [];
   return runEvent({
     command: "pr",
     flags,
@@ -1975,22 +3025,38 @@ async function runPrCreate(rest, deps) {
         }
         commits = [];
       }
+      builtPatchText = patchText;
+      builtCommits = commits;
       return buildPatch(
         addr.ownerPubkey,
         addr.repoId,
         title,
         commits,
         branch,
-        patchText
+        patchText,
+        body
       );
+    },
+    sendDaemon: (client, addr) => {
+      if (builtPatchText === void 0) {
+        throw new Error("internal: patch text not built before delegation");
+      }
+      return client.gitPatch({
+        repoAddr: addr,
+        title,
+        patchText: builtPatchText,
+        ...body !== void 0 ? { description: body } : {},
+        ...builtCommits.length > 0 ? { commits: builtCommits } : {},
+        ...branch !== void 0 ? { branch } : {}
+      });
     }
   });
 }
 var STATUS_KIND_BY_VALUE = {
-  open: STATUS_OPEN_KIND,
-  applied: STATUS_APPLIED_KIND,
-  closed: STATUS_CLOSED_KIND,
-  draft: STATUS_DRAFT_KIND
+  open: STATUS_OPEN_KIND2,
+  applied: STATUS_APPLIED_KIND2,
+  closed: STATUS_CLOSED_KIND2,
+  draft: STATUS_DRAFT_KIND2
 };
 function isStatusValue(value) {
   return Object.hasOwn(STATUS_KIND_BY_VALUE, value);
@@ -2001,7 +3067,7 @@ async function runPrStatus(args, deps) {
   let targetEventId;
   let status;
   try {
-    const { values, positionals } = parseArgs5({
+    const { values, positionals } = parseArgs7({
       args,
       options: COMMON_OPTIONS,
       allowPositionals: true
@@ -2039,18 +3105,238 @@ async function runPrStatus(args, deps) {
       const event = buildStatus(targetEventId, STATUS_KIND_BY_VALUE[status]);
       event.tags.push([
         "a",
-        `${REPOSITORY_ANNOUNCEMENT_KIND}:${addr.ownerPubkey}:${addr.repoId}`
+        `${REPOSITORY_ANNOUNCEMENT_KIND2}:${addr.ownerPubkey}:${addr.repoId}`
       ]);
       return event;
-    }
+    },
+    sendDaemon: (client, addr) => client.gitStatus({ repoAddr: addr, targetEventId, status })
   });
 }
 
+// src/cli/fetch.ts
+import { parseArgs as parseArgs8 } from "util";
+var FETCH_USAGE = `Usage: rig fetch [remote] [options]
+
+Fetch from a TOON remote \u2014 FREE (relay reads + Arweave gateway downloads; no
+payments, no identity needed). Reads the kind:30618 repository state from the
+remote's relay, downloads only the git objects this repository is missing
+(SHA-1 verified), and updates the remote-tracking refs
+(refs/remotes/<remote>/*; tags land at refs/tags/*), reporting what moved.
+
+No merge happens: integrate with the git passthrough, e.g.
+\`rig merge origin/main\`. \`rig fetch\` is the TOON transport and shadows
+\`git fetch\` \u2014 plain-git fetches remain available via \`git fetch\` directly.
+
+The repo address (toon.repoid/toon.owner) comes from the config \`rig init\`
+or \`rig clone\` writes; --repo-id/--owner override.
+
+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
+  --concurrency <n>    parallel gateway downloads (default 8)
+  --json               machine-readable result envelope
+  -h, --help           show this help`;
+var WS_URL_RE3 = /^wss?:\/\//i;
+function localRefFor(refname, remote) {
+  if (refname.startsWith("refs/heads/")) {
+    return `refs/remotes/${remote}/${refname.slice("refs/heads/".length)}`;
+  }
+  if (refname.startsWith("refs/tags/")) return refname;
+  return null;
+}
+async function resolveLocalRef(repoRoot, refname) {
+  try {
+    const out = await runGit(repoRoot, [
+      "rev-parse",
+      "--verify",
+      "--quiet",
+      refname
+    ]);
+    const sha = out.trim();
+    return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+async function runFetch(args, deps) {
+  const { io: io2 } = deps;
+  let json = false;
+  let remote = "origin";
+  let relayFlag;
+  let repoIdFlag;
+  let ownerFlag;
+  let concurrency;
+  try {
+    const { values, positionals } = parseArgs8({
+      args,
+      options: {
+        json: { type: "boolean", default: false },
+        relay: { type: "string" },
+        "repo-id": { type: "string" },
+        owner: { type: "string" },
+        concurrency: { type: "string" },
+        help: { type: "boolean", short: "h", default: false }
+      },
+      allowPositionals: true
+    });
+    if (values.help) {
+      io2.out(FETCH_USAGE);
+      return 0;
+    }
+    json = values.json === true;
+    if (positionals.length > 1) {
+      throw new Error(
+        `expected at most one [remote] argument, got ${positionals.length}`
+      );
+    }
+    if (positionals[0] !== void 0) remote = positionals[0];
+    relayFlag = values.relay;
+    repoIdFlag = values["repo-id"];
+    ownerFlag = values.owner !== void 0 ? ownerToHex(values.owner) : void 0;
+    if (values.concurrency !== void 0) {
+      concurrency = Number.parseInt(values.concurrency, 10);
+      if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+        throw new Error("--concurrency must be a positive integer");
+      }
+    }
+  } catch (err) {
+    io2.err(err instanceof Error ? err.message : String(err));
+    io2.err(FETCH_USAGE);
+    return 2;
+  }
+  try {
+    const repoRoot = await resolveRepoRoot(deps.cwd);
+    const toonConfig = await readToonConfig(repoRoot);
+    const repoId = repoIdFlag ?? toonConfig.repoId;
+    if (!repoId) throw new UnconfiguredRepoAddressError("repository id");
+    const owner = ownerFlag ?? toonConfig.owner;
+    if (!owner) throw new UnconfiguredRepoAddressError("repository owner");
+    let relayUrl;
+    if (relayFlag !== void 0) {
+      relayUrl = relayFlag;
+    } else {
+      const urls = await getGitRemoteUrls(repoRoot, remote);
+      if (urls.length === 0) throw new UnknownRemoteError(remote);
+      if (urls.length > 1) throw new MultiUrlRemoteError(remote, urls);
+      relayUrl = urls[0];
+    }
+    if (!WS_URL_RE3.test(relayUrl)) {
+      throw new InvalidRelayUrlError(
+        relayUrl,
+        `remote ${JSON.stringify(remote)}`
+      );
+    }
+    const remoteState = await fetchRemoteState({
+      relayUrls: [relayUrl],
+      ownerPubkey: owner,
+      repoId,
+      ...deps.webSocketFactory ? { webSocketFactory: deps.webSocketFactory } : {},
+      ...deps.resolveSha ? { resolveSha: deps.resolveSha } : {}
+    });
+    const planned = [];
+    for (const [refname, sha] of remoteState.refs) {
+      if (!isSafeRefname(refname)) {
+        io2.err(
+          `warning: skipping unsafe ref name from relay: ${JSON.stringify(refname)}`
+        );
+        continue;
+      }
+      const localRef = localRefFor(refname, remote);
+      if (localRef === null) {
+        io2.err(
+          `warning: skipping ref outside refs/heads and refs/tags: ${refname}`
+        );
+        continue;
+      }
+      planned.push({ refname, localRef, newSha: sha });
+    }
+    const reader = new GitRepoReader(repoRoot);
+    const tips = [...new Set(planned.map((p) => p.newSha))];
+    const candidates = [.../* @__PURE__ */ new Set([...remoteState.shaToTxId.keys(), ...tips])];
+    const { missing: absent } = await reader.statObjects(candidates);
+    const absentSet = new Set(absent);
+    const presentLocally = new Set(
+      candidates.filter((sha) => !absentSet.has(sha))
+    );
+    const collected = await collectRepoObjects({
+      tips,
+      shaToTxId: remoteState.shaToTxId,
+      resolveMissing: (shas) => remoteState.resolveMissing(shas),
+      presentLocally,
+      ...deps.fetchFn ? { fetchFn: deps.fetchFn } : {},
+      ...concurrency !== void 0 ? { concurrency } : {}
+    });
+    if (collected.missing.length > 0) {
+      throw new MissingRemoteObjectsError(
+        collected.missing,
+        `cannot fetch from ${relayUrl}`
+      );
+    }
+    const written = await writeGitObjects(repoRoot, collected.objects.values());
+    const updates = [];
+    for (const { refname, localRef, newSha } of planned) {
+      const oldSha = await resolveLocalRef(repoRoot, localRef);
+      if (oldSha === newSha) {
+        updates.push({ refname, localRef, oldSha, newSha, kind: "up-to-date" });
+        continue;
+      }
+      let kind;
+      if (oldSha === null) {
+        kind = "new";
+      } else {
+        kind = await reader.isAncestor(oldSha, newSha) ? "fast-forward" : "forced";
+      }
+      await updateRef(repoRoot, localRef, newSha);
+      updates.push({ refname, localRef, oldSha, newSha, kind });
+    }
+    const moved = updates.filter((u) => u.kind !== "up-to-date");
+    if (json) {
+      io2.emitJson({
+        command: "fetch",
+        repoAddr: { ownerPubkey: owner, repoId },
+        remote,
+        relay: relayUrl,
+        objectsDownloaded: written,
+        updates,
+        executed: true
+      });
+      return 0;
+    }
+    if (moved.length === 0) {
+      io2.out("Already up to date.");
+      return 0;
+    }
+    io2.out(`From ${relayUrl}`);
+    for (const u of moved) {
+      const short = (refname) => refname.replace(/^refs\/heads\//, "").replace(/^refs\/tags\//, "").replace(/^refs\/remotes\//, "");
+      const src = short(u.refname);
+      const dst = short(u.localRef);
+      if (u.kind === "new") {
+        const label = u.refname.startsWith("refs/tags/") ? "[new tag]" : "[new branch]";
+        io2.out(` * ${label.padEnd(17)} ${src.padEnd(14)} -> ${dst}`);
+      } else if (u.kind === "forced") {
+        io2.out(
+          ` + ${u.oldSha.slice(0, 7)}...${u.newSha.slice(0, 7)} ${src.padEnd(14)} -> ${dst}  (forced update)`
+        );
+      } else {
+        io2.out(
+          `   ${u.oldSha.slice(0, 7)}..${u.newSha.slice(0, 7)}  ${src.padEnd(14)} -> ${dst}`
+        );
+      }
+    }
+    io2.out(`Downloaded ${written} object(s) (SHA-1 verified).`);
+    return 0;
+  } catch (err) {
+    return emitCliError(io2, json, "fetch", err);
+  }
+}
+
 // src/cli/fund.ts
 import { readFileSync } from "fs";
 import { homedir } from "os";
-import { join } from "path";
-import { parseArgs as parseArgs6 } from "util";
+import { join as join2 } from "path";
+import { parseArgs as parseArgs9 } from "util";
 var DEVNET_FAUCET_URL = "https://faucet.devnet.toonprotocol.dev";
 var CHAINS = ["evm", "solana", "mina"];
 var FUND_USAGE = `Usage: rig fund [options]
@@ -2069,9 +3355,36 @@ Options:
   --address <address>  fund this address instead of the identity's own
   --json               machine-readable envelope
   -h, --help           show this help`;
+var SHARED_DEVNET_SUFFIX = ".devnet.toonprotocol.dev";
+function sharedDevnetOrigin(env, file) {
+  const candidates = [
+    env["TOON_CLIENT_RELAY_URL"] ?? file.relayUrl,
+    env["TOON_CLIENT_PROXY_URL"] ?? file.proxyUrl,
+    env["TOON_CLIENT_BTP_URL"] ?? file.btpUrl
+  ];
+  for (const url of candidates) {
+    if (!url) continue;
+    try {
+      const { hostname } = new URL(url);
+      if (hostname.endsWith(SHARED_DEVNET_SUFFIX) || hostname === SHARED_DEVNET_SUFFIX.slice(1)) {
+        return url;
+      }
+    } catch {
+    }
+  }
+  return void 0;
+}
+function noFaucetGuidance(network, devnetOrigin) {
+  const head = `no faucet is configured for network ${JSON.stringify(network ?? "custom")}`;
+  const external = "To fund the wallet externally instead, send the settlement token plus native gas to the address below for the chain your channels settle on.";
+  if (devnetOrigin !== void 0) {
+    return `${head} \u2014 but your configured origin (${devnetOrigin}) looks like the shared devnet. Set TOON_CLIENT_NETWORK=devnet (or "network": "devnet" in the client config) and re-run \`rig fund\` \u2014 no faucet URL is needed there. ${external}`;
+  }
+  return `${head}. If you meant the shared devnet, set TOON_CLIENT_NETWORK=devnet and re-run \`rig fund\` \u2014 no faucet URL is needed there. If this is a self-hosted network with its own faucet, set TOON_CLIENT_FAUCET_URL (or the faucetUrl config field). ${external}`;
+}
 function readFundConfig(env) {
-  const dir = env["TOON_CLIENT_HOME"] ?? join(homedir(), ".toon-client");
-  const configPath = join(dir, "config.json");
+  const dir = env["TOON_CLIENT_HOME"] ?? join2(homedir(), ".toon-client");
+  const configPath = join2(dir, "config.json");
   try {
     return {
       file: JSON.parse(readFileSync(configPath, "utf8")),
@@ -2092,7 +3405,7 @@ async function runFund(args, deps) {
   let addressFlag;
   let json = false;
   try {
-    const { values } = parseArgs6({
+    const { values } = parseArgs9({
       args,
       options: {
         chain: { type: "string" },
@@ -2149,7 +3462,7 @@ async function runFund(args, deps) {
       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.`;
+      const guidance = noFaucetGuidance(network, sharedDevnetOrigin(env, file));
       if (json) {
         io2.emitJson({
           command: "fund",
@@ -2221,7 +3534,7 @@ function signalExitCode(signal) {
 var runGitPassthrough = (argv2, options = {}) => {
   const err = options.err ?? ((line) => process.stderr.write(`${line}
 `));
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const child = spawn("git", argv2, {
       stdio: "inherit",
       ...options.cwd !== void 0 ? { cwd: options.cwd } : {},
@@ -2244,22 +3557,22 @@ var runGitPassthrough = (argv2, options = {}) => {
         err(
           `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);
+        resolve2(GIT_NOT_FOUND_EXIT);
         return;
       }
       err(`rig: failed to run git: ${spawnErr.message}`);
-      resolve(1);
+      resolve2(1);
     });
     child.on("close", (code, signal) => {
       restoreSignals();
-      resolve(signal !== null ? signalExitCode(signal) : code ?? 1);
+      resolve2(signal !== null ? signalExitCode(signal) : code ?? 1);
     });
   });
 };
 
 // src/cli/init.ts
-import { basename } from "path";
-import { parseArgs as parseArgs7 } from "util";
+import { basename as basename2 } from "path";
+import { parseArgs as parseArgs10 } from "util";
 var INIT_USAGE = `Usage: rig init [options]
 
 Set up the current git repository for rig (one-shot, idempotent, free):
@@ -2279,7 +3592,7 @@ Options:
   --json             machine-readable report
   -h, --help         show this help`;
 function parseInitArgs(args) {
-  const { values, positionals } = parseArgs7({
+  const { values, positionals } = parseArgs10({
     args,
     options: {
       "repo-id": { type: "string" },
@@ -2329,7 +3642,7 @@ async function runInit(args, deps) {
       warn: (line) => io2.err(line)
     });
     const existing = await readToonConfig(repoRoot);
-    const repoId = flags.repoId ?? existing.repoId ?? basename(repoRoot);
+    const repoId = flags.repoId ?? existing.repoId ?? basename2(repoRoot);
     const changed = {
       repoId: existing.repoId !== repoId,
       owner: existing.owner !== identity.pubkey
@@ -2415,12 +3728,22 @@ Commands rig owns:
   remote add <name> <url>    add a relay as a REAL git remote ("origin" is
   remote remove <name>       the default publish target); remove/list manage
   remote list                them \u2014 \`git remote -v\` shows the same data
+  clone <relay-url> <owner>/<repo-id> [dir]
+                             clone a TOON repo (free): relay state + Arweave
+                             objects (SHA-1 verified) \u2192 a real git repository,
+                             push/pull-capable out of the box
+  fetch [remote]             fetch remote refs + missing objects (free) and
+                             update refs/remotes/<remote>/*; no merge. Shadows
+                             git fetch (plain \`git fetch\` stays available)
   push [remote] [refspecs...]  plan, price, confirm, and execute a paid push
                              to TOON (defaults to the "origin" remote). rig
                              push is the TOON transport and shadows git push;
                              plain-git pushes remain available by running
                              \`git push\` directly
   issue create               file an issue (kind:1621) against a repo
+  issue list | show <id>     read the repo's issues + comments (free)
+  pr list | show <id>        read the repo's patches; show prints the full
+                             patch text (free)
   comment <root-event-id>    comment (kind:1622) on an issue or patch
   pr create                  publish a patch (kind:1617) with real
                              \`git format-patch\` content
@@ -2443,8 +3766,10 @@ Any other command is passed through to git verbatim: \`rig status\` runs
 \`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\`,
-\`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
+\`rig remote\`, \`rig clone\`, \`rig fetch\`, \`rig issue list/show\`,
+\`rig pr list/show\`, \`rig fund\`, \`rig balance\`, and \`rig channel list\`
+are free; push/issue create/comment/pr create/pr status 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).
@@ -2474,6 +3799,11 @@ async function dispatch(argv2, deps) {
       return runInit(rest, deps);
     case "remote":
       return runRemote(rest, deps);
+    // The #278 read path — FREE (relay + Arweave gateway reads, no payment).
+    case "clone":
+      return runClone(rest, deps);
+    case "fetch":
+      return runFetch(rest, deps);
     case "push":
       return runPush(rest, deps);
     case "issue":
@@ -2553,6 +3883,8 @@ function makeCliIo(options) {
 var RIG_OWNED_VERBS = /* @__PURE__ */ new Set([
   "init",
   "remote",
+  "clone",
+  "fetch",
   "push",
   "issue",
   "comment",
@@ -2570,6 +3902,29 @@ function isJsonInvocation(argv2) {
   }
   return false;
 }
+var ANNOUNCE_FAILED_RE = /\[Bootstrap\] Announce failed/;
+var ANNOUNCE_402_RE = /402|payment required/i;
+var ANNOUNCE_402_INFO = "rig: skipped the optional identity self-announce \u2014 the payment peer charges for announces and this identity has not paid for one (expected on a fresh or unfunded identity); harmless, the command continues.\n";
+function calmBootstrapNoise() {
+  const original = process.stderr.write;
+  let reframed = false;
+  const patched = ((chunk, encodingOrCb, cb) => {
+    let text = chunk;
+    if (typeof chunk === "string" && ANNOUNCE_FAILED_RE.test(chunk)) {
+      if (ANNOUNCE_402_RE.test(chunk)) {
+        text = reframed ? "" : ANNOUNCE_402_INFO;
+        reframed = true;
+      }
+    }
+    return typeof encodingOrCb === "function" ? original.call(process.stderr, text, encodingOrCb) : original.call(process.stderr, text, encodingOrCb, cb);
+  });
+  process.stderr.write = patched;
+  return {
+    restore: () => {
+      if (process.stderr.write === patched) process.stderr.write = original;
+    }
+  };
+}
 function redirectStdoutToStderr(realWrite) {
   const original = process.stdout.write;
   const real = realWrite ?? original.bind(process.stdout);
@@ -2591,6 +3946,7 @@ function redirectStdoutToStderr(realWrite) {
 
 // src/cli/rig.ts
 function makeIo(jsonMode) {
+  calmBootstrapNoise();
   const guard = jsonMode ? redirectStdoutToStderr() : void 0;
   return makeCliIo({
     jsonMode,
@@ -2615,6 +3971,16 @@ function makeIo(jsonMode) {
     }
   });
 }
+function exitWhenFlushed(code) {
+  process.exitCode = code;
+  let pending = 2;
+  const done = () => {
+    pending -= 1;
+    if (pending === 0) process.exit(code);
+  };
+  process.stdout.write("", done);
+  process.stderr.write("", done);
+}
 var argv = process.argv.slice(2);
 var io = makeIo(isJsonInvocation(argv));
 dispatch(argv, {
@@ -2624,7 +3990,7 @@ dispatch(argv, {
 }).then(
   (code) => {
     io.ensureSingleJsonDoc(code);
-    process.exitCode = code;
+    exitWhenFlushed(code);
   },
   (err) => {
     process.stderr.write(
@@ -2632,7 +3998,7 @@ dispatch(argv, {
 `
     );
     io.ensureSingleJsonDoc(1);
-    process.exitCode = 1;
+    exitWhenFlushed(1);
   }
 );
 //# sourceMappingURL=rig.js.map