moshcode 0.58.0 → 0.59.0

package/src/commands.mjs

@@ -16,11 +16,18 @@
 import { spawn, spawnSync } from "node:child_process";
 
 import { createRegistry } from "./registry.mjs";
-import { cliVerb, aiVerb } from "./cli.mjs";
+import { cliVerb, aiVerb, runMoshcode } from "./cli.mjs";
 import { ingestApproval, pollApproval } from "./notify.mjs";
 import { capture, killSession, sendPrompt } from "./herd.mjs";
 import { herdStart, roster, waitFor } from "./herd-cli.mjs";
 import { shellInvocation } from "./shell.mjs";
+import { identity, loginAuto, logout as forgetCreds } from "./auth.mjs";
+import { expandAlias, getAlias, loadAliases, removeAlias, setAlias } from "./aliases.mjs";
+import { CORE_CLI_COMMAND_NAMES, PIT_COMMANDS } from "./cli-schema.mjs";
+import { fetchAdvisor, stocksArgs } from "./advisor.mjs";
+import { cryptoArgs, fetchCrypto } from "./crypto.mjs";
+import { collectNews, loadListFeeds, readingList } from "./news.mjs";
+import { resolveList } from "./news-sources.mjs";
 
 // The moshcoding pit-anthem playlist. mosh() blasts this URL and, on a desktop
 // with a GUI, tries to open it in the default browser.
@@ -64,6 +71,61 @@ function expectNoArgs(name, args) {
   }
 }
 
+/**
+ * Whether a name already belongs to moshcode, for alias().
+ *
+ * The pit asks the dispatcher this by resolving; a script has no dispatcher, so
+ * it asks the schema instead — the CLI commands and the pit's own verbs, which
+ * is what an alias could collide with. Kept as a predicate (the shape
+ * setAlias() takes) rather than an exported list, so this stays the caller's
+ * answer and not a second roster to drift from the first.
+ */
+function isReserved(name) {
+  const key = String(name).toLowerCase();
+  return CORE_CLI_COMMAND_NAMES.includes(key)
+    || PIT_COMMANDS.some((c) => (typeof c === "string" ? c : c.name) === key);
+}
+
+// The shell verb, named so runAlias() can execute an expanded alias line
+// through exactly the same path a script's own shell() call takes — one
+// invocation, one dry-run story, one { ok, code } contract. It is registered in
+// COMMANDS below like every other verb.
+const SHELL = {
+  name: "shell",
+  summary: "run a shell command (blocking, cmd.exe on Windows or $SHELL elsewhere)",
+  usage: "shell(cmd)",
+  detail: "runs cmd in $SHELL, loading your rc file where it can; returns { ok, code, signal }",
+  // The moshscript system verb for arbitrary shell commands. Blocking
+  // (spawnSync + inherited stdio) so it runs inline in the no-`await` style,
+  // and the child owns the terminal for interactive commands. Returns
+  // { ok, code } so scripts can branch on the exit status:
+  //   const r = shell("npm test"); if (!r.ok) say("tests failed");
+  run(ctx, ...args) {
+    const cmd = args.join(" ");
+    if (!cmd) throw new Error("moshscript: shell() requires a command string");
+    if (ctx.dryRun) {
+      ctx.out(`  ▶ shell(${JSON.stringify(cmd)}) → would run: $SHELL ${shellInvocation(cmd).flags} ${JSON.stringify(cmd)}`);
+      // Same R8 contract as the comment above: `code` is always present, so a
+      // script branching on the exit status behaves the same under --dry-run.
+      return { ok: true, code: 0, dryRun: true };
+    }
+    // Same invocation the pit's own `!cmd` uses, so a command that works when
+    // typed works when scripted: interactive where a terminal is attached, so
+    // the user's rc file — and the aliases in it — are loaded. src/shell.mjs
+    // has the reasoning, including why a headless run stays non-interactive.
+    const { shell: sh, args: shArgs } = shellInvocation(cmd);
+    ctx.out(`  ▶ shell: ${cmd}`);
+    const res = spawnSync(sh, shArgs, { stdio: "inherit" });
+    if (res.error) throw res.error;
+    const code = res.status ?? 1;
+    if (code !== 0) {
+      ctx.out(`  ✗ shell() exited ${res.signal || code}`);
+      return { ok: false, code, signal: res.signal || null };
+    }
+    return { ok: true, code: 0 };
+  },
+};
+
 // The vocabulary, in registration order. mosh() is the worked example of the
 // command shape; the rest follow the same pattern.
 const COMMANDS = [
@@ -189,39 +251,227 @@ const COMMANDS = [
     },
   },
 
