moshcode 0.70.0 → 0.71.0

package/README.md

@@ -62,6 +62,12 @@ or miss one that does. A test fails the build when it drifts.
 | `moshcode crypto` <br>`coins` | tools | crypto market data from advis0r.com |
 | `moshcode news` | tools | headlines from your feeds, or a search |
 | `moshcode rss` | tools | read the same headlines in a full-screen reader |
+| `moshcode timer` | business | track time — on, off, and what it added up to |
+| `moshcode client` <br>`business` `merchant` `customer` | business | who the work is for — clients, businesses, merchants |
+| `moshcode team` <br>`teams` | business | who may do what on this machine |
+| `moshcode rate` <br>`rates` | business | what an hour of agent time costs |
+| `moshcode billing` <br>`invoice` | business | turn tracked time into an invoice |
+| `moshcode payments` | business | the rail invoices go out on |
 | `moshcode plugin` <br>`plugins` | extend | install moshcode's slash commands into Claude Code |
 | `moshcode commands` | script | list built-in moshscript commands |
 | `moshcode completion` | extend | print a shell completion script |
@@ -937,6 +943,88 @@ event, and publishes it to the displayed relays. Both flows leave the final
 confirmation in the browser. If the pit is remote or headless, `/post` prints
 the composer URL instead.
 
+## Getting paid (`/timer`, `/client`, `/rate`, `/billing`, `/payments`)
+
+Every agentic CLI helps you do the work. This one also bills for it. Six words,
+each useful on its own — the timer needs no client, the rate needs no gateway
+(PRD [0012](prd/0012-billing-baked-into-the-agent-cli.md)).
+
+```sh
+moshcode timer on acme --task "batch payments" --agents auto   # auto counts the herd
+moshcode timer off                                             # → 1h 12m, $480.00
+moshcode timer log --week                                      # this week's timesheet
+```
+
+The timer is a stopwatch and a ledger in `~/.moshcode/timers.json`, and it knows
+nothing about money. It does know about **agents**, which is what makes it
+different from every other stopwatch: an hour of moshcode is an hour times
+however many engines ran in it.
+
+```sh
+moshcode client create "Acme Inc", https://acme.com, +1-555-0100
+moshcode client create globex --contact.telephone +1-555-0200 --contact.name Jane
+moshcode client payee acme-inc solana:9xQe…        # where their payments land
+```
+
+Contact details are written the way they arrive: the comma form for what you
+pasted out of a signature, `--a.b` dotted flags for anything else. There is no
+fixed field list — `--billing.po` works because it says what it means.
+`/business`, `/merchant` and `/customer` are the same command.
+
+```sh
+moshcode rate set default $100/hour/agent/upto:4
+moshcode rate set acme-inc 0.5 SOL/day --prefer SOL,USDC --accept fiat
+moshcode rate set initech $5000/project
+```
+
+`$100/hour/agent/upto:4` is the sentence from the contract, parsed: price,
+period, unit, and the cap that made the client sign. Four agents cost four
+hundred an hour and **so do six**. Order after the price does not matter.
+
+```sh
+moshcode billing acme-inc                 # a preview — writes nothing
+moshcode billing acme-inc --month --mark  # claim the time, record the invoice
+moshcode billing acme-inc --send          # compose the gateway command
+moshcode billing acme-inc --send --yes    # …and run it
+```
+
+Two rules the shape enforces: time is never billed twice (an entry carries the
+invoice that claimed it, and `--mark` is the only verb that writes), and nothing
+settles to an address nobody chose — no payee and no wallet rail is a refusal,
+not a guess.
+
+```sh
+moshcode payments connect coinpay                                   # runs `coinpay login`
+moshcode payments connect wallet --chain solana --address 9xQe…     # no gateway at all
+moshcode payments connect paypal --vault profullstack--prod         # keys live in the vault
+```
+
+moshcode composes an invoice; a gateway delivers it. No secret is stored here: a
+CLI gateway keeps its own session, and an OAuth gateway gets a reference to the
+vault its keys live in (`moshcode secrets`), never the keys.
+
+### Teams and grants (`/team`)
+
+For a machine you handed to somebody else:
+
+```sh
+moshcode team create Profullstack
+moshcode team add profullstack preshy --role member --rate '$80/hour'
+moshcode team grant profullstack preshy tools:coinpay
+moshcode team can profullstack/preshy payments:write     # → no
+```
+
+A permission is `surface:target`, written however you say it — `tools:coinpay`,
+`tools/coinpay` and `allow(tools/coinpay)` are one grant. Roles (`owner`,
+`admin`, `member`, `client`) are a starting set; grants add to them.
+
+The pit gates itself only when `MOSHCODE_MEMBER=<team>/<handle>` is set — with
+it unset the owner is at the keyboard and nothing is checked. **This is a
+guardrail, not a security boundary.** moshcode runs as the person at the
+keyboard, and anyone who can type `/team` can also edit
+`~/.moshcode/business.json`. A boundary that has to hold against somebody is an
+OS account, a container, or a scoped credential.
+
 ## The arcade (`/games`)
 
 Twenty-two games, in the pit or straight from a shell. There are no menus, no options

