@100xprompt/brain 0.1.3 → 0.1.5

package/README.md

@@ -167,10 +167,73 @@ brain dashboard off          # send nothing from this machine (brain dashboard o
 ```
 
 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.
+`connect`, `disconnect`, `session continue`, `handoff`, `mcp install`/`uninstall`, `session hooks install`/`uninstall`,
+`settings set`/`unset`, `memory ingest`/`forget`/`sync`, `org login`/`logout`, `dashboard on`), 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.
 
+## Settings
+
+Everything brain can switch on this computer is one list of settings:
+
+```bash
+brain status                                   # this computer at a glance, and whether its settings are applied
+brain settings                                 # every setting here: its value, who set it and when, applied or not
+brain settings set tools.codex.model flash     # Codex on 100xprompt Flash (it reconnects Codex)
+brain settings set lean.threshold 80k          # make sessions lean by themselves from 80,000 tokens
+brain settings set memory.enabled off          # no project memory on this computer
+brain settings unset lean.threshold            # back to brain's default
+brain settings history                         # recent changes, and what each replaced
+brain sync                                     # apply what changed or failed, and send the report now
+```
+
+| Setting | What it does |
+|---|---|
+| `tools.<tool>.gateway` | the tool uses 100xprompt's gateway (as `gateway connect` / `disconnect`) |
+| `tools.<tool>.model` | `pro`, `flash` or `auto`, per tool |
+| `tools.<tool>.contextEdit` | the gateway clears old tool results from long requests |
+| `tools.<tool>.mcp` | the tool has `brain_recall`, `brain_expand` and `brain_map` |
+| `tools.<tool>.hooks` | the session-start hook (this computer only) |
+| `lean.auto`, `lean.threshold`, `lean.minChars` | when a long session is made lean, and from what size an output becomes a digest |
+| `memory.enabled` | project memory |
+| `reports.enabled` | reports to your account (this computer only; the same as `dashboard on`/`off`) |
+
+The other commands keep working as before and are recorded too: after `brain gateway connect --tool codex --model flash`,
+`brain settings` shows `tools.codex.model = flash`, set by that command. A value that cannot be applied yet (not signed in,
+say) stays saved and is marked failed with the reason; `brain sync` tries again. If you change a tool's file by hand
+afterwards, brain shows the setting as changed outside brain and does not put it back until you set it again.
+
+To see this computer's settings in your dashboard's Brain view, pair it once:
+
+```bash
+brain pair            # approve this computer in your 100xprompt account (in the browser); --no-browser on SSH
+brain pair status     # paired or not, and the last exchange with the account
+```
+
+To have changes you make in the dashboard apply here by themselves, run brain in the background:
+
+```bash
+brain service install    # macOS (launchd) or Linux (systemd --user); every minute it takes and applies dashboard changes
+brain service status     # installed, running, and its last round
+brain service uninstall
+```
+
+It uses the folders and opt-outs your shell had when you last ran a brain command (`~/.brain/env.json`), restarts itself
+when you update brain, and waits longer between tries while you are offline. Its log is `~/.brain/logs/service.log`. Run
+`brain service uninstall` before removing brain (if you forget, it stops by itself). Without it, `brain status` or
+`brain sync` take dashboard changes by hand.
+
+Pairing gives this computer its own token (`~/.brain/machine.key`, readable only by you), separate from the gateway key
+your tools use: model keys never read or change settings. A paired computer sends the changes made here to your account
+and takes the ones made there when you run `brain status`, `brain settings` or `brain sync` (a few seconds at most; the
+changes wait when you are offline). Hooks and reports stay this-computer-only. Removing the computer in the dashboard
+revokes its token; a `~/.brain` copied to another computer is not paired there.
+
+Settings are kept in `~/.brain/settings.json`, readable only by you. Commands you run also note where your tools keep their
+files (`CLAUDE_CONFIG_DIR`, `CODEX_HOME` and the like) and brain's own opt-outs in `~/.brain/env.json`, kept for a
+background brain (coming) to use the same folders; never keys. One brain at a time changes a tool's files: another waits its
+turn (`~/.brain/lock`).
+
 ## Teams
 
 Memory can live on one shared server instead of each person's machine, with who may see what enforced there.
@@ -212,6 +275,11 @@ 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 status
+brain settings [list | get | set | unset | history | ids]
+brain sync
+brain pair [status | forget]
+brain service install | uninstall | 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.3",
+  "version": "0.1.5",
   "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

@@ -41,6 +41,11 @@ brain org admin init|serve|user|token|team|project|policy|audit|retention   shar
 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 status                                       this computer at a glance: sign-in, reports, memory, lean, tools, and whether its settings are applied
+brain settings [list|get|set|unset|history|ids]    brain's settings on this computer: who set each, and whether it is applied (\`brain settings help\`)
+brain sync                                         exchange settings with your account, apply what changed or failed, and send this computer's report now
+brain pair [--no-browser] | status | forget        approve this computer in your 100xprompt account, so its settings show in the dashboard
+brain service install | uninstall | status         run brain in the background, so changes made in your dashboard apply here by themselves
 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`
 
