@100xprompt/brain 0.1.0 → 0.1.1

package/README.md

@@ -87,7 +87,7 @@ you sign in to 100xprompt and confirm, and the key comes back to brain by itself
 ```bash
 brain gateway login                              # sign in in the browser
 brain gateway connect --tool codex --dry-run     # show what would change
-brain gateway connect --tool codex               # Claude Code, Codex, OpenCode, Gemini CLI (signs in first if needed)
+brain gateway connect --tool codex               # any tool in the table below (signs in first if needed)
 brain gateway status
 brain gateway disconnect --tool codex            # put back exactly what was there
 brain gateway logout
@@ -103,8 +103,70 @@ brain gateway logout
 - On a machine without a browser (SSH): `brain gateway login --no-browser` prints the address. Open it anywhere, then
   paste the key from the page's Copy key button (input is hidden). For scripts and CI: `--key-env VAR`. To reuse the
   100xprompt CLI's sign-in: `--from-cli`.
-- Each sign-in makes a new key on your account. Signing in again also updates the copy Codex and Gemini CLI keep in their
-  own config.
+- Each sign-in makes a new key on your account. Signing in again also updates every copy of the key that a connected tool
+  keeps in its own config.
+
+| Tool (`--tool`) | How it gets the key | Context editing | Checked with the real tool |
+|---|---|---|---|
+| Claude Code (`claude-code`) | reads brain's key file at start | yes | yes |
+| Codex (`codex`) | copy in its config, made private | yes | yes |
+| OpenCode (`opencode`) | reads brain's key file | yes | yes |
+| Gemini CLI (`gemini-cli`) | copy in `~/.gemini/.env`, private | no | yes (needs the gateway update that accepts `x-goog-api-key`) |
+| Aider (`aider`) | copy in its model settings, private | yes | yes |
+| Cline CLI (`cline-sdk`) | copy in its providers file, private | yes | yes |
+| Continue (`continue`) | copy in `~/.continue/.env`, private | yes | yes (`cn`) |
+| Copilot CLI (`copilot-cli`) | copy in its providers file, private | yes | yes |
+| Copilot Chat in VS Code (`vscode-copilot`) | copy in VS Code's model list, private | yes | from the extension's code; pick "100xprompt Pro" once in the model picker |
+| Crush (`crush`) | reads brain's key file | yes | yes |
+| Factory Droid (`factory-droid`) | reads brain's key file | yes | yes |
+| Goose (`goose`) | reads brain's key file | yes | yes |
+| Grok CLI (`grok-cli`) | copy in its config, private | yes | yes |
+| Hermes Agent (`hermes`) | copy in `~/.hermes/.env`, private | yes | yes |
+| iFlow CLI (`iflow-cli`) | copy in its settings, private | no | yes |
+| Kilo CLI and Kilo Code (`kilo-cli`, `kilo-code`) | reads brain's key file | yes | yes |
+| Kimi Code (`kimi-code`) | copy in its config, private | yes | yes |
+| Letta Code (`letta-code`) | reads brain's key file (a provider mod; local agents only) | yes | from its source |
+| Mastra Code (`mastracode`) | copy in its settings, private | no | from its source |
+| Mistral Vibe (`mistral-vibe`) | copy in `~/.vibe/.env`, private | yes | yes |
+| Oh My Pi (`omp`) | reads brain's key file | yes | from its source |
+| OpenHands (`openhands`) | copy in its settings, private | yes | yes |
+| PearAI (`pearai`) | copy in `~/.pearai/.env`, private | yes | from its source |
+| Pi (`pi`) | reads brain's key file | yes | yes |
+| Qwen Code (`qwen-code`) | copy in `~/.qwen/.env`, private | yes | yes |
+
+"Checked with the real tool" means the real program, pointed at a local stand-in gateway, sent its request to the gateway's
+route with the key and the gateway's model, and `disconnect` gave every file back byte for byte (its original mode too).
+
+Some tools cannot be pointed at the gateway from a file brain can safely write and cleanly undo, so they have no connector:
+Cursor and the Cursor CLI, Windsurf, Antigravity, Amazon Q, Kiro, Auggie, Tabnine, Devin and Muse Code (their vendor's own
+servers only); Zed (the key only in the keychain or its launch environment); Void (settings encrypted in the app's state);
+Roo Code and the Cline extension (they keep the key in the editor's own storage, so disconnect could not take it back);
+Codebuff and Qoder (custom endpoints only through their own sign-in or the keychain). The reason and its source are in each
+tool's file under `src/gateway/connectors/`.
+
+Gemini CLI loads only the first `.env` it finds from the project folder up: in a project with its own `.env`, put the
+gateway lines there or export them. Letta Code uses the gateway for its local agents only (cloud agents call models from
+Letta's servers). Tools that read brain's key file stop working after `logout` until the next `login`; Kilo refuses to start
+without it.
+
+## Dashboard
+
+Signed in to the gateway, brain sends a short report of this machine to your 100xprompt account, shown in the console's
+Brain view (https://100xprompt.com/dashboard?view=brain): the coding tools found here, their session counts, which are
+connected to the gateway or have brain's MCP tools and hooks, your gateway settings, memory counts, and every chat brain
+moved from one tool into another (when, from and to which tool, the way, its title and its project folder's name). Never
+chat text, file contents, full paths or keys.
+
+```bash
+brain dashboard              # count sessions, send the report now, open the Brain view (--no-open prints the address)
+brain dashboard status       # on or off, and when the last report went out
+brain dashboard off          # send nothing from this machine (brain dashboard on to start again)
+```
+
+The report goes out in the background, at most every 30 seconds, after a command that changes it (`gateway login`,
+`connect`, `disconnect`, `session continue`, `handoff`, `mcp install`/`uninstall`, `session hooks install`/`uninstall`),
+and never makes that command wait or fail. The first time, brain prints what it sends and how to stop it.
+`BRAIN_NO_REPORT=1` also turns it off. The conversion log is `~/.brain/logs/conversions.jsonl`, readable only by you.
 
 ## Teams
 
@@ -146,6 +208,7 @@ brain memory ingest | search | status | forget | sync
 brain mcp serve | install | uninstall | status
 brain tokens audit | lookups
 brain gateway login | logout | connect | disconnect | status | tools
+brain dashboard [push | on | off | status]
 brain org login | logout | whoami | status | promote | demote | forget | admin ...
 brain expand <id>
 brain --version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@100xprompt/brain",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "One working session, any AI coding tool: move sessions between Claude Code, Codex, Cursor, Gemini CLI, OpenCode and more, keep what projects learned, spend fewer tokens. Runs on Bun. By 100xprompt.",
   "license": "MIT",
   "author": "Nipurn Agarwal",

package/src/cli.ts

@@ -8,7 +8,7 @@ import { gitInfo, homeDir } from "./fsutil.ts"
 import { secureSelf } from "./self.ts"
 import { HOOK_TOOLS, installHooks, runHook, uninstallHooks } from "./hooks.ts"
 import type { Session } from "./session/types.ts"
-import { prepare } from "./memory/prepare.ts"
+import { prepare, sessionTokens } from "./memory/prepare.ts"
 import { countTurns, firstUserText, toJsonl, unpaired } from "./session/util.ts"
 
 // brain session: one working session, any AI coding tool.
@@ -40,6 +40,7 @@ brain org login --server <url> --token <t> | logout | whoami | status | promote|
 brain org admin init|serve|user|token|team|project|policy|audit|retention   shared memory for an organisation (roles, scopes, audit)
 brain mcp serve | install | uninstall | status [--tool <id>]   the brain_recall / brain_expand tools for your AI tools
 brain gateway login [--no-browser] | logout | connect --tool <id> | disconnect --tool <id> | status | tools   sign in to 100xprompt and route a coding tool through its gateway (and back)
+brain dashboard [push|on|off|status] [--quiet] [--no-open]   send this machine's report (tools, gateway, conversions; never chat text) to your 100xprompt account and open its Brain view
 brain --version                                    the version, and where this brain runs from
 brain expand <blob id>                              the full text of a tool output that was replaced by a digest`
 