package/bin/moshcode.mjs

@@ -418,6 +418,40 @@ async function main() {
     if (code) process.exitCode = code;
     return;
   }
+  // The business layer. Imported where they are dispatched rather than at the
+  // top of the file: six modules that read two JSON files are dead weight in
+  // the startup path of `moshcode claude`, which is what this binary is mostly
+  // asked to do.
+  if (cmd === "timer") {
+    const { timerCommand } = await import("../src/timer.mjs");
+    process.exitCode = (await timerCommand(rest)) || 0;
+    return;
+  }
+  if (cmd === "client" || cmd === "business" || cmd === "merchant" || cmd === "customer") {
+    const { clientCommand } = await import("../src/clients.mjs");
+    process.exitCode = clientCommand(rest) || 0;
+    return;
+  }
+  if (cmd === "team" || cmd === "teams") {
+    const { teamCommand } = await import("../src/teams.mjs");
+    process.exitCode = teamCommand(rest) || 0;
+    return;
+  }
+  if (cmd === "rate" || cmd === "rates") {
+    const { rateCommand } = await import("../src/rates.mjs");
+    process.exitCode = rateCommand(rest) || 0;
+    return;
+  }
+  if (cmd === "billing" || cmd === "invoice") {
+    const { billingCommand } = await import("../src/billing.mjs");
+    process.exitCode = billingCommand(rest) || 0;
+    return;
+  }
+  if (cmd === "payments") {
+    const { paymentsCommand } = await import("../src/payments.mjs");
+    process.exitCode = paymentsCommand(rest) || 0;
+    return;
+  }
   if (cmd === "games" || cmd === "game" || cmd === "arcade") {
     const code = await gamesCommand(rest);
     if (code) process.exitCode = code;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moshcode",
-  "version": "0.70.0",
+  "version": "0.71.0",
   "type": "module",
   "description": "moshcode — a metal wrapper for coding engines and native UGig/CoinPay workflow CLIs, with OpenPRD and moshscript",
   "repository": {

package/prd/0012-billing-baked-into-the-agent-cli.md

@@ -0,0 +1,129 @@
+---
+openprd: "0.2"
+id: "0012"
+title: "Bake billing into the agent CLI — timer, clients, teams, rates, invoices, rails"
+status: Draft
+authors:
+  - anthony@profullstack.com
+created: 2026-08-29
+updated: 2026-08-29
+repo: https://github.com/moshcoder/moshcode
+discussion:
+implementation: src/timer.mjs · src/clients.mjs · src/teams.mjs · src/rates.mjs · src/billing.mjs · src/payments.mjs · src/business-store.mjs
+tags: business, billing, payments, time-tracking, permissions
+supersedes:
+superseded-by:
+---
+
+## Problem
+
+Every agentic CLI helps you do the work. None of them help you get paid for it.
+
+That gap is not small. An agency running moshcode has the whole engagement in
+this terminal — the engines, the herd, the repos, the deploys — and then leaves
+it to bill: hours reconstructed from memory into a spreadsheet, a rate that
+lives in a signed PDF nobody opens, an invoice retyped into a processor's web
+form. The one system that actually knows how long four agents ran on Acme's
+repo last Tuesday is the one system with nothing to say about it.
+
+It is worse than clerical. Agent work prices differently from human work and the
+existing tools cannot express it: an hour of moshcode is an hour times however
+many engines were running in it, capped at whatever the client was promised.
+"$100/hour/agent, up to 4" is a real sentence in a real contract, and there is
+nowhere to write it down except prose.
+
+The same terminal has a second unanswered question. A devops shop puts moshcode
+on machines its own people and its clients sit at, and "Preshy can use the
+CoinPay tool, the client can read invoices and nothing else" has no expression
+anywhere — not in moshcode, not in the tools it wraps.
+
+## Goals
+
+- Somebody who bills nobody still wants the timer, and gets it: `/timer on`,
+  `/timer off`, and a ledger, with no client, no rate and no gateway.
+- The rate card is written in the words of the contract and read by the machine
+  — including the cap, which is the clause that made the client sign.
+- The hours behind an invoice are the hours that were tracked, not the hours
+  somebody remembered on the last day of the month.
+- Time is never billed twice, and money never settles to an address nobody
+  chose.
+- Which processor a business already uses is their decision, not moshcode's.
+- The split between an operator, an employee and a client is something an
+  operator can write down, and something the pit then respects.
+
+## Non-Goals
+
+- Moving money. moshcode composes an invoice; a gateway delivers it. There is no
+  wallet, no key and no signing in this layer.
+- Being an accounting system. No ledgers, no tax, no reconciliation, no
+  multi-currency FX at settlement time.
+- Being a security boundary. The team gate stops the wrong command; it does not
+  stop a person with a shell. That is an OS account or a container, and this
+  PRD says so out loud rather than implying otherwise.
+- Server-side state. Everything here is two JSON files under `~/.moshcode`.
+  A shared, multi-machine business record is a later question.
+
+## Users
+
+- **The solo operator.** Bills a handful of clients hourly, wants the invoice to
+  be the time that was actually tracked.
+- **The agency.** Several clients, several people, several rates, and a promise
+  about agent caps that has to survive contact with a busy month.
+- **The employee or contractor.** Sits at a machine somebody else set up, needs
+  the engines and the timer and nothing that touches money.
+- **The client.** Occasionally handed a pit; should see what they are being
+  billed and the time behind it, and touch nothing.
+
+## Requirements
+
+- R1 [P0] `/timer on|off` tracks time to a local ledger, with no dependency on
+  a client, a rate or a gateway.
+- R2 [P0] A timer records how many agents were running, and `--agents auto`
+  reads that from the herd rather than asking.
+- R3 [P0] `/client create` accepts contact details as they arrive — a comma
+  form for what is pasted, `--a.b` dotted flags for anything else — with no
+  fixed field list.
+- R4 [P0] `/rate set <who> <spec>` parses the contract sentence, including
+  period, unit, `upto:N` cap and `min:N` floor, in any order after the price.
+- R5 [P0] `/billing <client>` previews without writing; `--mark` claims the
+  time exactly once; `--send` composes the gateway command and only `--yes`
+  runs it.
+- R6 [P0] An invoice refuses to settle when there is no client payee and no
+  wallet rail.
+- R7 [P1] `/payments` connects a rail — CLI (CoinPay, Stripe), OAuth (PayPal,
+  Coinbase) or a bare wallet — and stores no secret, only a vault reference.
+- R8 [P1] `/team` records people, roles and grants; `MOSHCODE_MEMBER` makes the
+  pit act as one of them, and the gate refuses commands they have no grant for.
+- R9 [P1] A permission is written however it is said — `tools:coinpay`,
+  `tools/coinpay`, `allow(tools/coinpay)` — and means the same thing.
+- R10 [P2] `/business`, `/merchant` and `/customer` are the same command as
+  `/client`; `/rates`, `/teams` and `/invoice` likewise.
+
+## UX Notes
+
+The five words are `/timer`, `/client`, `/rate`, `/billing`, `/payments`, plus
+`/team` for who may run them. Each is useful alone, which is the test each one
+had to pass: the timer with no rate, the rate with no gateway, the client with
+no invoice.
+
+Aliases are not synonyms in general English — a merchant is not a customer — but
+they are the same party in every conversation this is for, and the word somebody
+reaches for depends on which product taught it to them. Three doors, one room.
+
+The gate refuses by naming the permission and the command that would grant it,
+because the person who hits it is not the person who can fix it, and "ask an
+owner for `/team grant acme preshy tools:coinpay`" is a message they can paste.
+
+## Open Questions
+
+- Should the business record sync to app.moshcode.sh the way settings do (PRD
+  0010)? An agency's client list on one laptop is the same problem 0010 solved
+  for aliases — but a client list is a different kind of data, and the answer
+  may be that it belongs on the account rather than in a sync.
+- Should `/team` grants travel with `/load`, so a machine handed to a contractor
+  is configured by logging into it? That is the version where this stops being a
+  personal record and starts being an operator tool.
+- Beyond CoinPay, `--send` prints numbers rather than composing a command line.
+  Stripe's CLI is the obvious next one to teach it.
+- Member rates are recorded but not yet used: cost-per-person alongside
+  price-per-client is what turns an invoice into a margin.

package/src/billing.mjs

@@ -0,0 +1,363 @@
+// Tracked time × the rate they agreed to = the number you send them.
+//
+// This is the join, and it is the only file that touches all four of the other
+// ones: the ledger from `/timer`, the rate from `/rate`, the address from
+// `/client`, and the rail from `/payments`. It does the arithmetic nobody
+// enjoys doing at the end of a month, and then it stops — moshcode composes an
+// invoice, CoinPay (or Stripe, or a wallet) delivers it.
+//
+// Two rules the shape here exists to enforce:
+//
+//   Nothing is billed twice. An entry carries `billed` and the invoice id that
+//   claimed it, and drafting is separate from claiming: `/billing acme` is a
+//   preview you can run all day, `--mark` is the one that writes.
+//
+//   Nothing settles to an address nobody decided on. A client with no payee
+//   and no default wallet gets a refusal, not a best guess, because the failure
+//   mode of guessing is money arriving somewhere it cannot be recovered from.
+import { spawnSync } from "node:child_process";
+
+import { loadBusiness, loadTimers, newId, updateBusiness, updateTimers } from "./business-store.mjs";
+import { clientLabel, parseFields, resolveClient } from "./clients.mjs";
+import { GATEWAYS, defaultGateway, gatewayState } from "./payments.mjs";
+import { chargeFor, describeRate, formatMoney, isDollarPegged, isFiat, rateFor } from "./rates.mjs";
+import { humanDuration, selectEntries, windowFrom } from "./timer.mjs";
+import { acid, ash, bone, err, info, ok, table, warn } from "./ui.mjs";
+
+/** A line is a task; entries against the same task collapse into one. */
+function lineKeyFor(entry) {
+  return entry.task || entry.note || "untracked";
+}
+
+/**
+ * Turn a window of tracked time into an invoice draft.
+ *
+ * Charged per entry and then summed, not summed and then charged: the agent
+ * count varies between entries, and an average would quietly bill a two-agent
+ * afternoon at the four-agent rate (or the other way round, which is worse for
+ * a different reason).
+ */
+export function buildInvoice({ business, timers, clientId, since = null, until = null, all = false }) {
+  const client = business.clients?.[clientId] || null;
+  const rate = rateFor(business, clientId);
+  const entries = selectEntries(timers.entries || [], { client: clientId, since, until, unbilled: !all });
+
+  const lines = new Map();
+  const warnings = [];
+  let total = 0;
+  let seconds = 0;
+  const currency = rate?.currency || "USD";
+
+  for (const entry of entries) {
+    seconds += entry.seconds || 0;
+    const charge = chargeFor(entry, rate);
+    const key = lineKeyFor(entry);
+    const line = lines.get(key) || { what: key, seconds: 0, agents: 0, amount: 0, entries: [], flat: false };
+    line.seconds += entry.seconds || 0;
+    line.agents = Math.max(line.agents, entry.agents || 1);
+    line.entries.push(entry.id);
+    if (charge?.amount != null) { line.amount += charge.amount; total += charge.amount; }
+    if (charge?.flat) line.flat = true;
+    lines.set(key, line);
+    if (rate?.cap && (entry.agents || 1) > rate.cap) {
+      warnings.push(`${entry.id}: ${entry.agents} agents ran, ${rate.cap} billed (the cap)`);
+    }
+  }
+
+  // A flat project fee is earned once, however many entries sit under it.
+  if (rate?.per === "project" && entries.length) {
+    lines.set("project fee", { what: "project fee", seconds: 0, agents: 0, amount: rate.amount, entries: [], flat: true });
+    total += rate.amount;
+  }
+
+  return {
+    clientId,
+    client,
+    rate,
+    currency,
+    lines: [...lines.values()],
+    entries,
+    entryIds: entries.map((e) => e.id),
+    seconds,
+    total,
+    warnings,
+  };
+}
+
+/**
+ * Where this client's money should land: their payee, else the wallet rail.
+ *
+ * Per-client because the answer genuinely differs — one client pays a business
+ * account, another pays a project wallet — and a single global address makes
+ * that impossible to express without a second tool.
+ */
+export function settlementFor(business, clientId) {
+  const client = business.clients?.[clientId];
+  if (client?.payee?.address) return { ...client.payee, source: "client" };
+  const wallet = business.payments?.gateways?.wallet;
+  if (wallet?.address) return { chain: wallet.chain, address: wallet.address, source: "wallet" };
+  return null;
+}
+
+/**
+ * The CoinPay command line that turns a draft into a real invoice:
+ * `{ ok, args }`, or `{ ok: false, reason }`.
+ *
+ * Built rather than run: the amount, the currency and the address are decisions
+ * with consequences, and the last thing between them and a stranger's wallet
+ * should be a line a person can read. `--yes` is what runs it, which is the
+ * same convention CoinPay's own CLI uses for its irreversible verbs.
+ *
+ * The currency split is CoinPay's, not ours: `--currency` is a three-letter
+ * fiat code and the settlement ticker travels in `--crypto-currency`. That
+ * expresses a dollar-priced invoice settled in crypto exactly, and a
+ * USDC-priced one honestly, because USDC is a dollar. It cannot express a rate
+ * priced in SOL or BTC — the fiat amount would be a number nobody computed —
+ * so that case is refused with its reason rather than converted by guesswork.
+ */
+export function coinpayArgs(invoice, { payee = null, dueDate = null } = {}) {
+  const currency = invoice.currency;
+  if (!isFiat(currency) && !isDollarPegged(currency)) {
+    return {
+      ok: false,
+      reason: `this rate is priced in ${currency}, and a CoinPay invoice carries a fiat amount — `
+        + `price it in a currency (--prefer ${currency} keeps the settlement) or send it yourself`,
+    };
+  }
+  const priced = isFiat(currency) ? currency : "USD";
+  const crypto = isFiat(currency)
+    ? (invoice.rate?.prefer || []).find((c) => !isFiat(c)) || null
+    : currency;
+  const args = [
+    "invoice", "create",
+    "--amount", invoice.total.toFixed(2),
+    "--currency", priced,
+  ];
+  if (crypto) args.push("--crypto-currency", crypto);
+  if (dueDate) args.push("--due-date", dueDate);
+  if (payee?.address) args.push("--merchant-wallet-address", payee.address);
+  args.push("--notes", invoiceNote(invoice));
+  return { ok: true, args };
+}
+
+function invoiceNote(invoice) {
+  const who = invoice.client?.name || invoice.clientId || "work";
+  const lines = invoice.lines.filter((l) => l.what !== "project fee").map((l) => l.what);
+  const summary = lines.length ? `: ${lines.slice(0, 3).join(", ")}${lines.length > 3 ? `, +${lines.length - 3} more` : ""}` : "";
+  return `${who} — ${humanDuration(invoice.seconds)}${summary}`;
+}
+
+const USAGE = [
+  "usage: /billing <client> [--today|--week|--month|--since <date>] [--all] [--json]",
+  "       /billing <client> --mark            claim the time and record an invoice",
+  "       /billing <client> --send [--yes]    hand it to the connected gateway",
+  "       /billing list · /billing show <id> · /billing void <id>",
+];
+
+export function billingCommand(argv = [], { write = console.log, run = spawnSync } = {}) {
+  const verb = String(argv[0] ?? "").toLowerCase();
+  if (["list", "ls", ""].includes(verb) && argv.length <= 1) return listInvoices(argv.includes("--json"), write);
+  if (["show", "get"].includes(verb)) return showInvoice(argv[1], argv.includes("--json"), write);
+  if (["void", "cancel"].includes(verb)) return voidInvoice(argv[1], write);
+  return draftInvoice(argv, write, run);
+}
+
+function draftInvoice(argv, write, run) {
+  const { fields, rest } = parseFields(argv);
+  const business = loadBusiness();
+  const timers = loadTimers();
+
+  const found = resolveClient(business, rest[0]);
+  if (!found.ok) {
+    if (found.reason === "ambiguous") { write(err(`${JSON.stringify(rest[0])} matches ${found.matches.join(", ")} — say which`)); return 1; }
+    write(err(`no client ${JSON.stringify(rest[0] ?? "")} — ${acid("/client list")}`));
+    USAGE.forEach(write);
+    return 1;
+  }
+
+  const invoice = buildInvoice({
+    business,
+    timers,
+    clientId: found.id,
+    since: windowFrom(fields),
+    all: Boolean(fields.all),
+  });
+
+  if (fields.json) { write(JSON.stringify(invoice, null, 2)); return 0; }
+
+  if (!invoice.entries.length) {
+    write(info(`nothing unbilled for ${bone(found.id)}${fields.all ? "" : " — --all to include time already billed"}`));
+    return 0;
+  }
+  if (!invoice.rate) {
+    write(err(`no rate for ${bone(found.id)} — ${acid(`/rate set ${found.id} $100/hour/agent/upto:4`)}`));
+    return 1;
+  }
+
+  write(`  ${clientLabel(found.id, invoice.client)} ${ash("·")} ${ash(describeRate(invoice.rate))}`);
+  write(table(
+    invoice.lines.map((l) => [
+      l.what,
+      l.seconds ? humanDuration(l.seconds) : ash("—"),
+      l.agents > 1 ? `${l.agents}×` : "",
+      acid(formatMoney(l.amount, invoice.currency)),
+    ]),
+    { columns: ["what", "time", "agents", "amount"], indent: 2 },
+  ));
+  write(`  ${ash("total")} ${bone(humanDuration(invoice.seconds))} ${ash("→")} ${acid(formatMoney(invoice.total, invoice.currency))}`);
+  for (const note of invoice.warnings) write(`  ${ash(note)}`);
+
+  const settlement = settlementFor(business, found.id);
+  if (!settlement) {
+    write(warn("no payee for this client and no wallet rail — nothing to settle to"));
+    write(`  ${acid(`/client payee ${found.id} solana:<address>`)} ${ash("or")} ${acid("/payments connect wallet --chain solana --address <addr>")}`);
+  } else {
+    write(`  ${ash("settles to")} ${acid(`${settlement.chain}:${settlement.address}`)} ${ash(`(${settlement.source})`)}`);
+  }
+
+  if (!fields.mark && !fields.send) {
+    write(`  ${ash("this is a preview —")} ${acid(`/billing ${found.id} --mark`)} ${ash("claims the time,")} ${acid("--send")} ${ash("hands it to the gateway")}`);
+    return 0;
+  }
+
+  if (!settlement) return 1;
+
+  const record = commitInvoice(invoice, settlement);
+  const claimed = record.entryIds.length;
+  write(ok(`invoice ${bone(record.id)} — ${acid(formatMoney(record.total, record.currency))} ${ash(`(${claimed} ${claimed === 1 ? "entry" : "entries"} claimed)`)}`));
+
+  if (!fields.send) return 0;
+  return handOff(record, invoice, business, fields, write, run);
+}
+
+/** Write the invoice and mark its entries, in that order. */
+function commitInvoice(invoice, settlement) {
+  const id = newId("inv-");
+  const record = {
+    id,
+    client: invoice.clientId,
+    createdAt: new Date().toISOString(),
+    currency: invoice.currency,
+    total: invoice.total,
+    seconds: invoice.seconds,
+    lines: invoice.lines,
+    entryIds: invoice.entryIds,
+    rate: invoice.rate,
+    settlement,
+    status: "draft",
+    gateway: null,
+    gatewayRef: null,
+  };
+  updateBusiness((data) => { data.invoices[id] = record; });
+  updateTimers((data) => {
+    for (const entry of data.entries) {
+      if (record.entryIds.includes(entry.id)) { entry.billed = true; entry.invoice = id; }
+    }
+  });
+  return record;
+}
+
+function handOff(record, invoice, business, fields, write, run) {
+  const key = fields.gateway && fields.gateway !== true ? String(fields.gateway).toLowerCase() : defaultGateway(business);
+  if (!key || !GATEWAYS[key]) {
+    write(warn("no payment rail chosen — the invoice is recorded, but nothing was sent"));
+    write(`  ${acid("/payments connect coinpay")}`);
+    return 1;
+  }
+  if (key !== "coinpay") {
+    // Every other rail is a passthrough moshcode has not been taught to speak.
+    // Saying so is better than composing a command line from guesswork.
+    write(info(`${bone(key)} is connected, but moshcode only composes CoinPay invoices`));
+    write(`  ${ash("the numbers are above, and")} ${acid(`/billing show ${record.id}`)} ${ash("has them again whenever you need them")}`);
+    return 0;
+  }
+
+  const state = gatewayState("coinpay", business);
+  if (!state.installed) { write(err(`coinpay is not on PATH — ${acid("/install coinpay")}`)); return 1; }
+
+  const composed = coinpayArgs({ ...invoice, total: record.total }, { payee: record.settlement, dueDate: fields.due && fields.due !== true ? String(fields.due) : null });
+  if (!composed.ok) {
+    write(warn(composed.reason));
+    write(`  ${ash(`invoice ${record.id} is recorded either way —`)} ${acid(`/billing show ${record.id}`)}`);
+    return 1;
+  }
+  const { args } = composed;
+  const printable = `coinpay ${args.map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(" ")}`;
+  write(`  ${ash(printable)}`);
+  if (!fields.yes) {
+    write(`  ${ash("read it, then")} ${acid(`/billing ${record.client} --send --yes`)} ${ash("to run it")}`);
+    return 0;
+  }
+
+  const result = run("coinpay", args, { stdio: "inherit" });
+  if (result?.error) { write(err(String(result.error.message || result.error))); return 1; }
+  if (result?.status) { write(err(`coinpay exited ${result.status} — invoice ${record.id} is still a local draft`)); return result.status; }
+  updateBusiness((data) => {
+    data.invoices[record.id].gateway = "coinpay";
+    data.invoices[record.id].status = "handed-off";
+  });
+  write(ok(`handed to CoinPay — ${acid("coinpay invoice send <id>")} ${ash("emails it to the client")}`));
+  return 0;
+}
+
+function listInvoices(json, write) {
+  const { invoices } = loadBusiness();
+  const ids = Object.keys(invoices).sort();
+  if (json) { write(JSON.stringify(invoices, null, 2)); return 0; }
+  if (!ids.length) { write(info("no invoices yet.")); write(`  ${acid("/billing <client> --mark")}`); return 0; }
+  write(table(
+    ids.map((id) => {
+      const inv = invoices[id];
+      return [
+        bone(id),
+        inv.client || "",
+        ash(String(inv.createdAt || "").slice(0, 10)),
+        humanDuration(inv.seconds),
+        acid(formatMoney(inv.total, inv.currency)),
+        ash(inv.status || "draft"),
+      ];
+    }),
+    { columns: ["id", "client", "date", "time", "amount", "status"], indent: 2 },
+  ));
+  return 0;
+}
+
+function showInvoice(id, json, write) {
+  const { invoices } = loadBusiness();
+  const invoice = invoices[String(id ?? "")];
+  if (!invoice) { write(err(`no invoice ${JSON.stringify(id ?? "")} — ${acid("/billing list")}`)); return 1; }
+  if (json) { write(JSON.stringify(invoice, null, 2)); return 0; }
+  write(`  ${bone(invoice.id)} ${ash(invoice.client || "")} ${ash(String(invoice.createdAt).slice(0, 10))}`);
+  write(table(
+    invoice.lines.map((l) => [l.what, l.seconds ? humanDuration(l.seconds) : ash("—"), acid(formatMoney(l.amount, invoice.currency))]),
+    { columns: ["what", "time", "amount"], indent: 2 },
+  ));
+  write(`  ${ash("total")} ${acid(formatMoney(invoice.total, invoice.currency))} ${ash(`· ${invoice.status}`)}`);
+  if (invoice.settlement) write(`  ${ash("settles to")} ${acid(`${invoice.settlement.chain}:${invoice.settlement.address}`)}`);
+  return 0;
+}
+
+/**
+ * Undo the claim, not the invoice.
+ *
+ * The entries go back to unbilled so they can be re-drafted; the invoice record
+ * stays and is marked void. Deleting it would erase the fact that a number was
+ * once quoted, which is exactly the fact somebody comes looking for.
+ */
+function voidInvoice(id, write) {
+  const key = String(id ?? "");
+  const { invoices } = loadBusiness();
+  const invoice = invoices[key];
+  if (!invoice) { write(err(`no invoice ${JSON.stringify(key)}`)); return 1; }
+  if (invoice.status === "void") { write(info(`${key} is already void`)); return 0; }
+  updateBusiness((data) => { data.invoices[key].status = "void"; data.invoices[key].voidedAt = new Date().toISOString(); });
+  updateTimers((data) => {
+    for (const entry of data.entries) {
+      if (entry.invoice === key) { entry.billed = false; entry.invoice = null; }
+    }
+  });
+  write(ok(`${bone(key)} void — ${invoice.entryIds.length} entries are billable again`));
+  return 0;
+}
+
+export { USAGE as BILLING_USAGE };