@@ -212,6 +217,41 @@ async function main() {
     out(`running from ${CLI_PATH}${isEphemeral() ? " (a temporary bunx copy: hooks and MCP entries it installs run the pinned package)" : ""}`)
     return
   }
+  // A command the person runs records where their tools keep their files (env.json), for a brain that runs without their shell.
+  {
+    const { isPersonsCommand, recordEnv } = await import("./settings/env.ts")
+    if (isPersonsCommand(process.argv.slice(2))) recordEnv(home)
+  }
+  if (cmd === "settings") {
+    const { settingsCommand } = await import("./settings/cli.ts")
+    let changed = false
+    const code = await settingsCommand(rest, home, undefined, undefined, { changed: () => (changed = true) })
+    // The report carries the settings: sent when one was saved, never after a refusal.
+    if (changed) await reportLater()
+    process.exit(code)
+  }
+  if (cmd === "status") {
+    const { statusCommand } = await import("./settings/cli.ts")
+    let changed = false
+    const code = await statusCommand(home, undefined, undefined, { changed: () => (changed = true) })
+    if (changed) await reportLater()
+    process.exit(code)
+  }
+  if (cmd === "service") {
+    const { serviceCommand } = await import("./service.ts")
+    process.exit(await serviceCommand(rest, home))
+  }
+  if (cmd === "pair") {
+    const { pairCommand } = await import("./settings/pair.ts")
+    const code = await pairCommand(rest, home)
+    // A newly paired computer reports at once, so the dashboard shows it as paired.
+    if (code === 0 && !rest.some((a) => !a.startsWith("-"))) await reportLater()
+    process.exit(code)
+  }
+  if (cmd === "sync") {
+    const { syncCommand } = await import("./settings/cli.ts")
+    process.exit(await syncCommand(home))
+  }
   // 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")