@@ -55,6 +56,13 @@ const fail = (s: string): never => {
   process.stderr.write(`brain: ${s}\n`)
   process.exit(1)
 }
+/** After a command that changes what the dashboard report says: a report in a detached process (src/dashboard/send.ts). */
+async function reportLater() {
+  try {
+    const { reportInBackground } = await import("./dashboard/send.ts")
+    reportInBackground(home)
+  } catch {}
+}
 
 async function allRefs(tool?: string): Promise<{ refs: SessionRef[]; errors: string[] }> {
   const { READERS } = await adapters()
@@ -160,6 +168,13 @@ async function continueIn(source: Session, target: string, opts: { way?: Way; cw
     for (const s of skipped) out(`(${s}; using the next way)`)
     const r = await w.write(session, wopts)
     report(r)
+    if (!r.dryRun) {
+      // The dashboard's conversion log: tools, way, title, project folder name and sizes; never the chat (src/dashboard/conversions.ts).
+      const { logConversion } = await import("./dashboard/conversions.ts")
+      const { readerFor } = await adapters()
+      const to = r.tool === "cursor" ? "cursor-ide" : r.tool
+      logConversion(home, { from: source.header.tool, fromLabel: readerFor(source.header.tool)?.label ?? toolLabel(source.header.tool), to: r.tool, toLabel: readerFor(to)?.label ?? w.label, way: r.way, title: source.header.title, cwd: source.header.project.cwd ?? cwd, turns: source.turns.length, tokens: sessionTokens(session), lean: prepared.lean })
+    }
     if (!r.dryRun && r.way === "brief") {
       const brief = Bun.file(r.written[0]!)
       // The clipboard where the system has one (pbcopy on macOS, wl-copy or xclip on Linux, clip on Windows); a missing tool is fine.
@@ -171,6 +186,7 @@ async function continueIn(source: Session, target: string, opts: { way?: Way; cw
       if (copied) out("  (the brief is also on the clipboard)")
     }
     if (!r.dryRun && opts.open && target === "cursor") Bun.spawnSync(["/bin/sh", "-c", r.open])
+    if (!r.dryRun) await reportLater()
     return
   }
   fail(`no way to continue in "${target}" right now: ${skipped.join("; ")}`)
@@ -199,11 +215,19 @@ async function main() {
   // Commands with their own flags: `mcp serve` must keep stdout clean for the protocol, so they run before option parsing.
   if (cmd === "gateway") {
     const { gatewayCommand } = await import("./gateway/connect.ts")
-    process.exit(await gatewayCommand(rest, home))
+    const code = await gatewayCommand(rest, home)
+    if (code === 0 && ["login", "logout", "connect", "disconnect"].includes(rest[0] ?? "") && !rest.includes("--dry-run")) await reportLater()
+    process.exit(code)
   }
   if (cmd === "mcp") {
     const { mcpCommand } = await import("./memory/mcp-install.ts")
-    process.exit(await mcpCommand(rest, home))
+    const code = await mcpCommand(rest, home)
+    if (code === 0 && ["install", "uninstall"].includes(rest[0] ?? "") && !rest.includes("--dry-run")) await reportLater()
+    process.exit(code)
+  }
+  if (cmd === "dashboard") {
+    const { dashboardCommand } = await import("./dashboard/cli.ts")
+    process.exit(await dashboardCommand(rest, home))
   }
   if (cmd === "memory" && rest[0] === "sync") {
     const { syncMemory } = await import("./memory/sync.ts")
@@ -311,6 +335,7 @@ async function main() {
       : fail(`hooks ${action}? use install, uninstall or status`)
     for (const c of changes) out(`${c.tool.padEnd(14)} ${c.action}${c.why ? ` (${c.why})` : ""}  ${short(c.path)}`)
     if (!changes.length) out("no tools with session-start hooks found")
+    if ((action === "install" || action === "uninstall") && !values["dry-run"]) await reportLater()
     return
   }
   if (sub === "hook") {

package/src/dashboard/cli.ts

@@ -0,0 +1,148 @@
+// `brain dashboard [push|on|off|status] [--quiet] [--no-open]`: this machine's report for the Brain view of the 100xprompt
+// console (https://100xprompt.com/dashboard?view=brain). The dashboard is on the website only; brain sends the report
+// (report.ts, send.ts) and opens the page.
+import type { Reader } from "../adapters/types.ts"
+import type { Env } from "../gateway/common.ts"
+import { openInBrowser } from "../gateway/signin.ts"
+import { readConversions } from "./conversions.ts"
+import { DASHBOARD_URL, gatewayUrl, noticeOnce, reportUrl, sendingOff, sendReport, signedIn, startScheduled } from "./send.ts"
+import type { BrainReport } from "./report.ts"
+import { readCache, readSettings, updateSettings } from "./state.ts"
+
+const USAGE = [
+  "brain dashboard [--no-open]     count this machine's sessions, send its report to your 100xprompt account now, and open the Brain view",
+  "brain dashboard push [--quiet]  send the report now, without counting sessions (the last counts are reused)",
+  "brain dashboard off | on        stop or start sending reports from this machine (kept in ~/.brain/dashboard.json)",
+  "brain dashboard status          whether reports are sent, and when the last one went out",
+]
+
+const FLAGS = new Set(["--quiet", "--no-open", "--at", "--help", "-h"])
+
+function ago(iso: string | undefined, now = Date.now()): string {
+  const t = iso ? Date.parse(iso) : NaN
+  if (!Number.isFinite(t)) return ""
+  const m = Math.max(0, Math.round((now - t) / 60_000))
+  return m < 1 ? "just now" : m < 60 ? `${m}m ago` : m < 48 * 60 ? `${Math.round(m / 60)}h ago` : `${Math.round(m / 1440)}d ago`
+}
+
+const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`
+
+/** One line on what a report holds. */
+export function summary(r: BrainReport): string {
+  const counted = r.harnesses.filter((h) => h.sessions !== null)
+  const sessions = counted.reduce((n, h) => n + (h.sessions ?? 0), 0)
+  const connected = r.harnesses.filter((h) => h.gateway === "connected").length
+  return `${plural(r.harnesses.length, "tool")} (${connected} connected to the gateway)${counted.length ? `, ${plural(sessions, "session")}` : ""}, ${plural(r.totals.conversions, "conversion")}`
+}
+
+export async function dashboardCommand(
+  args: string[],
+  home: string,
+  io: { out(l: string): void; err(l: string): void } = { out: (l) => process.stdout.write(`${l}\n`), err: (l) => process.stderr.write(`${l}\n`) },
+  deps: { env?: Env; fetchImpl?: typeof fetch; open?: (url: string) => void; countTimeoutMs?: number; readers?: Reader[] } = {},
+): Promise<number> {
+  const env = deps.env ?? process.env
+  const atAt = args.indexOf("--at")
+  const words = args.filter((a, i) => !a.startsWith("-") && !(atAt >= 0 && i === atAt + 1))
+  const sub = words[0]
+  const quiet = args.includes("--quiet")
+  const say = (l: string) => {
+    if (!quiet) io.out(l)
+  }
+  const unknown = args.find((a) => a.startsWith("-") && !FLAGS.has(a))
+  if (args.includes("--help") || args.includes("-h") || sub === "help") {
+    USAGE.forEach((l) => io.out(l))
+    return 0
+  }
+  if (unknown || words.length > 1) {
+    io.out(unknown ? `unknown option ${unknown}` : `unexpected "${words[1]}"`)
+    USAGE.forEach((l) => io.out(`usage: ${l}`))
+    return 2
+  }
+  const notSignedIn = "not signed in to the gateway: run `brain gateway login` first, then `brain dashboard`"
+  const send = async (counts: boolean): Promise<void> => {
+    // The notice goes where the person reads it: the output, or stderr when the output is asked to stay quiet.
+    noticeOnce(home, quiet ? io.err : io.out)
+    const { buildReport, countAndKeep } = await import("./report.ts")
+    const report = await buildReport(home, {
+      env,
+      ...(counts ? { counts: await countAndKeep(home, { timeoutMs: deps.countTimeoutMs ?? 20_000, ...(deps.readers ? { readers: deps.readers } : {}) }) } : {}),
+    })
+    const r = await sendReport(home, report, deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {})
+    say(r.ok ? `sent this machine's report to ${gatewayUrl(home)}: ${summary(report)}` : `could not send the report: ${r.why}; the dashboard keeps the last report it got`)
+  }
+
+  switch (sub) {
+    case undefined: {
+      if (!signedIn(home)) {
+        io.out(notSignedIn)
+        return 1
+      }
+      const off = sendingOff(home, env)
+      if (off) say(`reports are off (${off}): nothing was sent${readSettings(home).off ? "; `brain dashboard on` starts them again" : ""}`)
+      else await send(true)
+      if (args.includes("--no-open")) say(`the dashboard: ${DASHBOARD_URL}`)
+      else {
+        ;(deps.open ?? openInBrowser)(DASHBOARD_URL)
+        say(`opening ${DASHBOARD_URL}`)
+      }
+      return 0
+    }
+    case "push": {
+      // `--at <ms>`: a background push started by another command waits for its turn (send.ts), then reads the state.
+      const at = atAt >= 0 ? Number(args[atAt + 1]) : NaN
+      if (Number.isFinite(at)) await startScheduled(home, at, env)
+      if (!signedIn(home)) {
+        say(notSignedIn)
+        return quiet ? 0 : 1
+      }
+      const off = sendingOff(home, env)
+      if (off) {
+        say(`reports are off (${off}): nothing was sent`)
+        return 0
+      }
+      await send(false)
+      return 0
+    }
+    case "off":
+      updateSettings(home, (s) => {
+        s.off = true
+      })
+      say("reports are off: brain sends nothing from this machine to your 100xprompt account. The console keeps the last report until you remove this machine there; `brain dashboard on` starts them again.")
+      return 0
+    case "on": {
+      updateSettings(home, (s) => {
+        delete s.off
+      })
+      const notes = [sendingOff(home, env) ? "BRAIN_NO_REPORT is set here, so nothing is sent while it is" : "", signedIn(home) ? "" : "sign in first: brain gateway login"].filter(Boolean)
+      say(`reports are on: brain sends this machine's report after commands that change it, and with \`brain dashboard\`${notes.length ? ` (${notes.join("; ")})` : ""}.`)
+      return 0
+    }
+    case "status": {
+      const { gatewayState, machineName } = await import("./report.ts")
+      const { machineId } = await import("./state.ts")
+      const off = sendingOff(home, env)
+      const push = readCache(home).push ?? {}
+      const counts = readCache(home).counts
+      const email = gatewayState(home).email
+      const lines = [
+        `reports: ${off ? `off (${off})` : "on"}`,
+        `signed in: ${signedIn(home) ? `yes${typeof email === "string" && email ? `, as ${email}` : ""}` : "no (brain gateway login)"}`,
+        `sends to: ${reportUrl(home)}`,
+        `last sent: ${push.lastSentAt ? `${push.lastSentAt} (${ago(push.lastSentAt)})` : "never"}`,
+        ...(push.lastError && push.lastAttemptAt ? [`last attempt: ${push.lastAttemptAt} (${ago(push.lastAttemptAt)}) failed: ${push.lastError}`] : []),
+        ...(typeof push.pendingUntilMs === "number" && push.pendingUntilMs > Date.now() ? [`next: a report waits to go out at ${new Date(push.pendingUntilMs).toISOString()}`] : []),
+        `sessions counted: ${counts?.at ? `${counts.at} (${ago(counts.at)}; \`brain dashboard\` counts them again)` : "never (`brain dashboard` counts them)"}`,
+        `conversions logged: ${readConversions(home, 0).total}`,
+        `machine: ${machineName()} (${machineId(home)})`,
+        `view: ${DASHBOARD_URL}`,
+      ]
+      lines.forEach((l) => io.out(l))
+      return 0
+    }
+    default:
+      io.out(`unknown dashboard command "${sub}"`)
+      USAGE.forEach((l) => io.out(`usage: ${l}`))
+      return 2
+  }
+}

package/src/dashboard/conversions.ts

@@ -0,0 +1,170 @@
+// The conversion log: one line per session brain carried from one tool into another (`session continue` / `handoff`, not
+// dry runs), for the Brain view of the console. <home>/.brain/logs/conversions.jsonl (0600), append-only. What a line
+// holds is exactly a conversion of the dashboard report (docs/dashboard-contract.md): which tools, how, when, the chat's
+// title and its project FOLDER NAME. Never the chat text, never a full path.
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { basename, join, resolve } from "node:path"
+import type { Way } from "../adapters/types.ts"
+import { redact } from "../memory/redact.ts"
+
+export const conversionLog = (home: string) => join(home, ".brain", "logs", "conversions.jsonl")
+
+export const TITLE_MAX = 200
+export const PROJECT_MAX = 120
+const LABEL_MAX = 80
+const WAYS: readonly Way[] = ["native", "import", "brief"]
+
+export interface Conversion {
+  /** Made when the conversion happened: the gateway drops a conversion it already has. */
+  id: string
+  at: string
+  from: string
+  fromLabel: string
+  to: string
+  toLabel: string
+  way: Way
+  title: string | null
+  /** The project folder's name only (basename), never its path. */
+  project: string | null
+  turns: number | null
+  /** Estimated tokens of the converted session. */
+  tokens: number | null
+  /** Big tool outputs were replaced by digests. */
+  lean: boolean
+}
+
+/** At most `n` UTF-16 units, never ending in half of a surrogate pair. */
+export function clip(s: string, n: number): string {
+  if (s.length <= n) return s
+  const cut = s.slice(0, n)
+  return /[\uD800-\uDBFF]$/.test(cut) ? cut.slice(0, -1) : cut
+}
+
+/** A title as it may be sent: one line, secrets taken out, at most 200 characters; null when there is none. */
+export function cleanTitle(t: unknown): string | null {
+  if (typeof t !== "string") return null
+  const one = redact(t.replace(/\s+/g, " ").trim())
+  return one ? clip(one, TITLE_MAX) : null
+}
+
+/** The project folder's name, from a folder path or a name; null for none, the root, or a home folder (not a project). */
+export function projectName(cwd: unknown, homes: string[] = []): string | null {
+  if (typeof cwd !== "string" || !cwd.trim()) return null
+  const p = cwd.trim()
+  if (p.includes("/") || p.includes("\\")) {
+    const full = resolve(p)
+    if (full === "/" || homes.some((h) => h && resolve(h) === full)) return null
+  }
+  const name = basename(p.replace(/[\\/]+$/, "")).split("\\").pop() ?? ""
+  return name ? clip(name, PROJECT_MAX) : null
+}
+
+const count = (n: unknown): number | null => (typeof n === "number" && Number.isFinite(n) && n >= 0 ? Math.floor(n) : null)
+const label = (s: unknown, fallback: string) => clip(typeof s === "string" && s.trim() ? s.trim() : fallback, LABEL_MAX)
+
+/** What `continue` knows when a writer has written: the tools, the way, and the source session's header and size. */
+export interface ConversionInput {
+  from: string
+  fromLabel: string
+  to: string
+  toLabel: string
+  way: Way
+  title?: string
+  /** The session's project folder (only its name is kept). */
+  cwd?: string
+  turns?: number
+  tokens?: number
+  lean: boolean
+  at?: string
+}
+
+/** "cursor" is what `continue --in` calls Cursor; everywhere else (readers, hooks, harnesses) it is "cursor-ide". */
+export const toolId = (tool: string) => (tool === "cursor" ? "cursor-ide" : tool)
+
+/** One line for the log, from what `continue` knows. */
+export function conversionOf(c: ConversionInput, homes: string[] = [process.env.BRAIN_HOME ?? "", process.env.HOME ?? "", homedir()]): Conversion {
+  return {
+    id: crypto.randomUUID(),
+    at: c.at ?? new Date().toISOString(),
+    from: toolId(c.from),
+    fromLabel: label(c.fromLabel, c.from),
+    to: toolId(c.to),
+    toLabel: label(c.toLabel.replace(/^the /, ""), c.to),
+    way: c.way,
+    title: cleanTitle(c.title),
+    project: projectName(c.cwd, homes),
+    turns: count(c.turns),
+    tokens: count(c.tokens),
+    lean: !!c.lean,
+  }
+}
+
+/** Appends one conversion. Never throws: a log must not break a conversion that already happened. */
+export function logConversion(home: string, c: ConversionInput): Conversion | undefined {
+  try {
+    const line = conversionOf(c)
+    const f = conversionLog(home)
+    mkdirSync(join(home, ".brain", "logs"), { recursive: true, mode: 0o700 })
+    const fresh = !existsSync(f)
+    appendFileSync(f, `${JSON.stringify(line)}\n`, { mode: 0o600 })
+    if (fresh) chmodSync(f, 0o600)
+    return line
+  } catch {
+    return undefined
+  }
+}
+
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/
+
+/** A line of the log as it may be sent, or undefined for a line that is not a conversion (a damaged or foreign line). */
+export function parseConversion(line: string): Conversion | undefined {
+  let v: any
+  try {
+    v = JSON.parse(line)
+  } catch {
+    return undefined
+  }
+  if (!v || typeof v !== "object" || typeof v.id !== "string" || !v.id || typeof v.at !== "string" || !ISO.test(v.at)) return undefined
+  if (typeof v.from !== "string" || !v.from || typeof v.to !== "string" || !v.to || !WAYS.includes(v.way)) return undefined
+  // Read back through the same filters it was written with: whatever is in the file, only these fields, clipped, leave.
+  return {
+    id: clip(v.id, 64),
+    at: v.at,
+    from: clip(v.from, LABEL_MAX),
+    fromLabel: label(v.fromLabel, v.from),
+    to: clip(v.to, LABEL_MAX),
+    toLabel: label(v.toLabel, v.to),
+    way: v.way,
+    title: cleanTitle(v.title),
+    project: projectName(v.project),
+    turns: count(v.turns),
+    tokens: count(v.tokens),
+    lean: v.lean === true,
+  }
+}
+
+/** Months (UTC, "YYYY-MM") counted in a report's totals.byMonth: the latest twelve that have any conversion. */
+export const MONTHS_KEPT = 12
+
+/** The newest `limit` conversions (newest first), how many the log holds in all, and how many per month (UTC). */
+export function readConversions(home: string, limit = 500): { list: Conversion[]; total: number; byMonth: Record<string, number> } {
+  let text = ""
+  try {
+    text = readFileSync(conversionLog(home), "utf8")
+  } catch {
+    return { list: [], total: 0, byMonth: {} }
+  }
+  const all: Conversion[] = []
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue
+    const c = parseConversion(line)
+    if (c) all.push(c)
+  }
+  // The file is in the order they happened; a sort by time keeps that for lines written by machines with a skewed clock.
+  const newest = all.map((c, i) => ({ c, i })).sort((a, b) => b.c.at.localeCompare(a.c.at) || b.i - a.i).map((x) => x.c)
+  const months = new Map<string, number>()
+  for (const c of all) months.set(c.at.slice(0, 7), (months.get(c.at.slice(0, 7)) ?? 0) + 1)
+  const byMonth = Object.fromEntries([...months].sort((a, b) => b[0].localeCompare(a[0])).slice(0, MONTHS_KEPT))
+  return { list: newest.slice(0, Math.max(0, limit)), total: all.length, byMonth }
+}