@100xprompt/brain 0.1.0 → 0.1.2

package/src/dashboard/report.ts

@@ -0,0 +1,275 @@
+// The report of this machine for the Brain view of the 100xprompt console, built exactly as docs/dashboard-contract.md
+// says: the machine, the coding tools present here (sessions, gateway, MCP tools, hooks), the gateway settings, memory
+// counts, and the conversions brain made. Summaries plus each chat's title and project folder name: never chat text, file
+// contents, full paths or keys.
+import { existsSync, readFileSync } from "node:fs"
+import { hostname } from "node:os"
+import { join } from "node:path"
+import type { Reader } from "../adapters/types.ts"
+import { toolLabel } from "../brief.ts"
+import { DEFAULT_MODEL, DEFAULT_ROUTE, type Env, type GatewaySettings, modelName, statePath } from "../gateway/common.ts"
+import { CONNECTORS, cliAuthPath, hasKey, installedHere } from "../gateway/connect.ts"
+import { HOOK_TOOLS, hookInstalled } from "../hooks.ts"
+import { MCP_TOOLS, statusMcp } from "../memory/mcp-install.ts"
+import { chittaCandidates, memoryDbPath, openMemory } from "../memory/store.ts"
+import { readOrgConfig } from "../org/config.ts"
+import { VERSION } from "../self.ts"
+import { clip, type Conversion, readConversions, toolId } from "./conversions.ts"
+import { machineId, readCache, type ToolCount, updateCache } from "./state.ts"
+
+export const SCHEMA = "brain-report/v1"
+/** The gateway takes at most 500 conversions and 512 KB; a report is cut to fit below that. */
+export const MAX_CONVERSIONS = 500
+export const MAX_BYTES = 500_000
+
+export interface Harness {
+  id: string
+  label: string
+  /** Sessions brain can read for it here; null when never counted (`brain dashboard` counts them). */
+  sessions: number | null
+  lastSessionAt: string | null
+  gateway: "connected" | "available" | "unsupported"
+  /** brain_recall / brain_expand installed in it; null when brain has no MCP installer for it. */
+  mcp: boolean | null
+  /** The session-start hook installed; null when brain has no hook for it. */
+  hooks: boolean | null
+}
+
+export interface BrainReport {
+  schema: typeof SCHEMA
+  sentAt: string
+  machine: { id: string; name: string; os: string; brainVersion: string }
+  harnesses: Harness[]
+  gateway: {
+    signedIn: boolean
+    email?: string
+    route: string
+    model: string
+    contextEdit: boolean
+    connected: Array<{ tool: string; label: string; since: string | null }>
+  }
+  memory: { available: true; projects: number; items: number } | { available: false }
+  conversions: Conversion[]
+  /** byMonth: conversions per month, UTC "YYYY-MM", the latest twelve months that have any. */
+  totals: { conversions: number; byMonth: Record<string, number> }
+}
+
+/** The computer's name: os.hostname() without ".local". */
+export const machineName = (h: string = hostname()) => clip(h.replace(/\.local\.?$/i, "").trim(), 80) || "this machine"
+
+const isoOrNull = (v: unknown): string | null => {
+  if (typeof v !== "string" && typeof v !== "number") return null
+  const t = typeof v === "number" ? v : Date.parse(v)
+  return Number.isFinite(t) ? new Date(t).toISOString() : null
+}
+
+interface GatewayState {
+  settings?: Partial<GatewaySettings>
+  email?: string
+  tools?: Record<string, { at?: string }>
+}
+
+/** <home>/.brain/gateway.json as `brain gateway` keeps it (read only here). */
+export function gatewayState(home: string): GatewayState {
+  try {
+    const s = JSON.parse(readFileSync(statePath(home), "utf8"))
+    return s && typeof s === "object" ? s : {}
+  } catch {
+    return {}
+  }
+}
+
+/** What the MCP installer calls a tool, as the readers (and so the report) call it. */
+const MCP_IDS: Record<string, string> = { cursor: "cursor-ide", gemini: "gemini-cli", vscode: "vscode-copilot" }
+const mcpToolId = (id: string) => MCP_IDS[id] ?? id
+
+async function withTimeout<T>(p: Promise<T>, ms: number): Promise<T | undefined> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const late = new Promise<undefined>((r) => {
+    timer = setTimeout(() => r(undefined), ms)
+  })
+  try {
+    return await Promise.race([p.catch(() => undefined), late])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Sessions per tool, from every reader at once, within `timeoutMs`; a reader that fails or takes longer is left out (its
+ * last count stays in the cache). Some readers copy a big database to read it, so this runs only for `brain dashboard`.
+ */
+export async function countSessions(home: string, o: { timeoutMs?: number; readers?: Reader[] } = {}): Promise<Record<string, ToolCount>> {
+  const readers = o.readers ?? (await import("../adapters/index.ts")).READERS
+  const out: Record<string, ToolCount> = {}
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const deadline = new Promise<"late">((r) => {
+    timer = setTimeout(r, o.timeoutMs ?? 20_000, "late" as const)
+  })
+  try {
+    await Promise.all(
+      readers.map(async (r) => {
+        const refs = await Promise.race([r.list(home).catch(() => undefined), deadline])
+        if (!refs || refs === "late") return
+        const id = toolId(r.tool)
+        const newest = refs.map((x) => isoOrNull(x.updatedAt)).filter((x): x is string => !!x).sort().pop() ?? null
+        const had = out[id]
+        out[id] = { sessions: (had?.sessions ?? 0) + refs.length, lastSessionAt: [had?.lastSessionAt, newest].filter((x): x is string => !!x).sort().pop() ?? null }
+      }),
+    )
+  } finally {
+    clearTimeout(timer)
+  }
+  return out
+}
+
+/** Counts sessions now and keeps the counts for later background reports (merged over the last ones). */
+export async function countAndKeep(home: string, o: { timeoutMs?: number; readers?: Reader[] } = {}): Promise<Record<string, ToolCount>> {
+  const fresh = await countSessions(home, o)
+  const c = updateCache(home, (c) => {
+    c.counts = { at: new Date().toISOString(), tools: { ...(c.counts?.tools ?? {}), ...fresh } }
+  })
+  return c.counts!.tools
+}
+
+async function memorySummary(home: string, env: Env): Promise<BrainReport["memory"]> {
+  try {
+    const org = env.BRAIN_ORG !== "off" && readOrgConfig(home)
+    // No store yet: say whether memory can be used, without creating one.
+    if (!org && !existsSync(memoryDbPath(home))) return chittaCandidates().some((f) => existsSync(f)) ? { available: true, projects: 0, items: 0 } : { available: false }
+    const mem = openMemory(home)
+    try {
+      const r = await withTimeout(
+        (async () => {
+          const s = await mem.status()
+          if (!s.available) return { available: false as const }
+          const projects = await mem.projects()
+          return { available: true as const, projects: projects.length, items: projects.reduce((n, p) => n + (Number(p.items) || 0), 0) }
+        })(),
+        5_000,
+      )
+      return r ?? { available: false }
+    } finally {
+      mem.close()
+    }
+  } catch {
+    return { available: false }
+  }
+}
+
+/** Whether a tool the MCP installer knows has run here (its config or folder exists), as the installer decides it. */
+function mcpToolHere(t: (typeof MCP_TOOLS)[number], home: string, env: Env): boolean {
+  if (t.id === "claude-code" && env.CLAUDE_CONFIG_DIR && existsSync(env.CLAUDE_CONFIG_DIR)) return true
+  return t.probe.some((p) => existsSync(join(home, p)))
+}
+
+/**
+ * Every coding tool brain knows (its readers, gateway connectors, MCP installer and hooks) that is present here: found by
+ * the connector's or the installer's probe, connected, with brain's MCP tools or hook in it, or with sessions counted.
+ */
+export async function harnesses(home: string, counts: Record<string, ToolCount> | undefined, env: Env = process.env): Promise<Harness[]> {
+  const { READERS } = await import("../adapters/index.ts")
+  const st = gatewayState(home)
+  const connected = st.tools && typeof st.tools === "object" ? st.tools : {}
+  let mcpInstalled = new Map<string, boolean>()
+  try {
+    mcpInstalled = new Map(statusMcp(home).map((c) => [mcpToolId(c.tool), c.action === "installed"]))
+  } catch {}
+  const hookOn = (id: string) => {
+    try {
+      return hookInstalled(id, home)
+    } catch {
+      return false
+    }
+  }
+  /**
+   * The 100xprompt CLI is the gateway's own client: there is nothing for brain to connect, and it is on the gateway
+   * whenever it is signed in (its auth.json holds a key; only its presence is looked at). Signed out, it can be
+   * (`100xprompt auth login`). Any other tool: undefined, decided by brain's connectors.
+   */
+  const ownClient = (id: string, h: string, e: Env): Harness["gateway"] | undefined => {
+    if (id !== "100xprompt") return undefined
+    try {
+      const k = JSON.parse(readFileSync(cliAuthPath(h, e), "utf8"))?.["100xprompt"]?.key
+      return typeof k === "string" && k.trim() ? "connected" : "available"
+    } catch {
+      return "available"
+    }
+  }
+  const known = new Map<string, { label: string; present: boolean }>()
+  const add = (id: string, label: string, present: boolean) => {
+    const k = known.get(id)
+    if (k) k.present ||= present
+    else known.set(id, { label, present })
+  }
+  for (const r of READERS) add(toolId(r.tool), r.label, (counts?.[toolId(r.tool)]?.sessions ?? 0) > 0)
+  for (const c of CONNECTORS) {
+    let here = false
+    try {
+      here = installedHere(c, home, env)
+    } catch {}
+    add(c.id, c.label, here || !!connected[c.id])
+  }
+  for (const t of MCP_TOOLS) add(mcpToolId(t.id), t.label, mcpToolHere(t, home, env) || mcpInstalled.get(mcpToolId(t.id)) === true)
+  for (const id of HOOK_TOOLS) add(id, toolLabel(id), hookOn(id))
+  const mcpIds = new Set(MCP_TOOLS.map((t) => mcpToolId(t.id)))
+  const connectorIds = new Set(CONNECTORS.map((c) => c.id))
+  return [...known.entries()]
+    .filter(([, k]) => k.present)
+    .map(([id, k]): Harness => ({
+      id,
+      label: clip(k.label, 80),
+      sessions: counts?.[id] ? counts[id]!.sessions : null,
+      lastSessionAt: counts?.[id]?.lastSessionAt ?? null,
+      gateway: connected[id] ? "connected" : (ownClient(id, home, env) ?? (connectorIds.has(id) ? "available" : "unsupported")),
+      mcp: mcpIds.has(id) ? mcpInstalled.get(id) === true : null,
+      hooks: HOOK_TOOLS.includes(id) ? hookOn(id) : null,
+    }))
+    .sort((a, b) => a.label.localeCompare(b.label) || a.id.localeCompare(b.id))
+}
+
+/** The gateway part: signed in or not, the settings `brain gateway status` shows, and the tools connected to it. */
+export function gatewayPart(home: string): BrainReport["gateway"] {
+  const st = gatewayState(home)
+  const s = st.settings && typeof st.settings === "object" ? st.settings : {}
+  const label = (id: string) => CONNECTORS.find((c) => c.id === id)?.label ?? toolLabel(id)
+  return {
+    signedIn: hasKey(home),
+    ...(typeof st.email === "string" && st.email ? { email: clip(st.email, 200) } : {}),
+    route: typeof s.route === "string" && s.route ? s.route : DEFAULT_ROUTE,
+    model: modelName(typeof s.model === "string" && s.model ? s.model : DEFAULT_MODEL),
+    contextEdit: typeof s.contextEdit === "boolean" ? s.contextEdit : true,
+    connected: Object.entries(st.tools && typeof st.tools === "object" ? st.tools : {}).map(([tool, rec]) => ({ tool, label: clip(label(tool), 80), since: isoOrNull(rec?.at) })),
+  }
+}
+
+/**
+ * The whole report. Session counts are `counts` when given (`brain dashboard` just counted), else the last ones kept
+ * (null for a tool never counted); nothing here lists sessions, so a background report stays cheap.
+ */
+export async function buildReport(home: string, o: { counts?: Record<string, ToolCount>; now?: Date; env?: Env } = {}): Promise<BrainReport> {
+  const env = o.env ?? process.env
+  const counts = o.counts ?? readCache(home).counts?.tools
+  const { list, total, byMonth } = readConversions(home, MAX_CONVERSIONS)
+  return {
+    schema: SCHEMA,
+    sentAt: (o.now ?? new Date()).toISOString(),
+    machine: { id: machineId(home), name: machineName(), os: process.platform, brainVersion: VERSION },
+    harnesses: await harnesses(home, counts, env),
+    gateway: gatewayPart(home),
+    memory: await memorySummary(home, env),
+    conversions: list,
+    totals: { conversions: total, byMonth },
+  }
+}
+
+/** The report as it is sent: at most MAX_BYTES of JSON, the oldest conversions dropped first if it is bigger. */
+export function reportBody(r: BrainReport, maxBytes = MAX_BYTES): string {
+  let body = JSON.stringify(r)
+  let list = r.conversions
+  while (Buffer.byteLength(body) > maxBytes && list.length) {
+    list = list.slice(0, Math.floor(list.length * 0.9))
+    body = JSON.stringify({ ...r, conversions: list })
+  }
+  return body
+}

package/src/dashboard/send.ts

@@ -0,0 +1,213 @@
+// Sending the report (report.ts) to the person's 100xprompt account: POST <gateway>/api/brain/report with the brain's
+// gateway key, best effort, 10 s at most. docs/dashboard-contract.md has the rules:
+//   - only when signed in (`brain gateway login`), and not turned off (`brain dashboard off`, or BRAIN_NO_REPORT=1);
+//   - in the background after a command that changes what the report says, never slowing that command: the command starts
+//     a detached `brain dashboard push --quiet` and returns. At most one background push every 30 s: a command within 30 s
+//     of the last one schedules the next for 30 s after it, and a push already waiting covers later commands too, because a
+//     push reads the state when it runs;
+//   - the first time a report is about to go out, a notice says once what is sent and how to stop it.
+// This file stays cheap to import (every command that changes something loads it); report.ts is loaded only to send.
+import { CLI_PATH } from "../self.ts"
+import { DEFAULT_URL, type Env, readKey, statePath } from "../gateway/common.ts"
+import { readFileSync } from "node:fs"
+import { readCache, readSettings, updateCache, updateSettings } from "./state.ts"
+import type { BrainReport } from "./report.ts"
+
+/** Where the person sees what was sent. */
+export const DASHBOARD_URL = "https://100xprompt.com/dashboard?view=brain"
+export const REPORT_PATH = "/api/brain/report"
+export const SEND_TIMEOUT_MS = 10_000
+/** The least time between two background pushes. */
+export const REPORT_EVERY_MS = 30_000
+/** A waiting push that has not cleared its mark this long after its time has died: the mark is ignored. */
+const PENDING_STALE_MS = 60_000
+
+/** BRAIN_REPORT_EVERY_MS shortens or lengthens the 30 s between background pushes (tests use a short one). */
+export function reportEvery(env: Env = process.env): number {
+  const n = Number(env.BRAIN_REPORT_EVERY_MS)
+  return env.BRAIN_REPORT_EVERY_MS !== undefined && env.BRAIN_REPORT_EVERY_MS !== "" && Number.isFinite(n) && n >= 0 ? n : REPORT_EVERY_MS
+}
+
+/** The gateway address: the one `brain gateway connect --url` keeps in gateway.json, else https://proxy.100xprompt.com. */
+export function gatewayUrl(home: string): string {
+  try {
+    const u = JSON.parse(readFileSync(statePath(home), "utf8"))?.settings?.url
+    if (typeof u === "string" && u.trim()) return u.trim().replace(/\/+$/, "")
+  } catch {}
+  return DEFAULT_URL
+}
+
+export const reportUrl = (home: string) => `${gatewayUrl(home)}${REPORT_PATH}`
+
+/** The key goes over https only (plain http only to a gateway on this machine), as `brain gateway connect` allows. */
+export function safeUrl(url: string): boolean {
+  try {
+    const u = new URL(url)
+    if (u.username || u.password) return false
+    if (u.protocol === "https:") return true
+    return u.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(u.hostname)
+  } catch {
+    return false
+  }
+}
+
+export const signedIn = (home: string) => readKey(home).length > 0
+
+/** Why nothing is sent right now, or undefined when reports go out (signed in or not is checked separately). */
+export function sendingOff(home: string, env: Env = process.env): string | undefined {
+  const v = env.BRAIN_NO_REPORT
+  if (v !== undefined && v !== "" && v !== "0" && v.toLowerCase() !== "false") return "BRAIN_NO_REPORT is set"
+  if (readSettings(home).off) return "turned off with `brain dashboard off`"
+  return undefined
+}
+
+/** What the first-time notice says. */
+export const NOTICE = [
+  "brain: this machine now sends a report to your 100xprompt account, for the Brain view of the console",
+  `  (${DASHBOARD_URL}). It holds: this computer's name, OS and brain version; the coding tools found`,
+  "  here, their session counts, and which are connected to the gateway or have brain's MCP tools or hooks; your gateway",
+  "  settings and memory counts; and each chat brain moved between tools: when, from and to which tool, its title and its",
+  "  project folder's name. Never chat text, file contents, full paths or keys.",
+  "  Stop it: brain dashboard off",
+]
+
+/** Prints the notice the first time a report is about to go out, and remembers that it did. */
+export function noticeOnce(home: string, print: (line: string) => void): boolean {
+  if (readSettings(home).noticeShownAt) return false
+  NOTICE.forEach((l) => print(l))
+  try {
+    updateSettings(home, (s) => {
+      s.noticeShownAt = new Date().toISOString()
+    })
+  } catch {}
+  return true
+}
+
+export type SendResult = { ok: true; machines?: number } | { ok: false; why: string }
+
+/** POSTs the report. Never throws and never says the key; records when it went out (or why not) for `brain dashboard status`. */
+export async function sendReport(home: string, report: BrainReport, o: { fetchImpl?: typeof fetch; timeoutMs?: number } = {}): Promise<SendResult> {
+  const r = await post(home, report, o)
+  updateCache(home, (c) => {
+    const at = new Date().toISOString()
+    c.push = { ...c.push, lastAttemptAt: at }
+    if (r.ok) {
+      c.push.lastSentAt = at
+      delete c.push.lastError
+    } else c.push.lastError = r.why
+  })
+  return r
+}
+
+async function post(home: string, report: BrainReport, o: { fetchImpl?: typeof fetch; timeoutMs?: number }): Promise<SendResult> {
+  const key = readKey(home)
+  if (!key) return { ok: false, why: "not signed in (brain gateway login)" }
+  const url = reportUrl(home)
+  if (!safeUrl(url)) return { ok: false, why: `the gateway address ${gatewayUrl(home)} is not https; the key is never sent over it` }
+  const { reportBody } = await import("./report.ts")
+  const timeoutMs = o.timeoutMs ?? SEND_TIMEOUT_MS
+  try {
+    const res = await (o.fetchImpl ?? fetch)(url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+      body: reportBody(report),
+      // A redirect is not followed: it could carry the key to another host.
+      redirect: "manual",
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (res.ok) {
+      const j = (await res.json().catch(() => undefined)) as { machines?: unknown } | undefined
+      return { ok: true, ...(typeof j?.machines === "number" ? { machines: j.machines } : {}) }
+    }
+    const said = await res
+      .json()
+      .then((j: any) => (typeof j?.error === "string" ? j.error : typeof j?.error?.message === "string" ? j.error.message : typeof j?.reason === "string" ? j.reason : ""))
+      .catch(() => "")
+    const why =
+      res.status === 401 || res.status === 403 ? "the gateway refused the key (sign in again: brain gateway login)"
+      : res.status === 404 ? "this gateway does not take brain reports yet"
+      : res.status === 413 ? "the report was too big for the gateway"
+      : res.status === 429 ? "too many reports for now; the next one carries everything"
+      : res.status >= 300 && res.status < 400 ? `the gateway answered with a redirect (HTTP ${res.status}); not followed`
+      : `the gateway answered HTTP ${res.status}`
+    return { ok: false, why: said ? `${why}: ${String(said).slice(0, 200)}` : why }
+  } catch (e) {
+    const name = (e as Error)?.name
+    return { ok: false, why: name === "TimeoutError" || name === "AbortError" ? `the gateway did not answer within ${Math.round(timeoutMs / 1000)} s` : `could not reach ${gatewayUrl(home)}` }
+  }
+}
+
+/**
+ * When the next background push may run, given the last one: now, or 30 s after the last one started. undefined when one
+ * is already waiting (it reads the state when it runs, so it carries this change too).
+ */
+export function planPush(p: { lastStartMs?: number; pendingUntilMs?: number }, now: number, every = REPORT_EVERY_MS): { at: number } | undefined {
+  if (typeof p.pendingUntilMs === "number" && now < p.pendingUntilMs + PENDING_STALE_MS) return undefined
+  const last = typeof p.lastStartMs === "number" && p.lastStartMs <= now ? p.lastStartMs : -Infinity
+  return { at: Math.max(now, last + every) }
+}
+
+/**
+ * After a command that changed what the report says: starts `brain dashboard push --quiet` in a detached process and
+ * returns at once. Nothing at all when not signed in or turned off. Never throws.
+ */
+export function reportInBackground(home: string, o: { env?: Env; cli?: string; say?: (line: string) => void; now?: number } = {}): boolean {
+  const env = o.env ?? process.env
+  try {
+    if (!signedIn(home) || sendingOff(home, env)) return false
+    noticeOnce(home, o.say ?? ((l) => process.stderr.write(`${l}\n`)))
+    const plan = planPush(readCache(home).push ?? {}, o.now ?? Date.now(), reportEvery(env))
+    if (!plan) return false
+    updateCache(home, (c) => {
+      c.push = { ...c.push, pendingUntilMs: plan.at }
+    })
+    try {
+      const child = Bun.spawn([process.execPath, o.cli ?? CLI_PATH, "dashboard", "push", "--quiet", "--at", String(plan.at)], {
+        cwd: home,
+        detached: true,
+        stdio: ["ignore", "ignore", "ignore"],
+        env: { ...env, BRAIN_HOME: home },
+      })
+      child.unref()
+    } catch {
+      // Nothing started: the mark must not hold up the next command's push.
+      updateCache(home, (c) => {
+        if (c.push?.pendingUntilMs === plan.at) delete c.push.pendingUntilMs
+      })
+      return false
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** The start of a background push: waits for its time, then clears its mark, so a later command schedules the next. */
+export async function startScheduled(home: string, at: number, env: Env = process.env): Promise<void> {
+  const wait = Math.min(at - Date.now(), reportEvery(env) + 5_000)
+  if (wait > 0) await Bun.sleep(wait)
+  const now = Date.now()
+  updateCache(home, (c) => {
+    c.push = { ...c.push, lastStartMs: now }
+    if (typeof c.push.pendingUntilMs === "number" && c.push.pendingUntilMs <= Math.max(at, now)) delete c.push.pendingUntilMs
+  })
+}
+
+/**
+ * The last report before `brain gateway logout` forgets the key: the same snapshot, marked signed out, so the console does
+ * not go on showing this machine as signed in. Sent while the key is still there (after logout nothing can be sent),
+ * waited for briefly, best effort; nothing when reports are off or the person is not signed in.
+ */
+export async function reportSignedOut(home: string, o: { env?: Env; fetchImpl?: typeof fetch; timeoutMs?: number } = {}): Promise<SendResult | undefined> {
+  const env = o.env ?? process.env
+  if (sendingOff(home, env) || !readKey(home)) return undefined
+  try {
+    const { buildReport } = await import("./report.ts")
+    const report = await buildReport(home, { env })
+    report.gateway = { ...report.gateway, signedIn: false }
+    delete (report.gateway as { email?: string }).email
+    return await sendReport(home, report, { timeoutMs: o.timeoutMs ?? 3_000, ...(o.fetchImpl ? { fetchImpl: o.fetchImpl } : {}) })
+  } catch {
+    return undefined
+  }
+}

package/src/dashboard/state.ts

@@ -0,0 +1,95 @@
+// The small files the dashboard report keeps under <home>/.brain (all 0600, in a 0700 folder):
+//   machine.json          { id, createdAt }: this machine's random id, made once (the console tells machines apart by it)
+//   dashboard.json        the person's choice: { off?, noticeShownAt? }. Written only by the person's own commands, never
+//                         by a background push, so a push can never undo `brain dashboard off`.
+//   dashboard-cache.json  what brain works out or remembers by itself: the last session counts, and the push bookkeeping
+//                         (when the last report went out, a push that is waiting to run).
+// Every write re-reads the file first and changes only its own fields, then replaces the file atomically.
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+export const brainDir = (home: string) => join(home, ".brain")
+export const machinePath = (home: string) => join(brainDir(home), "machine.json")
+export const settingsPath = (home: string) => join(brainDir(home), "dashboard.json")
+export const cachePath = (home: string) => join(brainDir(home), "dashboard-cache.json")
+
+export interface DashboardSettings {
+  /** `brain dashboard off`: nothing is sent. */
+  off?: boolean
+  /** When the first-time notice (what is sent, how to stop it) was shown. */
+  noticeShownAt?: string
+}
+
+export interface ToolCount {
+  sessions: number
+  lastSessionAt: string | null
+}
+
+export interface DashboardCache {
+  /** Sessions per tool id, from the last `brain dashboard` (counting is expensive: background reports reuse these). */
+  counts?: { at: string; tools: Record<string, ToolCount> }
+  push?: {
+    /** When the last background push started (epoch ms): the next one waits until 30 s after it. */
+    lastStartMs?: number
+    /** A background push is waiting to run at this time (epoch ms); it reads the state when it runs. */
+    pendingUntilMs?: number
+    lastAttemptAt?: string
+    lastSentAt?: string
+    /** Why the last attempt failed (cleared by a success). */
+    lastError?: string
+  }
+}
+
+function readJson<T extends object>(path: string): T {
+  try {
+    const v = JSON.parse(readFileSync(path, "utf8"))
+    return v && typeof v === "object" && !Array.isArray(v) ? (v as T) : ({} as T)
+  } catch {
+    return {} as T
+  }
+}
+
+/** Atomic write, 0600, in a 0700 <home>/.brain. */
+export function writePrivateJson(path: string, value: unknown) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
+  const tmp = `${path}.${process.pid}.brain-tmp`
+  try {
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 })
+    chmodSync(tmp, 0o600)
+    renameSync(tmp, path)
+  } finally {
+    rmSync(tmp, { force: true })
+  }
+}
+
+export const readSettings = (home: string): DashboardSettings => readJson<DashboardSettings>(settingsPath(home))
+export function updateSettings(home: string, change: (s: DashboardSettings) => void): DashboardSettings {
+  const s = readSettings(home)
+  change(s)
+  writePrivateJson(settingsPath(home), s)
+  return s
+}
+
+export const readCache = (home: string): DashboardCache => readJson<DashboardCache>(cachePath(home))
+/** Best effort: bookkeeping that cannot be written is not a reason to fail. */
+export function updateCache(home: string, change: (c: DashboardCache) => void): DashboardCache {
+  const c = readCache(home)
+  change(c)
+  try {
+    writePrivateJson(cachePath(home), c)
+  } catch {}
+  return c
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** This machine's id: made once, kept in <home>/.brain/machine.json. A missing or damaged file gets a new one. */
+export function machineId(home: string): string {
+  const m = readJson<{ id?: unknown; createdAt?: unknown }>(machinePath(home))
+  if (typeof m.id === "string" && UUID.test(m.id)) return m.id
+  const id = crypto.randomUUID()
+  try {
+    writePrivateJson(machinePath(home), { id, createdAt: new Date().toISOString() })
+  } catch {}
+  return id
+}