moshcode 0.58.0 → 0.59.0

package/README.md

@@ -30,6 +30,7 @@ or miss one that does. A test fails the build when it drifts.
 | `moshcode start` | engines | launch an engine with its native defaults |
 | `moshcode herd` | runtime | run agent sessions that outlive this terminal |
 | `moshcode ps` | runtime | list herd sessions and what each one is doing |
+| `moshcode cost` | runtime | what each session is spending, read from the engines' own logs |
 | `moshcode attach` | runtime | attach this terminal to a herd session |
 | `moshcode kill` | runtime | end a herd session |
 | `moshcode wait` | runtime | block until a session is blocked, done, or idle |
@@ -338,6 +339,58 @@ moshcode herd start claude --name watch  # then run `moshcode herd watch` in the
 
 With `--ask`, whatever you reply is typed into the session that was waiting.
 
+### What it is costing
+
+Every engine already writes down what it used, so nothing has to be
+instrumented or proxied — `moshcode cost` reads the CLIs' own session logs and
+lines them up against the herd:
+
+```sh
+moshcode cost                    # per session, in the window (default: 24h)
+moshcode cost api                # one session, with its engine runs
+moshcode cost --all --since 7d   # every engine session on the box, herd or not
+moshcode cost --watch            # the same report, re-read every 10s
+moshcode cost --json             # for a script
+```
+
+```
+  session  engine  model          in    out   cache  cost    age
+  api      claude  claude-opus-5  1.2k  27k   10.5M  $9.91~  42m
+  audit    codex   gpt-5.6-sol    400   200   600    —       12m
+
+  total  $9.91~  1.6k in · 27k out · 10.5M cached
+  ~ estimated from published rates; unmarked figures are the engine's own.
+⚠ no rate for gpt-5.6-sol — tokens counted, cost omitted.
+```
+
+| engine | where the number comes from |
+|---|---|
+| claude | per-message `usage` in `~/.claude/projects/**/*.jsonl` |
+| codex | cumulative `token_count` events in `~/.codex/sessions/…` |
+| opencode, privacycode | the per-message `cost` each one computed itself |
+| aider | the running session total it prints into `.aider.chat.history.md` |
+
+**A `~` is an estimate, and an unmarked figure is not.** opencode and aider
+price their own messages, and that price is reported untouched. Claude Code and
+Codex record tokens only — which is the honest state of things on a
+subscription, where the marginal request costs nothing extra — so those are
+multiplied by published rates to answer "what would this have cost on the API".
+
+A model nobody has priced shows its tokens and no cost, rather than a
+convincing-looking zero. Price it yourself in `~/.moshcode/pricing.json`:
+
+```json
+{ "gpt-5.6-sol": { "input": 1.25, "output": 10 } }
+```
+
+Cache tokens get their own column because on a long agent session they are most
+of the traffic and a tenth of the price; folding them into `in` makes a $3
+session look like a $60 one. Attribution is engine + directory + "started before
+this run did", so a session that shares a directory with another agent can pick
+up its neighbour's work — `--json` carries the run list when you need to check.
+gemini, kimi, qwen, deepseek and openagents keep no readable usage log, so they
+report no cost rather than zero cost.
+
 ### Driving it from a script or another agent
 
 There is no second API — every verb takes `--json`, and that is what a machine