@@ -227,7 +267,10 @@ async function main() {
   }
   if (cmd === "dashboard") {
     const { dashboardCommand } = await import("./dashboard/cli.ts")
-    process.exit(await dashboardCommand(rest, home))
+    const code = await dashboardCommand(rest, home)
+    // Turned back on: the dashboard gets this computer as it is now.
+    if (code === 0 && rest[0] === "on") await reportLater()
+    process.exit(code)
   }
   if (cmd === "memory" && rest[0] === "sync") {
     const { syncMemory } = await import("./memory/sync.ts")
@@ -235,6 +278,7 @@ async function main() {
     const limitAt = rest.indexOf("--limit")
     const r = await syncMemory({ home, ...(here ? { cwd: process.cwd() } : {}), ...(limitAt >= 0 ? { limit: Number(rest[limitAt + 1]) || 8 } : {}) })
     if (!rest.includes("--quiet")) {
+      if (r.ingested) await reportLater()
       if (r.unavailable) out(`memory sync: memory is not available (${r.unavailable})`)
       else if (r.busy) out("memory sync: another sync is running")
       else out(`memory sync: ${r.ingested} session${r.ingested === 1 ? "" : "s"} (${r.items} items) added, ${r.upToDate} already up to date${r.deferred ? `, ${r.deferred} left for the next run` : ""}${r.errors.length ? `; could not read ${r.errors.length}` : ""} (${(r.ms / 1000).toFixed(1)}s)`)
@@ -243,7 +287,10 @@ async function main() {
   }
   if (cmd === "memory") {
     const { memoryCommand } = await import("./memory/cli.ts")
-    process.exit(await memoryCommand(rest, home, async (id) => readRef(await resolveRef(id)), out))
+    const code = await memoryCommand(rest, home, async (id) => readRef(await resolveRef(id)), out)
+    // The report carries memory's counts.
+    if (code === 0 && (rest[0] === "ingest" || rest[0] === "forget")) await reportLater()
+    process.exit(code)
   }
   if (cmd === "tokens") {
     const { tokensCommand } = await import("./memory/audit.ts")
@@ -251,7 +298,13 @@ async function main() {
   }
   if (cmd === "org") {
     const { orgCommand } = await import("./org/cli.ts")
-    process.exit(await orgCommand(rest, home, { out }))
+    const { orgConfigPath } = await import("./org/config.ts")
+    const { existsSync } = await import("node:fs")
+    const was = existsSync(orgConfigPath(home))
+    const code = await orgCommand(rest, home, { out })
+    // Joining or leaving team memory changes the report's memory part (a logout that left nothing changes nothing).
+    if (code === 0 && (rest[0] === "login" || (rest[0] === "logout" && was))) await reportLater()
+    process.exit(code)
   }
   if (cmd === "expand") {
     const id = rest[0] ?? fail("expand needs a blob id (from a digest: \"id=...\")")
@@ -329,13 +382,26 @@ async function main() {
   if (sub === "hooks") {
     const action = positionals[0] ?? "status"
     const tools = values.tool ? [values.tool] : HOOK_TOOLS
-    const changes = action === "install" ? await installHooks(tools, home, { dryRun: !!values["dry-run"] })
-      : action === "uninstall" ? await uninstallHooks(tools, home, { dryRun: !!values["dry-run"] })
-      : action === "status" ? await installHooks(tools, home, { dryRun: true })
-      : fail(`hooks ${action}? use install, uninstall or status`)
+    if (!["install", "uninstall", "status"].includes(action)) fail(`hooks ${action}? use install, uninstall or status`)
+    const change = action !== "status" && !values["dry-run"]
+    // A real install or uninstall is recorded as this computer's setting (tools.<tool>.hooks) in the same hold of the brain
+    // lock as the change, so `brain settings` shows who set it.
+    const { recordChanges } = change ? await import("./settings/apply.ts") : { recordChanges: undefined }
+    const { withBrainLock } = await import("./lock.ts")
+    const run = async () => {
+      const cs = action === "install" ? await installHooks(tools, home, { dryRun: !!values["dry-run"] })
+        : action === "uninstall" ? await uninstallHooks(tools, home, { dryRun: !!values["dry-run"] })
+        : await installHooks(tools, home, { dryRun: true })
+      if (recordChanges) {
+        const done = cs.filter((c) => (action === "install" ? ["installed", "already-installed"] : ["removed", "not-installed"]).includes(c.action))
+        recordChanges(home, done.map((c) => ({ id: `tools.${c.tool}.hooks`, value: action === "install" })), `brain session hooks ${action}`)
+      }
+      return cs
+    }
+    const changes = change ? await withBrainLock(home, run, { what: `${action === "install" ? "installing" : "removing"} session hooks` }) : await run()
     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()
+    if (change) await reportLater()
     return
   }
   if (sub === "hook") {
@@ -348,4 +414,11 @@ async function main() {
   fail(`unknown command "${sub}"\n\n${USAGE}`)
 }
 
-await main()
+try {
+  await main()
+} catch (e) {
+  // Another brain holding the lock too long, or a settings file from a newer brain: a sentence, not a stack trace.
+  const name = (e as Error)?.name
+  if (name === "BrainBusy" || (e as Error)?.constructor?.name === "SettingsUnwritable") fail((e as Error).message)
+  throw e
+}

package/src/dashboard/cli.ts

@@ -5,7 +5,7 @@ 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 { canReport, 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"
 
@@ -35,6 +35,26 @@ export function summary(r: BrainReport): string {
   return `${plural(r.harnesses.length, "tool")} (${connected} connected to the gateway)${counted.length ? `, ${plural(sessions, "session")}` : ""}, ${plural(r.totals.conversions, "conversion")}`
 }
 
+/**
+ * `brain dashboard on|off`: the choice in dashboard.json, recorded as this computer's reports.enabled setting in the same
+ * hold of the brain lock, so `brain settings` shows who set it.
+ */
+async function setReports(home: string, on: boolean) {
+  const { recordChanges } = await import("../settings/apply.ts")
+  const { withBrainLockSync } = await import("../lock.ts")
+  withBrainLockSync(
+    home,
+    () => {
+      updateSettings(home, (s) => {
+        if (on) delete s.off
+        else s.off = true
+      })
+      recordChanges(home, [{ id: "reports.enabled", value: on }], `brain dashboard ${on ? "on" : "off"}`)
+    },
+    { what: `turning reports ${on ? "on" : "off"}` },
+  )
+}
+
 export async function dashboardCommand(
   args: string[],
   home: string,
@@ -74,7 +94,7 @@ export async function dashboardCommand(
 
   switch (sub) {
     case undefined: {
-      if (!signedIn(home)) {
+      if (!canReport(home)) {
         io.out(notSignedIn)
         return 1
       }
@@ -92,7 +112,7 @@ export async function dashboardCommand(
       // `--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)) {
+      if (!canReport(home)) {
         say(notSignedIn)
         return quiet ? 0 : 1
       }
@@ -105,15 +125,11 @@ export async function dashboardCommand(
       return 0
     }
     case "off":
-      updateSettings(home, (s) => {
-        s.off = true
-      })
+      await setReports(home, false)
       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
-      })
+      await setReports(home, true)
       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

package/src/dashboard/report.ts

@@ -13,6 +13,7 @@ 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 { memoryOn } from "../settings/values.ts"
 import { VERSION } from "../self.ts"
 import { clip, type Conversion, readConversions, toolId } from "./conversions.ts"
 import { machineId, readCache, type ToolCount, updateCache } from "./state.ts"
@@ -52,6 +53,94 @@ export interface BrainReport {
   conversions: Conversion[]
   /** byMonth: conversions per month, UTC "YYYY-MM", the latest twelve months that have any. */
   totals: { conversions: number; byMonth: Record<string, number> }
+  /** Every setting on this computer and its state (docs/settings-contract.md, section 3). Absent when it could not be read. */
+  settings?: SettingsSection
+}
+
+export interface SettingsRow {
+  id: string
+  family: string
+  tool: string | null
+  type: "bool" | "choice" | "number"
+  choices?: string[]
+  min?: number
+  max?: number
+  unit?: string
+  value: boolean | number | string | null
+  from: string
+  by?: string
+  command?: string
+  at?: string
+  actual: boolean | number | string | null
+  state: string
+  error?: string
+  notes?: string[]
+  remote: boolean
+  /** A change made here to this setting (any level) not sent to the account yet: being the later write, it will win. */
+  pending?: true
+}
+
+export interface SettingsSection {
+  paired: boolean
+  lastSyncAt: string | null
+  waiting: number
+  /** brain's background service on this computer (docs/settings-contract.md, section 6). */
+  service: { installed: boolean; running: boolean; lastRunAt: string | null }
+  rows: SettingsRow[]
+}
+
+/**
+ * The report's settings: each setting's value, where it comes from and its state, as `brain settings` shows them. A
+ * model is pro, flash, auto, other or partly, never a gateway id; notes and errors were cleaned when they were kept.
+ */
+export async function settingsSection(home: string, env: Env): Promise<SettingsSection | undefined> {
+  try {
+    const { listSettings } = await import("../settings/apply.ts")
+    const { cleanText } = await import("../settings/catalog.ts")
+    const { exchangeState } = await import("../settings/account.ts")
+    const rows = await withTimeout(listSettings(home, env), 5_000)
+    if (!rows) return undefined
+    const st = exchangeState(home)
+    const { serviceState } = await import("../service.ts")
+    const { readSettingsFile } = await import("../settings/store.ts")
+    const unsent = new Set(readSettingsFile(home).doc.outbox.map((c) => c.id))
+    const short = (v: unknown, type: { kind: string; choices?: string[] }): boolean | number | string | null => {
+      if (v === undefined || v === null) return null
+      if (typeof v === "boolean" || typeof v === "number") return v
+      const t = String(v)
+      if (type.kind === "choice" && t !== "partly" && !type.choices!.includes(t)) return "other"
+      return clip(t, 40)
+    }
+    return {
+      paired: st.paired,
+      lastSyncAt: st.lastSyncAt ?? null,
+      waiting: st.waiting,
+      service: serviceState(home),
+      rows: rows.slice(0, 400).map((r): SettingsRow => {
+        const t = r.family.type
+        return {
+          id: r.id,
+          family: r.family.key,
+          tool: r.tool ?? null,
+          type: t.kind,
+          ...(t.kind === "choice" ? { choices: t.choices } : {}),
+          ...(t.kind === "number" ? { min: t.min, max: t.max, unit: t.unit } : {}),
+          value: short(r.value, t),
+          from: r.from,
+          ...(r.entry ? { by: r.entry.source, at: r.entry.at, ...(r.entry.command ? { command: clip(r.entry.command, 60) } : {}) } : {}),
+          actual: short(r.actual.value, t),
+          state: r.state,
+          // Never a key, a file's contents or a home path, whatever a tool's files said.
+          ...(r.error ? { error: clip(cleanText(r.error, home), 300) } : {}),
+          ...(r.notes.length ? { notes: r.notes.slice(0, 5).map((n) => clip(cleanText(n, home), 300)) } : {}),
+          remote: r.family.remote === "yes",
+          ...(st.paired && unsent.has(r.id) ? { pending: true as const } : {}),
+        }
+      }),
+    }
+  } catch {
+    return undefined
+  }
 }
 
 /** The computer's name: os.hostname() without ".local". */
@@ -134,6 +223,8 @@ export async function countAndKeep(home: string, o: { timeoutMs?: number; reader
 
 async function memorySummary(home: string, env: Env): Promise<BrainReport["memory"]> {
   try {
+    // Turned off on this computer (brain settings): memory is not used here, whatever is stored.
+    if (!memoryOn(home)) return { available: false }
     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 }
@@ -251,6 +342,7 @@ export async function buildReport(home: string, o: { counts?: Record<string, Too
   const env = o.env ?? process.env
   const counts = o.counts ?? readCache(home).counts?.tools
   const { list, total, byMonth } = readConversions(home, MAX_CONVERSIONS)
+  const settings = await settingsSection(home, env)
   return {
     schema: SCHEMA,
     sentAt: (o.now ?? new Date()).toISOString(),
@@ -260,6 +352,7 @@ export async function buildReport(home: string, o: { counts?: Record<string, Too
     memory: await memorySummary(home, env),
     conversions: list,
     totals: { conversions: total, byMonth },
+    ...(settings ? { settings } : {}),
   }
 }
 

package/src/dashboard/send.ts

@@ -10,7 +10,7 @@
 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 { readCache, readMachineToken, readSettings, updateCache, updateSettings } from "./state.ts"
 import type { BrainReport } from "./report.ts"
 
 /** Where the person sees what was sent. */
@@ -53,6 +53,9 @@ export function safeUrl(url: string): boolean {
 
 export const signedIn = (home: string) => readKey(home).length > 0
 
+/** Whether this computer has a way to send its report: the gateway key, or its own token from `brain pair`. */
+export const canReport = (home: string) => signedIn(home) || !!readMachineToken(home)
+
 /** 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
@@ -101,7 +104,20 @@ export async function sendReport(home: string, report: BrainReport, o: { fetchIm
 
 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)" }
+  // A paired computer sends with its own token (it needs no gateway key); one the account no longer takes (the computer
+  // was removed in the dashboard) falls back to the gateway key, as before pairing.
+  const token = readMachineToken(home)
+  if (!key && !token) return { ok: false, why: "not signed in (brain gateway login)" }
+  if (token) {
+    const r = await postWith(home, report, token, o)
+    if (r.ok || !key || !("status" in r) || (r.status !== 401 && r.status !== 403)) return strip(r)
+  }
+  return strip(await postWith(home, report, key, o))
+}
+
+const strip = (r: SendResult & { status?: number }): SendResult => (r.ok ? r : { ok: false, why: r.why })
+
+async function postWith(home: string, report: BrainReport, key: string, o: { fetchImpl?: typeof fetch; timeoutMs?: number }): Promise<SendResult & { status?: number }> {
   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")
@@ -130,7 +146,7 @@ async function post(home: string, report: BrainReport, o: { fetchImpl?: typeof f
       : 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 }
+    return { ok: false, why: said ? `${why}: ${String(said).slice(0, 200)}` : why, status: res.status }
   } 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)}` }
@@ -154,7 +170,7 @@ export function planPush(p: { lastStartMs?: number; pendingUntilMs?: number }, n
 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
+    if (!canReport(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

package/src/dashboard/state.ts

@@ -1,10 +1,13 @@
 // 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)
+//   machine.json          { id, createdAt, hw }: this machine's random id, made once (the console tells machines apart by
+//                         it), and a hash of the computer's hardware id: a ~/.brain copied to another computer (Migration
+//                         Assistant, dotfiles) gets its own id there, and drops this computer's token (machine.key)
 //   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 { createHash } from "node:crypto"
 import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
 import { dirname, join } from "node:path"
 
@@ -83,13 +86,72 @@ export function updateCache(home: string, change: (c: DashboardCache) => void):
 
 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. */
+/** The computer's own token for the account's settings (written by `brain pair`), 0600. */
+export const machineKeyPath = (home: string) => join(brainDir(home), "machine.key")
+
+/** A computer's token: `100x_brain_` and 43 letters and digits. */
+export const MACHINE_TOKEN = /^100x_brain_[A-Za-z0-9]{43}$/
+
+/** This computer's token, if it is paired (never printed). */
+export function readMachineToken(home: string): string | undefined {
+  try {
+    const t = readFileSync(machineKeyPath(home), "utf8").trim()
+    return MACHINE_TOKEN.test(t) ? t : undefined
+  } catch {
+    return undefined
+  }
+}
+
+let hw: string | null | undefined
+/**
+ * A hash of this computer's hardware id (macOS: IOPlatformUUID; Linux: /etc/machine-id), never the id itself; null where
+ * there is none to read. BRAIN_HW_ID replaces the hardware id (tests). Read once per process.
+ */
+export function hardwareHash(env: Record<string, string | undefined> = process.env): string | null {
+  if (env.BRAIN_HW_ID !== undefined) return env.BRAIN_HW_ID ? createHash("sha256").update(`brain-hw:${env.BRAIN_HW_ID}`).digest("hex") : null
+  if (hw !== undefined) return hw
+  let raw = ""
+  try {
+    if (process.platform === "darwin") {
+      const p = Bun.spawnSync(["ioreg", "-rd1", "-c", "IOPlatformExpertDevice"], { stdout: "pipe", stderr: "ignore", timeout: 3_000 })
+      raw = /"IOPlatformUUID"\s*=\s*"([^"]+)"/.exec(p.stdout.toString())?.[1] ?? ""
+    } else if (process.platform === "linux") {
+      for (const f of ["/etc/machine-id", "/var/lib/dbus/machine-id"]) {
+        try {
+          raw = readFileSync(f, "utf8").trim()
+          if (raw) break
+        } catch {}
+      }
+    }
+  } catch {}
+  hw = raw ? createHash("sha256").update(`brain-hw:${raw}`).digest("hex") : null
+  return hw
+}
+
+/**
+ * This machine's id: made once, kept in <home>/.brain/machine.json. A missing or damaged file gets a new one. A file made on
+ * another computer (its hardware hash differs) gets a new id too, and that computer's token is dropped here: the copy is
+ * a computer of its own, and is paired on its own.
+ */
 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 m = readJson<{ id?: unknown; createdAt?: unknown; hw?: unknown }>(machinePath(home))
+  const here = hardwareHash()
+  if (typeof m.id === "string" && UUID.test(m.id)) {
+    if (!here || m.hw === here) return m.id
+    if (m.hw === undefined) {
+      // Made by a brain before the hardware hash: this computer is taken to be the one that made it.
+      try {
+        writePrivateJson(machinePath(home), { ...m, hw: here })
+      } catch {}
+      return m.id
+    }
+    try {
+      rmSync(machineKeyPath(home), { force: true })
+    } catch {}
+  }
   const id = crypto.randomUUID()
   try {
-    writePrivateJson(machinePath(home), { id, createdAt: new Date().toISOString() })
+    writePrivateJson(machinePath(home), { id, createdAt: new Date().toISOString(), ...(here ? { hw: here } : {}) })
   } catch {}
   return id
 }

package/src/fsutil.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"
+import { chmodSync, existsSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs"
 import { join, resolve } from "node:path"
 import type { Project } from "./session/types.ts"
 
@@ -12,6 +12,24 @@ export const appSupport = (home: string) => join(home, "Library", "Application S
 
 export const exists = (p: string) => existsSync(p)
 
+/**
+ * Replaces a file's content in one step: the text goes to a temporary file beside it (a name no other process uses,
+ * created with `mode` when given, so a private file is never readable by others even for a moment), which then takes the
+ * file's place. A reader sees the old content or the new, never half of it.
+ */
+export function writeAtomic(path: string, text: string, mode?: number): void {
+  const tmp = `${path}.${process.pid}-${Math.random().toString(36).slice(2, 10)}.brain-tmp`
+  // Earlier brains used one fixed name; a copy an interrupted run left there (with whatever mode it had) goes.
+  rmSync(`${path}.brain-tmp`, { force: true })
+  try {
+    writeFileSync(tmp, text, mode === undefined ? {} : { mode })
+    if (mode !== undefined) chmodSync(tmp, mode)
+    renameSync(tmp, path)
+  } finally {
+    rmSync(tmp, { force: true })
+  }
+}
+
 export function isDir(p: string): boolean {
   try {
     return statSync(p).isDirectory()