+  SHELL,
+
+  // The account. Local rather than cliVerbs for the same reason the herd is:
+  // `moshcode whoami` prints, and a script needs to *branch* on the answer —
+  // "am I logged in?", "whose account is this?", "are there credits left?".
+  // Shelling out returns { ok, code }, so the only way to read the account
+  // would be to re-parse stdout. src/auth.mjs owns the flows either way; these
+  // are a second caller of the same identity(), not a second implementation.
   {
-    name: "shell",
-    summary: "run a shell command (blocking, cmd.exe on Windows or $SHELL elsewhere)",
-    usage: "shell(cmd)",
-    detail: "runs cmd in $SHELL, loading your rc file where it can; returns { ok, code, signal }",
-    // The moshscript system verb for arbitrary shell commands. Blocking
-    // (spawnSync + inherited stdio) so it runs inline in the no-`await` style,
-    // and the child owns the terminal for interactive commands. Returns
-    // { ok, code } so scripts can branch on the exit status:
-    //   const r = shell("npm test"); if (!r.ok) say("tests failed");
+    name: "whoami",
+    summary: "the logged-in account, as a value (verified against app.moshcode.sh)",
+    usage: "whoami()",
+    detail: "returns { status, verified, api, user: { id, email, name, credits } }. needs await",
+    // Never throws — an unreachable app is a `status`, not an exception,
+    // because the caller is usually deciding whether to start work.
+    async run(ctx) {
+      if (ctx.dryRun) {
+        ctx.out("  👤 whoami()  → would check app.moshcode.sh");
+        return { status: "dry_run", verified: false, api: null, user: null, dryRun: true };
+      }
+      const me = await identity();
+      const who = me.user?.email || me.user?.name;
+      ctx.out(me.verified
+        ? `  👤 whoami()  → ${who || "moshcoder"} (${me.user.credits ?? "?"} credits)`
+        : `  👤 whoami()  → ${me.status}${who ? ` (${who}, unverified)` : ""}`);
+      return me;
+    },
+  },
+  {
+    name: "login",
+    summary: "authenticate this machine against app.moshcode.sh",
+    usage: "login({ device, browser, force })",
+    detail: "no-op when already authenticated unless force; returns { ok, email, already }. needs await",
+    // Idempotent by default. A script that opens with login() should be safe to
+    // re-run all day without throwing a browser tab at an operator who is
+    // already signed in — so the verified case returns early. `force` re-runs
+    // the flow anyway (switching accounts), and device/browser pin the flow
+    // rather than letting loginAuto sniff for SSH.
+    async run(ctx, opts = {}) {
+      if (ctx.dryRun) {
+        ctx.out("  🔑 login()   → would authenticate against app.moshcode.sh");
+        return { ok: true, email: null, already: false, dryRun: true };
+      }
+      if (!opts.force) {
+        const me = await identity();
+        if (me.verified) {
+          ctx.out(`  🔑 login()   → already signed in as ${me.user.email || me.user.name || "moshcoder"}`);
+          return { ok: true, email: me.user.email ?? null, already: true };
+        }
+      }
+      try {
+        const r = await loginAuto({ device: Boolean(opts.device), browser: Boolean(opts.browser) });
+        ctx.out(`  🔑 login()   → signed in as ${r.email || "moshcoder"} 🤘`);
+        return { ok: true, email: r.email ?? null, already: false };
+      } catch (e) {
+        // R8: hand back the failure instead of throwing, so a script can fall
+        // back (skip the notify, run read-only) rather than die at line 1.
+        ctx.out(`  ✗ login() failed — ${e.message}`);
+        return { ok: false, email: null, already: false, error: e.message };
+      }
+    },
+  },
+  {
+    name: "requireLogin",
+    summary: "BLOCK until this machine is authenticated — the gate for scripts that need an account",
+    usage: "requireLogin({ device, browser })",
+    detail: "returns the verified { id, email, name, credits }; THROWS if it can't authenticate. needs await",
+    // The one verb here that throws, and on purpose: "require" means the script
+    // must not continue unauthenticated. Everything downstream (notify, ask,
+    // credits) would fail one call at a time and much less legibly, so a script
+    // that needs an account says so once, at the top.
+    async run(ctx, opts = {}) {
+      if (ctx.dryRun) {
+        ctx.out("  🔒 requireLogin() → would require an authenticated account");
+        return { id: null, email: null, name: null, credits: null, dryRun: true };
+      }
+      let me = await identity();
+      if (!me.verified) {
+        ctx.out(`  🔒 requireLogin() → ${me.status} — starting the login flow…`);
+        try { await loginAuto({ device: Boolean(opts.device), browser: Boolean(opts.browser) }); }
+        catch (e) { throw new Error(`moshscript: requireLogin() could not authenticate — ${e.message}`); }
+        me = await identity();
+      }
+      if (!me.verified) {
+        throw new Error(`moshscript: requireLogin() could not authenticate (${me.status}) — run \`moshcode login\``);
+      }
+      ctx.out(`  🔒 requireLogin() → ${me.user.email || me.user.name || "moshcoder"} 🤘`);
+      return me.user;
+    },
+  },
+  {
+    name: "logout",
+    summary: "forget this machine's credentials",
+    usage: "logout()",
+    detail: "returns { ok }",
     run(ctx, ...args) {
-      const cmd = args.join(" ");
-      if (!cmd) throw new Error("moshscript: shell() requires a command string");
+      expectNoArgs("logout", args);
+      if (ctx.dryRun) { ctx.out("  🚪 logout()  → would forget the local credentials"); return { ok: true, dryRun: true }; }
+      forgetCreds();
+      return { ok: true };
+    },
+  },
+
+  // Aliases. The pit already keeps named shortcuts (src/aliases.mjs) and they
+  // are the operator's own vocabulary — the things *they* retype. A script that
+  // cannot reach them has to re-spell every one of those lines, so the same
+  // store is readable and writable here, and runAlias() executes one.
+  {
+    name: "alias",
+    summary: "read, list, or define pit aliases",
+    usage: 'alias() | alias(name) | alias(name, line)',
+    detail: "no args → the whole map; one arg → that line or null; two → defines it, returns { ok, name, value, previous }",
+    run(ctx, name, value) {
+      if (name === undefined) return loadAliases();
+      if (value === undefined) return getAlias(String(name));
       if (ctx.dryRun) {
-        ctx.out(`  ▶ shell(${JSON.stringify(cmd)}) → would run: $SHELL ${shellInvocation(cmd).flags} ${JSON.stringify(cmd)}`);
-        // Same R8 contract as the comment above: `code` is always present, so a
-        // script branching on the exit status behaves the same under --dry-run.
-        return { ok: true, code: 0, dryRun: true };
+        ctx.out(`  🔖 alias(${name}) → would define: ${value}`);
+        return { ok: true, name: String(name), value: String(value), previous: null, dryRun: true };
+      }
+      // Same reservation rule the pit enforces: a shortcut that collides with a
+      // built-in would be silently dead, so it is refused rather than shadowed.
+      const r = setAlias(name, value, { isReserved });
+      ctx.out(r.ok ? `  🔖 alias(${r.name}) → ${r.value}` : `  ✗ alias() — ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "unalias",
+    summary: "forget a pit alias",
+    usage: "unalias(name)",
+    detail: "returns { ok, name, value } — { ok: false } when there was no such alias",
+    run(ctx, name) {
+      if (!name) throw new Error("moshscript: unalias(name) requires an alias name");
+      if (ctx.dryRun) { ctx.out(`  🔖 unalias(${name}) → would forget it`); return { ok: true, name: String(name), dryRun: true }; }
+      const r = removeAlias(name);
+      ctx.out(r.ok ? `  🔖 unalias(${r.name})` : `  ✗ unalias() — ${r.error}`);
+      return r;
+    },
+  },
+  {
+    name: "runAlias",
+    summary: "run a pit alias by name, with extra arguments appended",
+    usage: "runAlias(name, ...args)",
+    detail: "returns { ok, code } like shell()/CLI verbs; { ok: false, code: 127 } when undefined",
+    // The expansion rule is the pit's (src/aliases.mjs): a leading `/` is a pit
+    // command, anything else is a shell line, and typed arguments are appended
+    // rather than substituted. A pit command routes to its CLI twin here —
+    // moshscript is not the pit, but `/agents claude` and `moshcode agents
+    // claude` are the same capability, which is the whole cliVerb premise.
+    run(ctx, name, ...args) {
+      if (!name) throw new Error("moshscript: runAlias(name) requires an alias name");
+      const value = getAlias(String(name));
+      if (value == null) {
+        ctx.out(`  ✗ runAlias(${name}) — no alias named "${name}"`);
+        return { ok: false, code: 127 };
       }
-      // Same invocation the pit's own `!cmd` uses, so a command that works when
-      // typed works when scripted: interactive where a terminal is attached, so
-      // the user's rc file — and the aliases in it — are loaded. src/shell.mjs
-      // has the reasoning, including why a headless run stays non-interactive.
-      const { shell: sh, args: shArgs } = shellInvocation(cmd);
-      ctx.out(`  ▶ shell: ${cmd}`);
-      const res = spawnSync(sh, shArgs, { stdio: "inherit" });
-      if (res.error) throw res.error;
-      const code = res.status ?? 1;
-      if (code !== 0) {
-        ctx.out(`  ✗ shell() exited ${res.signal || code}`);
-        return { ok: false, code, signal: res.signal || null };
+      const line = expandAlias(value, args.map(String).join(" "));
+      if (line.startsWith("/")) {
+        const [verb, ...rest] = line.slice(1).split(/\s+/).filter(Boolean);
+        return runMoshcode(verb, rest, ctx);
+      }
+      return SHELL.run(ctx, line.replace(/^!/, ""));
+    },
+  },
+
+  // Reading the tools, not just running them. `stocks report NVDA` prints a
+  // table; a script wants the score. These call the same advis0r/feed layer the
+  // CLI renders from, so a verb here can never drift from its printed twin.
+  {
+    name: "stocksRead",
+    summary: "run a stocks query and RETURN its JSON (advis0r)",
+    usage: 'stocksRead("report", "NVDA")',
+    detail: "same arguments as stocks(); returns the parsed data, or null on error. needs await",
+    async run(ctx, ...args) {
+      const request = stocksArgs(args.map(String));
+      if (request.error) throw new Error(`moshscript: stocksRead() — ${request.error}`);
+      if (ctx.dryRun) { ctx.out(`  📈 stocksRead(${args.join(" ")}) → would query advis0r`); return null; }
+      ctx.out(`  📈 stocksRead(${args.join(" ")})`);
+      const res = await fetchAdvisor(request);
+      if (!res.ok) { ctx.out(`     ! ${res.error || `advis0r returned ${res.status}`}`); return null; }
+      return res.data;
+    },
+  },
+  {
+    name: "cryptoRead",
+    summary: "run a crypto query and RETURN its JSON (advis0r)",
+    usage: 'cryptoRead("report", "BTC/USD")',
+    detail: "same arguments as crypto(); returns the parsed data, or null on error. needs await",
+    async run(ctx, ...args) {
+      const request = cryptoArgs(args.map(String));
+      if (request.error) throw new Error(`moshscript: cryptoRead() — ${request.error}`);
+      if (ctx.dryRun) { ctx.out(`  🪙 cryptoRead(${args.join(" ")}) → would query advis0r`); return null; }
+      ctx.out(`  🪙 cryptoRead(${args.join(" ")})`);
+      const res = await fetchCrypto(request);
+      if (!res.ok) { ctx.out(`     ! ${res.error || `advis0r returned ${res.status}`}`); return null; }
+      return res.data;
+    },
+  },
+  {
+    name: "newsRead",
+    summary: "fetch the news feeds and RETURN the headlines",
+    usage: 'newsRead({ list, limit })',
+    detail: "returns [{ title, link, source, date }, …] — your subscriptions, or a named list. needs await",
+    // `list` names one of the built-in feed lists; omit it for the operator's
+    // own subscriptions (the same reading list `/news` shows).
+    async run(ctx, opts = {}) {
+      const limit = Number(opts.limit) || 20;
+      if (ctx.dryRun) { ctx.out(`  📰 newsRead() → would fetch ${opts.list || "your"} feeds`); return []; }
+      let feeds;
+      if (opts.list) {
+        const list = resolveList(String(opts.list));
+        if (!list) throw new Error(`moshscript: newsRead() — no feed list named "${opts.list}"`);
+        const loaded = await loadListFeeds(list);
+        if (!loaded.ok) { ctx.out(`     ! couldn't load ${opts.list}`); return []; }
+        feeds = loaded.feeds;
+      } else {
+        feeds = readingList().feeds;
       }
-      return { ok: true, code: 0 };
+      ctx.out(`  📰 newsRead() → reading ${feeds.length} feed(s)…`);
+      const { items } = await collectNews(feeds);
+      return items.slice(0, limit).map(({ title, link, source, date }) => ({ title, link, source, date }));
     },
   },
 
@@ -334,6 +584,7 @@ const COMMANDS = [
   cliVerb("agents", "launch an autonomous agent session (moshcode agents <engine>)"),
   cliVerb("herd", "drive the herd (moshcode herd <verb>) — see herdStart/herdWait for values"),
   cliVerb("ps", "print the herd roster"),
+  cliVerb("cost", "print what the herd is spending (moshcode cost [name] [--all])"),
   cliVerb("start", "raw-launch an engine (moshcode start <engine>)"),
   cliVerb("install", "install an engine or workflow tool"),
   cliVerb("upgrade", "upgrade moshcode, engines, and tools"),
@@ -357,6 +608,31 @@ const COMMANDS = [
   cliVerb("mcpjam", "drive the MCPJam CLI (test, debug, and validate MCP servers)"),
   cliVerb("trade", "look up tickers, inspect markets, and preview/place Alpaca orders"),
   cliVerb("pwd", "print the current repo/location"),
+
+  // Research and feeds. The *Read() verbs above return the data; these are the
+  // rendered CLI, for when a script wants the table on the operator's screen.
+  cliVerb("stocks", "research tickers via advis0r (report, discover, signals, research)"),
+  cliVerb("crypto", "research crypto pairs via advis0r (quote, report, bars, book)"),
+  cliVerb("advisor", "query advis0r directly"),
+  cliVerb("news", "read, search, and subscribe to news feeds"),
+  cliVerb("rss", "manage RSS subscriptions and reading lists"),
+
+  // Extending moshcode from a script — the same fan-out `mcp`/`skill` do.
+  cliVerb("plugin", "install/manage moshcode plugins from the marketplace"),
+  cliVerb("engines", "list coding engines and whether they're installed"),
+  cliVerb("tools", "list the adjacent workflow CLIs and whether they're installed"),
+
+  // Hosting: the Moshpit side of the CLI, so a deploy script can claim a name,
+  // serve a site, and bring the resolver up without dropping to $SHELL.
+  cliVerb("dns", "drive the Moshpit DNS bridge (enable, status, resolve)"),
+  cliVerb("doh", "run/inspect the DNS-over-HTTPS endpoint"),
+  cliVerb("site", "scaffold and publish a site"),
+  cliVerb("serve", "serve a directory over HTTP"),
+  cliVerb("template", "scaffold from a moshcode template"),
+
+  // Settings sync (PRD 0010) — needs an account, so pair with requireLogin().
+  cliVerb("save", "push local settings to your moshcode account"),
+  cliVerb("load", "pull settings from your moshcode account"),
 ];
 
 /** A fresh registry preloaded with the built-in vocabulary. */

package/src/cost-cli.mjs

@@ -0,0 +1,232 @@
+// `moshcode cost` — what the herd is spending, right now.
+//
+// The roster answers "which agent is blocked". This answers the other question
+// you have at 2am with six agents running: "what is this costing me". Same
+// shape as `moshcode ps` on purpose — one row per session, one line of totals —
+// because it is the same list of sessions seen through a different column.
+//
+// Everything it prints comes from the engines' own session logs (src/cost.mjs).
+// Nothing is sampled, nothing is proxied, and a number the engine itself
+// computed is never overwritten by our arithmetic.
+import {
+  DEFAULT_WINDOW_MS, UNCOSTED_ENGINES, attributeRuns, engineRuns,
+  formatTokens, formatUsd, totals,
+} from "./cost.mjs";
+import { pricingFile } from "./cost-pricing.mjs";
+import { EXIT, humanAge, roster } from "./herd-cli.mjs";
+import { acid, ash, bone, dim, err, info, table, warn } from "./ui.mjs";
+
+const tilde = (p) => {
+  const home = process.env.HOME || "";
+  return home && p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+};
+
+/** "30m", "6h", "3d", "90s" — the same vocabulary `moshcode wait --timeout` takes. */
+export function parseWindow(raw, fallback = DEFAULT_WINDOW_MS) {
+  const m = /^(\d+(?:\.\d+)?)\s*([smhd])?$/.exec(String(raw ?? "").trim());
+  if (!m) return fallback;
+  const n = Number(m[1]);
+  if (!Number.isFinite(n) || n <= 0) return fallback;
+  return n * { s: 1e3, m: 60e3, h: 3600e3, d: 86400e3 }[m[2] || "h"];
+}
+
+function flagValue(argv, name) {
+  const i = argv.indexOf(name);
+  if (i === -1) return null;
+  const next = argv[i + 1];
+  return next && !next.startsWith("-") ? next : null;
+}
+
+/**
+ * How confident the dollar figure is, in one character.
+ *
+ * `~` means we multiplied tokens by a published rate card; no marker means the
+ * engine handed us the price. On a subscription the estimate is what the same
+ * work would cost on the API — worth watching, not worth invoicing.
+ */
+function costCell(cost, source) {
+  if (cost == null) return ash("—");
+  const text = formatUsd(cost);
+  if (source === "engine") return bone(text);
+  return `${bone(text)}${dim("~")}`;
+}
+
+/**
+ * Cache tokens get their own column rather than folding into `in`.
+ *
+ * On a long agent session they are most of the traffic and a tenth of the price
+ * — a single "in" number that mixes them makes a $3 session look like a $60
+ * one, and hides the thing you would actually act on.
+ */
+const cacheTokens = (u) => u.cacheRead + u.cacheWrite5m + u.cacheWrite1h;
+
+/** The per-session table, shared by the one-shot report and `--watch`. */
+export function renderCost(rows, { indent = "  " } = {}) {
+  if (!rows.length) return "";
+  return table(
+    rows.map((r) => [
+      bone(r.name),
+      ash(String(r.engine)),
+      ash(r.models?.length ? r.models.join(",") : "—"),
+      dim(formatTokens(r.usage.input)),
+      dim(formatTokens(r.usage.output)),
+      dim(formatTokens(cacheTokens(r.usage))),
+      costCell(r.cost, r.costSource),
+      dim(humanAge(r.age)),
+    ]),
+    { columns: ["session", "engine", "model", "in", "out", "cache", "cost", "age"], header: true, indent: indent.length },
+  );
+}
+
+/** The `--all` table: engine sessions as the engines recorded them. */
+function renderRuns(runs, { indent = "  " } = {}) {
+  if (!runs.length) return "";
+  return table(
+    runs.map((r) => [
+      bone(String(r.id).slice(0, 8)),
+      ash(r.engine),
+      ash(r.models?.length ? r.models.join(",") : "—"),
+      ash(tilde(r.cwd || "")),
+      dim(formatTokens(r.usage.input)),
+      dim(formatTokens(r.usage.output)),
+      dim(formatTokens(cacheTokens(r.usage))),
+      costCell(r.cost, r.costSource),
+    ]),
+    { columns: ["run", "engine", "model", "cwd", "in", "out", "cache", "cost"], header: true, indent: indent.length },
+  );
+}
+
+/**
+ * Gather everything once: the roster, the engine runs in the window, and the
+ * attribution between them. Returned whole so `--json`, the table, and the
+ * herd bar all read the same numbers.
+ */
+export async function costReport({ since, cwd = null, engines = null } = {}) {
+  const sessions = roster();
+  const runs = await engineRuns({ since, cwd, engines });
+  const { rows, unattributed } = attributeRuns(sessions, runs);
+  return { sessions, runs, rows, unattributed, since };
+}
+
+/**
+ * The total is the total of the table above it, and anything the table left out
+ * is its own line. A single grand total over rows that are not all shown reads
+ * as "your herd cost $850" when the herd cost nothing and another terminal did.
+ */
+function footer(report, write, { attribution = true } = {}) {
+  const shown = totals(report.rows);
+  const loose = totals(report.unattributed);
+  const all = totals([...report.rows, ...report.unattributed]);
+
+  write("");
+  write(`  ${bone("total")}  ${costCell(shown.cost, "rates")}  ${dim(`${formatTokens(shown.usage.input)} in · ${formatTokens(shown.usage.output)} out · ${formatTokens(cacheTokens(shown.usage))} cached`)}`);
+  if (attribution && report.unattributed.length) {
+    write(info(`plus ${formatUsd(loose.cost)} in ${report.unattributed.length} engine session(s) outside the herd — ${acid("moshcode cost --all")} shows them.`));
+  }
+  if (shown.cost != null || loose.cost != null) {
+    write(dim(`  ~ estimated from published rates; unmarked figures are the engine's own.`));
+  }
+  if (all.unpriced.length) {
+    write(warn(`no rate for ${all.unpriced.join(", ")} — tokens counted, cost omitted.`));
+    write(info(`price them in ${tilde(pricingFile())}: { "${all.unpriced[0]}": { "input": 1.25, "output": 10 } }`));
+  }
+}
+
+/**
+ * `moshcode cost [name] [--all] [--since 6h] [--engine <name>] [--json] [--watch [secs]]`
+ */
+export async function costCommand(argv = [], { write = console.log } = {}) {
+  const asJson = argv.includes("--json");
+  const all = argv.includes("--all");
+  const since = Date.now() - parseWindow(flagValue(argv, "--since"));
+  const engineFlag = flagValue(argv, "--engine");
+  const engines = engineFlag ? engineFlag.split(",").map((s) => s.trim()).filter(Boolean) : null;
+  const watch = argv.includes("--watch");
+  const flagWords = new Set([flagValue(argv, "--since"), flagValue(argv, "--engine"), flagValue(argv, "--watch")]);
+  const name = argv.find((a) => !a.startsWith("-") && !flagWords.has(a)) || null;
+
+  if (watch && asJson) {
+    write(err("--watch and --json do not go together — pipe repeated `moshcode cost --json` instead."));
+    return EXIT.usage;
+  }
+
+  const once = async () => {
+    const report = await costReport({ since, engines });
+    let rows = report.rows;
+    if (name) {
+      rows = rows.filter((r) => r.name === name);
+      if (!rows.length) {
+        write(err(`no session named ${JSON.stringify(name)} — ${acid("moshcode ps")}`));
+        return EXIT.gone;
+      }
+    }
+
+    if (asJson) {
+      write(JSON.stringify({
+        since,
+        sessions: rows.map(({ name: n, engine, cwd, state, models, usage, cost, costSource, unpriced, runs }) => ({
+          name: n, engine, cwd, state, models, usage, cost, costSource, unpriced,
+          runs: runs.map((r) => ({ id: r.id, model: r.model, usage: r.usage, cost: r.cost, costSource: r.costSource, start: r.start, end: r.end })),
+        })),
+        unattributed: report.unattributed.map((r) => ({
+          id: r.id, engine: r.engine, cwd: r.cwd, model: r.model, usage: r.usage, cost: r.cost, costSource: r.costSource, start: r.start, end: r.end,
+        })),
+        totals: totals([...rows, ...report.unattributed]),
+      }, null, 2));
+      return EXIT.matched;
+    }
+
+    if (all) {
+      const runs = name ? rows.flatMap((r) => r.runs) : report.runs;
+      if (!runs.length) {
+        write(info("no engine sessions on disk in this window — widen it with `--since 7d`."));
+        return EXIT.matched;
+      }
+      write(renderRuns(runs));
+      // The runs ARE the rows here, so they are what the total totals. And the
+      // "not tied to a herd session" note would be describing the whole table
+      // back at itself, so it stays off.
+      footer({ ...report, rows: runs, unattributed: [] }, write, { attribution: false });
+      return EXIT.matched;
+    }
+
+    if (!rows.length) {
+      write(info("the herd is empty — `moshcode herd start claude` puts something in it."));
+      write(info(`already ran an agent outside the herd? ${acid("moshcode cost --all")}`));
+      return EXIT.matched;
+    }
+
+    write(renderCost(rows));
+    footer({ ...report, rows }, write);
+    if (UNCOSTED_ENGINES.some((e) => rows.some((r) => r.engine === e))) {
+      write(info(`${UNCOSTED_ENGINES.join(", ")} keep no usage log moshcode can read — those rows show no cost, not zero cost.`));
+    }
+    return EXIT.matched;
+  };
+
+  if (!watch) return once();
+
+  // --watch is the "ongoing" part: the same report, re-read on an interval,
+  // because the interesting thing about a running agent's cost is the slope.
+  const every = Math.max(2, Number(flagValue(argv, "--watch") || 10)) * 1000;
+  let stop = false;
+  const onSigint = () => { stop = true; };
+  process.on("SIGINT", onSigint);
+  try {
+    while (!stop) {
+      if (process.stdout.isTTY) process.stdout.write("\x1b[2J\x1b[H");
+      await once();
+      write(dim(`  refreshing every ${Math.round(every / 1000)}s · ctrl-c to stop`));
+      await new Promise((resolve) => {
+        const timer = setTimeout(resolve, every);
+        // A timer must not hold the process open past a ctrl-c.
+        timer.unref?.();
+        const poll = setInterval(() => { if (stop) { clearTimeout(timer); clearInterval(poll); resolve(); } }, 100);
+        poll.unref?.();
+      });
+    }
+  } finally {
+    process.off("SIGINT", onSigint);
+  }
+  return EXIT.matched;
+}