@@ -1013,6 +1066,9 @@ agents("claude");                              // drop into an autonomous sessio
 
 ```sh
 moshcode run examples/alive.mosh              # run a script
+moshcode run examples/account.mosh --dry-run  # log in, then do work that needs an account
+moshcode run examples/aliases.mosh --dry-run  # define and run the pit's shortcuts
+moshcode run examples/research-desk.mosh      # stocksRead/cryptoRead/newsRead → one digest
 moshcode run deploy.mosh --dry-run            # narrate without executing
 moshcode run alive.mosh --max 5               # bound the while loop (default 3)
 moshcode run deploy.mosh staging --fast       # extra args reach the script as argv
@@ -1058,6 +1114,35 @@ chmod +x deploy.mosh
 | `stop()` | end the loop (`alive = false`) |
 | `repeat()` | back to the top of the loop |
 
+**Account verbs** (see [Authentication](#authentication)):
+
+| verb | description |
+|---|---|
+| `await requireLogin()` | gate — verify, log in if needed, **throw** if it can't; returns the user |
+| `await login({ device, browser, force })` | authenticate; no-op when already signed in; returns `{ ok, email, already }` |
+| `await whoami()` | the account as a value: `{ status, verified, api, user: { id, email, name, credits } }` |
+| `logout()` | forget this machine's credentials |
+
+**Alias verbs** — the pit's own shortcuts (`~/.moshcode/aliases.json`), readable and writable from a script:
+
+| verb | description |
+|---|---|
+| `alias()` | every alias, as a `name → line` map |
+| `alias(name)` | one alias's line, or `null` |
+| `alias(name, line)` | define one; refuses names moshcode already owns |
+| `unalias(name)` | forget one |
+| `runAlias(name, …args)` | run one, args appended; returns `{ ok, code }` |
+
+**Read verbs** — the tools as *values* rather than tables:
+
+| verb | description |
+|---|---|
+| `await stocksRead(…)` | same args as `stocks(…)`, returns the parsed JSON |
+| `await cryptoRead(…)` | same args as `crypto(…)`, returns the parsed JSON |
+| `await newsRead({ list, limit })` | headlines as `[{ title, link, source, date }, …]` |
+| `herdRead(name, { lines })` | a herd session's screen, as a string |
+| `herdList()` | the roster: `[{ name, engine, state, cwd, alive }, …]` |
+
 **CLI verbs** (each shells out to `moshcode <name> ...args`):
 
 | verb | description |
@@ -1082,7 +1167,26 @@ chmod +x deploy.mosh
 | `turso(args…)` | drive the Turso CLI |
 | `tailscale(args…)` | drive the Tailscale CLI |
 | `coral(args…)` | drive the Coral CLI (SQL over APIs, databases, internal systems) |
+| `alpaca(args…)` | drive the native Alpaca trading CLI |
 | `mcpjam(args…)` | drive the MCPJam CLI (test, debug, and validate MCP servers) |
+| `trade(args…)` | look up tickers, inspect markets, preview/place Alpaca orders |
+| `stocks(args…)` | research tickers via advis0r (`stocksRead` returns the data) |
+| `crypto(args…)` | research crypto pairs via advis0r (`cryptoRead` returns the data) |
+| `advisor(args…)` | query advis0r directly |
+| `news(args…)` | read, search, and subscribe to news feeds (`newsRead` returns the items) |
+| `rss(args…)` | manage RSS subscriptions and reading lists |
+| `plugin(args…)` | install/manage moshcode plugins from the marketplace |
+| `engines()` | list coding engines and whether they're installed |
+| `tools()` | list the adjacent workflow CLIs and whether they're installed |
+| `dns(args…)` | drive the Moshpit DNS bridge (enable, status, resolve) |
+| `doh(args…)` | run/inspect the DNS-over-HTTPS endpoint |
+| `site(args…)` | scaffold and publish a site |
+| `serve(args…)` | serve a directory over HTTP |
+| `template(args…)` | scaffold from a moshcode template |
+| `save()` / `load()` | push/pull settings to your moshcode account (needs login) |
+| `herd(args…)` | drive the herd (`herdStart`/`herdWait`/`herdRead` return values) |
+| `ps()` | print the herd roster |
+| `ai(prompt, { engine })` | run an engine headlessly and **return** its output as a string |
 | `pwd()` | print the current repo/location |
 | `run(file)` | run another .mosh file (include/compose) |
 
@@ -1094,6 +1198,81 @@ chmod +x deploy.mosh
 | `argv` | positional args passed after the script file |
 | `env` | `process.env` — parameterize scripts from the environment |
 
+### Authentication
+
+Some verbs need an account: `notify()`/`ask()` reach you through
+`app.moshcode.sh`, and `save()`/`load()` sync settings to it. A script says so
+once, at the top, instead of failing one call at a time later on:
+
+```js
+const me = await requireLogin();          // verifies; logs in if it has to
+say(`signed in as ${me.email} (${me.credits} credits)`);
+```
+
+- **`requireLogin({ device, browser })`** — the gate. Verifies this machine
+  against the app; if there's no usable session it runs the login flow, then
+  re-checks. Returns the verified `{ id, email, name, credits }`. **Throws** if
+  it still can't authenticate — the one verb here that does, because "require"
+  means the script must not continue without an account.
+- **`login({ device, browser, force })`** — idempotent. Returns early with
+  `{ already: true }` when you're already signed in, so a script you re-run all
+  day never throws a browser tab at you. Returns `{ ok: false, error }` on
+  failure rather than throwing, so a script can fall back to read-only work.
+- **`whoami()`** — the account as a value, verified against the app:
+  `{ status, verified, api, user }` where `status` is `authenticated`,
+  `not_logged_in`, `expired`, `unverified`, or `unreachable`. Never throws — an
+  unreachable app is a status, not an exception.
+- **`logout()`** — forget the local credentials.
+
+The flow is picked for where the script is running: the loopback/browser flow
+locally, and the device-code flow over SSH or on a headless box (where a
+`127.0.0.1` callback would land on the *browser's* machine and never arrive).
+`{ device: true }` / `{ browser: true }` pin it either way. Credentials live in
+`~/.moshcode/credentials.json` (mode `0600`) — the same ones `moshcode login`
+writes, so logging in once covers the CLI, the pit, and every script.
+
+```js
+// gate on the balance, not just the session
+const me = await whoami();
+if (!me.verified) { say("read-only run — not signed in"); }
+else if (me.user.credits < 10) notify(`only ${me.user.credits} credits left`);
+```
+
+### Aliases
+
+The pit keeps named shortcuts for the lines you retype (`/alias set gs "git
+status"`). Scripts read and write the same store, so your vocabulary and
+moshcode's are one thing rather than two:
+
+```js
+alias("gs", "git status --short");   // define (refuses names moshcode owns)
+alias("cc", "/agents claude");       // a leading `/` is a moshcode command
+runAlias("gs", "--branch");          // → git status --short --branch
+```
+
+Expansion is the pit's rule: a leading `/` routes to the moshcode command of
+that name, anything else is a shell line, and arguments are **appended** rather
+than substituted — exactly how a shell alias behaves. `runAlias()` returns
+`{ ok, code }` like `shell()`, and `{ ok: false, code: 127 }` when there's no
+such alias.
+
+### Reading the tools, not just running them
+
+`stocks report NVDA` prints a table; a script usually wants the number. The
+`*Read()` verbs call the same layer the printed commands render from and hand
+back parsed data:
+
+```js
+const report = await stocksRead("report", "NVDA");   // → JSON, or null on error
+const btc    = await cryptoRead("quote", "BTC/USD");
+const items  = await newsRead({ limit: 5 });          // [{ title, link, source, date }]
+```
+
+A failed lookup returns `null` (or `[]`) rather than throwing, so one bad symbol
+doesn't take a briefing script down. Same reasoning as the herd's
+`herdRead()`/`herdList()`: shelling out gives you `{ ok, code }`, and the whole
+point of these is the value.
+
 ### Human-in-the-loop
 
 - `notify(msg)` — fire-and-forget. Pings the operator across configured channels

package/bin/moshcode.mjs

@@ -336,7 +336,7 @@ async function main() {
     const [key, engine] = resolved;
     return launchEngine(key, engine, rest.slice(1));
   }
-  // The herd (PRD 0009). `herd` is the namespace; the five verbs people reach
+  // The herd (PRD 0009). `herd` is the namespace; the verbs people reach
   // for most often are also top-level, because `moshcode ps` is what someone
   // types when they want to know what is running and nobody should have to
   // learn a namespace to ask that.
@@ -344,7 +344,7 @@ async function main() {
     process.exitCode = (await herdCommand(rest)) || 0;
     return;
   }
-  if (["ps", "attach", "kill", "wait", "restore"].includes(cmd)) {
+  if (["ps", "attach", "kill", "wait", "restore", "cost"].includes(cmd)) {
     process.exitCode = (await herdCommand([cmd === "ps" ? "ps" : cmd, ...rest])) || 0;
     return;
   }

package/examples/account.mosh

@@ -0,0 +1,48 @@
+#!/usr/bin/env moshscript
+// account.mosh — authenticate the operator, then do work that needs an account.
+//
+// `requireLogin()` is the gate: it verifies this machine against
+// app.moshcode.sh and, if there is no usable session, runs the login flow
+// (browser locally, device code over SSH) before the script continues. Anything
+// downstream that needs an account — notify(), ask(), save()/load() — would
+// otherwise fail one call at a time, much later and much less legibly.
+//
+// Try it safely first:
+//
+//   moshcode run examples/account.mosh --dry-run
+//   chmod +x examples/account.mosh && ./examples/account.mosh 5
+//
+// argv[0] is the minimum credit balance to demand (default: 1).
+
+const needCredits = Number(argv[0] || 1);
+
+// Blocks until there is a verified account. THROWS if it can't get one — that
+// is what "require" means, and it stops the script here rather than halfway
+// through the work.
+const me = await requireLogin();
+say(`🤘 signed in as ${me.email || me.name || "moshcoder"}`);
+
+// whoami() hands the account back as a value, so a script can branch on it
+// instead of re-parsing `moshcode whoami` output.
+if (me.credits != null && me.credits < needCredits) {
+  say(`⛔ ${me.credits} credits left, need ${needCredits} — topping up is a human job`);
+  notify(`moshcode is out of credits (${me.credits}) — top up to keep the pit going`);
+  stop();
+} else {
+  // Settings sync needs the account we just proved we have.
+  load();                       // → moshcode load   (pull settings down)
+  say("⚙️  settings pulled from your account");
+
+  const test = shell("pnpm -r test");
+  if (!test.ok) {
+    // The human-in-the-loop gate: this blocks until someone answers at
+    // app.moshcode.sh/approve/:id — which only works because we're logged in.
+    const next = await ask(`tests failed (exit ${test.code}) — ship anyway, or fix?`);
+    say(`👤 operator says: ${next ?? "(no reply — stopping)"}`);
+    if (next == null) stop();
+  } else {
+    say("✅ green — saving settings back up");
+    save();                     // → moshcode save   (push settings up)
+    notify("moshcode: tests green, settings synced 🤘");
+  }
+}

package/examples/aliases.mosh

@@ -0,0 +1,56 @@
+#!/usr/bin/env moshscript
+// aliases.mosh — the pit's shortcuts, from a script.
+//
+// The pit keeps named shortcuts for the lines you retype (`/alias set gs "git
+// status"`). They are your vocabulary, not moshcode's, so a script can read the
+// same store, define new ones, and run them — instead of re-spelling every one
+// of those lines in every script.
+//
+// The expansion rule is the pit's: a leading `/` is a moshcode command,
+// anything else is a shell line, and arguments are appended rather than
+// substituted — so runAlias("gs", "--short") is `git status --short`.
+//
+// Try it safely first:
+//
+//   moshcode run examples/aliases.mosh --dry-run
+//   chmod +x examples/aliases.mosh && ./examples/aliases.mosh
+//
+// argv[0] is the engine an alias should open (default: claude).
+
+const engine = argv[0] || "claude";
+
+// Set up a small kit. alias(name, line) returns { ok, error, previous }; a name
+// moshcode already owns (`agents`, `install`, …) is refused rather than
+// shadowed, because a shortcut that silently does nothing is worse than one
+// that was never accepted.
+const kit = {
+  gs: "git status --short --branch",
+  gl: "git log --oneline -12",
+  cc: `/agents ${engine}`,          // a leading `/` → the moshcode command
+};
+
+for (const [name, line] of Object.entries(kit)) {
+  const r = alias(name, line);
+  if (!r.ok) say(`⚠️  couldn't define /${name} — ${r.error}`);
+}
+
+// alias() with no arguments is the whole map — the same one the pit shows.
+const all = alias();
+say(`🔖 ${Object.keys(all).length} alias(es) on this machine`);
+
+// Run one. Returns { ok, code } like shell() and the CLI verbs, so a script can
+// branch on the outcome without try/catch.
+//
+// Under --dry-run nothing above was actually written, so these report the
+// aliases as missing (code 127) rather than pretending to run them — a dry run
+// narrates what it would do, and it genuinely doesn't know what an undefined
+// alias expands to. Run it for real to see them execute.
+const status = runAlias("gs");
+if (!status.ok && status.code !== 127) say(`git status exited ${status.code}`);
+
+runAlias("gl", "--author", env.USER || "");   // extra args are appended
+
+// Clean up the throwaway ones, leave the useful one behind.
+unalias("gl");
+
+say(`🤘 /cc is yours now — type it in the pit to open ${engine}`);

package/examples/research-desk.mosh

@@ -0,0 +1,49 @@
+#!/usr/bin/env moshscript
+// research-desk.mosh — a morning briefing, assembled from the read verbs.
+//
+// `stocks report NVDA` prints a table; `stocksRead("report", "NVDA")` hands
+// back the JSON. That is the difference this script is built on: the *Read()
+// verbs return values, so a script can rank, threshold, and summarize instead
+// of scraping stdout. Same advis0r/feed layer the printed commands render from.
+//
+// Try it safely first:
+//
+//   moshcode run examples/research-desk.mosh --dry-run
+//   chmod +x examples/research-desk.mosh && ./examples/research-desk.mosh NVDA AMD
+//
+// argv is the ticker list (default: NVDA TSLA).
+
+const tickers = argv.length ? argv : ["NVDA", "TSLA"];
+const briefing = [];
+
+// Rank the tickers by whatever score advis0r returns, keeping only the ones
+// worth a human's attention. A failed lookup comes back null rather than
+// throwing, so one bad symbol doesn't take the briefing down.
+for (const symbol of tickers) {
+  const data = await stocksRead("report", symbol);
+  if (!data) { say(`⚠️  no data for ${symbol}`); continue; }
+  const score = data.score ?? data.report?.score ?? null;
+  briefing.push({ symbol, score });
+  say(`📈 ${symbol}: ${score ?? "no score"}`);
+}
+
+// Crypto reads the same way.
+const btc = await cryptoRead("quote", "BTC/USD");
+if (btc) say(`🪙 BTC/USD: ${btc.price ?? btc.quote?.price ?? "?"}`);
+
+// Headlines from your own subscriptions (or pass { list: "smallweb" } for one
+// of the built-in feed lists).
+const headlines = await newsRead({ limit: 5 });
+for (const item of headlines) {
+  say(`📰 ${item.source ? `[${item.source}] ` : ""}${item.title}`);
+}
+
+// One ping with the whole picture, rather than one per lookup.
+const movers = briefing
+  .filter((b) => b.score != null)
+  .sort((a, b) => b.score - a.score)
+  .slice(0, 3)
+  .map((b) => `${b.symbol} ${b.score}`)
+  .join(", ");
+
+notify(`morning desk — ${movers || "no scores today"} · ${headlines.length} headline(s)`);

package/package.json

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

package/src/auth.mjs

@@ -166,89 +166,84 @@ export async function loginAuto({ device = false, browser = false } = {}) {
   return loginDevice({ open: !isRemoteShell() });
 }
 
-/** Print who is logged in (verified against the app). */
-export async function whoami({ json = false } = {}) {
+/**
+ * Who is logged in, as a value — the shape `whoami --json` prints, and what
+ * moshscript's whoami()/requireLogin() read (src/commands.mjs).
+ *
+ * Returning rather than printing is the point: a script needs to branch on the
+ * account ("do I have credits?", "is this the right email?"), and the only way
+ * to get that out of a printing function is to re-parse its stdout. One
+ * verified-identity implementation, two callers — the CLI renders it, the
+ * script reads it — so the two can never disagree about what "logged in" means.
+ *
+ * Never throws: an unreachable app is a `status` like any other, because the
+ * caller is usually deciding whether to *start* work, not reporting an outage.
+ */
+export async function identity() {
   const creds = loadCreds();
   if (!creds?.token) {
-    if (json) {
-      console.log(JSON.stringify({
-        status: "not_logged_in",
-        verified: false,
-        api: API(),
-        user: null,
-      }, null, 2));
-    } else {
-      console.log("not logged in — run: moshcode login");
-    }
-    return;
+    return { status: "not_logged_in", verified: false, api: API(), user: null };
   }
   const api = creds.api || API();
+  // What we know locally, used for every unverified outcome. Deliberately not
+  // presented as confirmed: the app is the authority on the account, and these
+  // fields are only what the last successful login happened to write down.
   const localUser = {
     id: creds.id ?? null,
     email: creds.email ?? null,
     name: null,
     credits: null,
   };
-  const printJson = (value) => console.log(JSON.stringify(value, null, 2));
   try {
     const res = await fetch(`${api}/api/me`, { headers: { authorization: `Bearer ${creds.token}` } });
     if (res.status === 401) {
-      if (json) {
-        printJson({
-          status: "expired",
-          verified: false,
-          api,
-          user: localUser,
-          error: { type: "auth", status: 401 },
-        });
-      }
-      else console.log("session expired — run: moshcode login");
-      return;
+      return { status: "expired", verified: false, api, user: localUser, error: { type: "auth", status: 401 } };
     }
     // Any other error status still has a body, and it isn't an account — reading
-    // it as one prints a made-up identity for a session the app just refused.
+    // it as one reports a made-up identity for a session the app just refused.
     if (!res.ok) {
-      if (json) {
-        printJson({
-          status: "unverified",
-          verified: false,
-          api,
-          user: localUser,
-          error: { type: "http", status: res.status },
-        });
-      } else {
-        console.log(`${creds.email || "logged in"} @ ${api} (couldn't verify — the app returned ${res.status})`);
-      }
-      return;
+      return { status: "unverified", verified: false, api, user: localUser, error: { type: "http", status: res.status } };
     }
     const me = await res.json();
-    if (json) {
-      printJson({
-        status: "authenticated",
-        verified: true,
-        api,
-        user: {
-          id: me.id ?? creds.id ?? null,
-          email: me.email ?? creds.email ?? null,
-          name: me.name ?? null,
-          credits: me.credits ?? null,
-        },
-      });
-    } else {
-      console.log(`${me.email || me.name || "moshcoder"} 🤘  (${me.credits ?? "?"} credits)  @ ${api}`);
-    }
+    return {
+      status: "authenticated",
+      verified: true,
+      api,
+      user: {
+        id: me.id ?? creds.id ?? null,
+        email: me.email ?? creds.email ?? null,
+        name: me.name ?? null,
+        credits: me.credits ?? null,
+      },
+    };
   } catch {
-    if (json) {
-      printJson({
-        status: "unreachable",
-        verified: false,
-        api,
-        user: localUser,
-        error: { type: "network" },
-      });
-    } else {
-      console.log(`${creds.email || "logged in"} @ ${api} (couldn't reach the app to verify)`);
-    }
+    return { status: "unreachable", verified: false, api, user: localUser, error: { type: "network" } };
+  }
+}
+
+/** Print who is logged in (verified against the app). */
+export async function whoami({ json = false } = {}) {
+  const me = await identity();
+  if (json) {
+    console.log(JSON.stringify(me, null, 2));
+    return;
+  }
+  const who = me.user?.email || me.user?.name;
+  switch (me.status) {
+    case "not_logged_in":
+      console.log("not logged in — run: moshcode login");
+      return;
+    case "expired":
+      console.log("session expired — run: moshcode login");
+      return;
+    case "unverified":
+      console.log(`${who || "logged in"} @ ${me.api} (couldn't verify — the app returned ${me.error.status})`);
+      return;
+    case "unreachable":
+      console.log(`${who || "logged in"} @ ${me.api} (couldn't reach the app to verify)`);
+      return;
+    default:
+      console.log(`${who || "moshcoder"} 🤘  (${me.user.credits ?? "?"} credits)  @ ${me.api}`);
   }
 }
 

package/src/cli-schema.mjs

@@ -112,6 +112,31 @@ export const CORE_CLI_COMMANDS = [
     seeAlso: ["herd", "attach", "wait"],
     note: "state is idle, working, blocked, done or unknown — unknown is a safe answer, not a failure.",
   },
+  {
+    name: "cost",
+    group: "runtime",
+    description: "what each session is spending, read from the engines' own logs",
+    synopsis: [["moshcode cost [name] [--all] [--since 6h] [--json]", "session, engine, model, tokens, cost"]],
+    flags: [
+      ["--all", "every engine session on disk, herd or not", ""],
+      ["--since <dur>", "how far back to look (30m, 6h, 3d)", "24h"],
+      ["--engine <list>", "only these engines, comma-separated", "all"],
+      ["--watch [secs]", "re-read on an interval until ctrl-c", "10"],
+      ["--json", "machine-readable", ""],
+    ],
+    examples: [
+      ["moshcode cost", "what is the herd costing me right now?"],
+      ["moshcode cost api --json", "one session, with its engine runs broken out"],
+      ["moshcode cost --all --since 7d", "everything the agents did this week"],
+    ],
+    seeAlso: ["ps", "herd", "attach"],
+    note: "the numbers come from each CLI's own session log — claude's ~/.claude/projects transcripts, "
+      + "codex's rollout token counts, opencode's per-message cost, aider's chat history. a figure marked "
+      + "`~` was worked out from published rates and is what the tokens WOULD cost on the api; unmarked "
+      + "figures are the engine's own arithmetic. models with no rate show tokens and no cost — add yours "
+      + "to ~/.moshcode/pricing.json. gemini, kimi, qwen, deepseek and openagents log nothing readable, "
+      + "so they report no cost rather than zero.",
+  },
   {
     name: "attach",
     group: "runtime",
@@ -874,6 +899,14 @@ export const HERD_VERBS = [
   { name: "status", description: "what the herd is running on, and how many sessions",
     synopsis: [["moshcode herd status [--json]", ""]],
     flags: [["--json", "machine-readable", ""]] },
+  { name: "cost", description: "what each session is spending, from the engines' own logs",
+    synopsis: [["moshcode herd cost [name] [--all] [--since 6h] [--json]", ""]],
+    flags: [
+      ["--all", "every engine session on disk, herd or not", ""],
+      ["--since <dur>", "how far back to look", "24h"],
+      ["--watch [secs]", "re-read on an interval", "10"],
+      ["--json", "machine-readable", ""],
+    ] },
   { name: "start", description: "start a session and hand the prompt back",
     synopsis: [["moshcode herd start <engine> [--name <slug>] [--agent] [args…]", ""]],
     flags: [
@@ -994,6 +1027,8 @@ export const PIT_COMMANDS = [
     description: "sessions that keep running when you leave" },
   { name: "ps", cli: "ps",
     description: "what the herd is running, and which one wants you" },
+  { name: "cost", args: "[name] [--all]", cli: "cost",
+    description: "what the herd is spending, from the engines' own logs" },
   { name: "attach", args: "<name>", cli: "attach",
     description: "step into a herd session (detach leaves it running)" },
   { name: "kill", args: "<name…>", cli: "kill",