@100xprompt/brain 0.1.3 → 0.1.4

package/src/settings/cli.ts

@@ -0,0 +1,439 @@
+// `brain settings`, `brain status` and `brain sync`: the command line's way into brain's settings (catalog.ts lists them,
+// apply.ts changes them). The dashboard and, later, the page on this computer are the other ways in; all three see the
+// same settings and the same record of who changed what.
+import { type Env, MODEL_ALIASES, modelName } from "../gateway/common.ts"
+import { type Family, FAMILIES, parseId, showValue, toolName } from "./catalog.ts"
+import { listSettings, type Outcome, reconcile, type Row, rowOf, setSetting, unsetSetting } from "./apply.ts"
+import { type Change, type Entry, readDoc, readSettingsFile, settingsFile } from "./store.ts"
+import { readRecordedEnv } from "./env.ts"
+import { type Exchange, exchange, exchangeState } from "./account.ts"
+
+type Io = { out(l: string): void; err?(l: string): void }
+
+const USAGE = [
+  "brain settings [list] [--tool <id>] [--json]      every setting on this computer: its value, where it comes from, and whether it is applied",
+  "brain settings get <id> [--json]                  one setting, with its levels and recent changes",
+  "brain settings set <id> <value> [--for computer|me]   change it here (default), or for all your computers",
+  "brain settings unset <id> [--for computer|me]     clear it at that level: the value above applies, or brain leaves it as it is",
+  "brain settings history [<id>] [--limit 20]        recent changes, by whom and what each replaced",
+  "brain settings ids                                the settings there are, and who may change each",
+]
+
+const pad = (s: string, n: number) => (s.length >= n ? s : s + " ".repeat(n - s.length))
+
+/** A time for people, in this computer's time zone: 2026-11-11 10:40. */
+export function when(iso: string | undefined): string {
+  const t = iso ? new Date(iso) : undefined
+  if (!t || Number.isNaN(t.getTime())) return ""
+  const z = (n: number) => String(n).padStart(2, "0")
+  return `${t.getFullYear()}-${z(t.getMonth() + 1)}-${z(t.getDate())} ${z(t.getHours())}:${z(t.getMinutes())}`
+}
+
+/** Who made a change or an entry: a command, `brain settings`, the dashboard, the team admin. */
+export function by(e: Pick<Entry, "source" | "command">): string {
+  switch (e.source) {
+    case "command":
+      return e.command ? `\`${e.command}\`` : "a brain command"
+    case "settings":
+      return "`brain settings`"
+    case "dashboard":
+      return "the dashboard"
+    case "admin":
+      return "your team admin"
+    case "local-page":
+      return "the page on this computer"
+  }
+}
+
+function fromText(r: Row): string {
+  switch (r.from) {
+    case "lock":
+      return "locked by your team admin"
+    case "computer":
+      return `this computer, by ${by(r.entry!)} ${when(r.entry!.at)}`
+    case "person":
+      return `all your computers, by ${by(r.entry!)} ${when(r.entry!.at)}`
+    case "team":
+      return "your team's default"
+    case "default":
+      return "brain's default"
+    case "none":
+      return "as found (not set)"
+  }
+}
+
+function stateText(r: Row): string {
+  switch (r.state) {
+    case "applied":
+    case "default":
+    case "as found":
+      return r.state === "applied" && r.from !== "default" ? "applied" : ""
+    case "waiting":
+      return "waiting to be applied (brain sync)"
+    case "failed":
+      return `failed: ${r.error ?? "unknown reason"}`
+    case "changed outside brain":
+      return `changed outside brain: it is ${showValue(r.family.type, r.actual.value)} now`
+    case "can't read":
+      return `can't read it${r.notes[0] ? `: ${r.notes[0]}` : ""}`
+    case "locked":
+      return "locked"
+    default:
+      return r.state
+  }
+}
+
+/** The value a row shows: what applies, or (not set) what this computer has. */
+const shown = (r: Row) => showValue(r.family.type, r.value !== undefined ? r.value : r.actual.value)
+
+function printRows(rows: Row[], io: Io) {
+  const idw = Math.max(...rows.map((r) => r.id.length), 10) + 2
+  const vw = Math.max(...rows.map((r) => shown(r).length), 5) + 2
+  const groups = new Map<string, Row[]>()
+  for (const r of rows) {
+    const g = r.tool ? `${toolName(r.tool)} (${r.tool})` : "brain"
+    groups.set(g, [...(groups.get(g) ?? []), r])
+  }
+  const order = [...groups.keys()].sort((a, b) => (a === "brain" ? 1 : b === "brain" ? -1 : a.localeCompare(b)))
+  for (const [i, g] of order.entries()) {
+    if (i) io.out("")
+    io.out(g)
+    for (const r of groups.get(g)!) {
+      const st = stateText(r)
+      io.out(`  ${pad(r.id, idw)}${pad(shown(r), vw)}${fromText(r)}${st ? `  [${st}]` : ""}`)
+      if (["failed", "changed outside brain"].includes(r.state)) for (const n of r.notes) io.out(`  ${" ".repeat(idw)}note: ${n}`)
+    }
+  }
+}
+
+const rowJson = (r: Row) => ({
+  id: r.id,
+  ...(r.tool ? { tool: r.tool } : {}),
+  value: r.value ?? null,
+  from: r.from,
+  ...(r.entry ? { entry: r.entry } : {}),
+  // A model brain has no short name for is "other": people never see the gateway's model ids.
+  actual: r.family.type.kind === "choice" && typeof r.actual.value === "string" && r.actual.value !== "partly" && !r.family.type.choices.includes(r.actual.value) ? "other" : r.actual.value,
+  state: r.state,
+  ...(r.error ? { error: r.error } : {}),
+  ...(r.notes.length ? { notes: r.notes } : {}),
+})
+
+function changeLine(c: Change, type?: Family["type"]): string {
+  const v = c.value === null ? "cleared" : type ? showValue(type, c.value) : String(c.value)
+  const where = c.level === "computer" ? "this computer" : c.level === "person" ? "all your computers" : "team default"
+  const rep = c.replaced ? `; replaced ${type ? showValue(type, c.replaced.value) : String(c.replaced.value)} set by ${by(c.replaced)} ${when(c.replaced.at)}` : ""
+  return `${when(c.at)}  ${c.id} = ${v}  (${where}, by ${by(c)}${rep})`
+}
+
+function printOutcome(o: Outcome, io: Io, verb: string): number {
+  if (o.refused) {
+    io.out(`brain settings: ${o.refused}`)
+    return 1
+  }
+  if (o.row) {
+    const r = o.row
+    const st = stateText(r)
+    io.out(`${r.id} = ${shown(r)}  (${fromText(r)})${st ? `  ${st}` : ""}`)
+    if (r.state === "failed") io.out(`  ${verb}, but not applied; \`brain sync\` tries again`)
+    if (o.change?.replaced) io.out(`  replaced ${showValue(r.family.type, o.change.replaced.value)}, set by ${by(o.change.replaced)} ${when(o.change.replaced.at)}`)
+    for (const n of r.notes) io.out(`  note: ${n}`)
+  }
+  for (const n of o.notes) io.out(`  ${n}`)
+  return o.ok ? 0 : 1
+}
+
+function levelFlag(args: string[]): "computer" | "person" | { error: string } {
+  const i = args.indexOf("--for")
+  if (i < 0) return "computer"
+  const v = args[i + 1]
+  if (v === "computer" || v === "this") return "computer"
+  if (v === "me" || v === "all" || v === "person") return "person"
+  return { error: "--for takes computer (this computer, the default) or me (all your computers)" }
+}
+
+/** One line on an exchange with the account, when it did something or failed (nothing on a computer that is not paired). */
+export function exchangeLines(x: Exchange, waiting: number): string[] {
+  if (!x.paired) return []
+  const n = (k: number, one: string) => `${k} ${one}${k === 1 ? "" : "s"}`
+  if (!x.ok) return [`account: not reached (${x.why})${waiting ? `; ${n(waiting, "change")} made here wait to be sent` : ""}`]
+  const parts: string[] = []
+  if (x.sent) parts.push(`sent ${n(x.sent, "change")} made here`)
+  if (x.received.length) parts.push(`${n(x.received.length, "change")} from your account taken${x.applied.length ? `, ${x.applied.length} applied here` : ""}`)
+  if (x.refused.length) parts.push(`refused by your account: ${x.refused.map((r) => `${r.id} (${r.message || r.code})`).join(", ")}`)
+  for (const h of x.held) parts.push(`${h.id} not taken here: ${h.why}`)
+  return parts.length ? [`account: ${parts.join("; ")}`] : []
+}
+
+/** Exchanges with the account when this computer is paired (within `deadline`: 3 s for the whole command), and says what that did. */
+async function withAccount(home: string, env: Env, say: (l: string) => void, fetchImpl: typeof fetch | undefined, deadline: number): Promise<Exchange | undefined> {
+  if (Date.now() >= deadline) return undefined
+  const x = await exchange(home, { env, timeoutMs: deadline - Date.now(), ...(fetchImpl ? { fetchImpl } : {}) })
+  for (const l of exchangeLines(x, exchangeState(home).waiting)) say(l)
+  return x
+}
+
+/**
+ * `brain settings ...`. `hooks.changed` is called when a set or unset saved something (the dashboard report is sent then,
+ * not after a refusal). A paired computer exchanges with the account first (and, after a change, again).
+ */
+export async function settingsCommand(
+  args: string[],
+  home: string,
+  io: Io = { out: (l) => console.log(l) },
+  env: Env = process.env,
+  hooks: { changed?: () => void; fetchImpl?: typeof fetch } = {},
+): Promise<number> {
+  // Options alone (`brain settings --json`, `--tool codex`) mean list.
+  const [sub = "list", ...rest] = !args[0] || args[0].startsWith("--") ? ["list", ...args] : args
+  const words = rest.filter((a, i) => !a.startsWith("--") && !["--for", "--limit", "--tool"].includes(rest[i - 1] ?? ""))
+  const json = rest.includes("--json")
+  // With --json the output must stay JSON: notes go to stderr.
+  const note = (l: string) => (json ? (io.err ?? ((x: string) => process.stderr.write(`${x}\n`))) : io.out)(l)
+  const file = readSettingsFile(home)
+  if (file.problem === "newer") note(`note: ${settingsFile(home)} was written by a newer brain; values are shown as this brain reads them, and cannot be changed or applied here`)
+  if (file.problem === "damaged") note(`note: ${settingsFile(home)} could not be read: brain's defaults apply (memory counts as off), and it is kept aside on the next change`)
+  // What the account changed is taken (and applied) before anything is shown or changed here; the whole command keeps to 3 s.
+  const deadline = Date.now() + 3_000
+  if (["list", "get", "history", "set", "unset"].includes(sub) && !file.problem) await withAccount(home, env, note, hooks.fetchImpl, deadline)
+  switch (sub) {
+    case "list": {
+      const ti = rest.indexOf("--tool")
+      const tool = ti >= 0 ? rest[ti + 1] : undefined
+      let rows = await listSettings(home, env)
+      if (tool) {
+        const { canonicalTool } = await import("./catalog.ts")
+        const t = canonicalTool(tool)
+        rows = rows.filter((r) => r.tool === t)
+        if (!rows.length) {
+          io.out(`no settings for "${tool}" on this computer`)
+          return 1
+        }
+      }
+      if (json) io.out(JSON.stringify(rows.map(rowJson), null, 1))
+      else {
+        printRows(rows, io)
+        io.out("")
+        io.out("change one: brain settings set <id> <value>   (brain settings get <id> says more)")
+      }
+      return 0
+    }
+    case "get": {
+      const ref = parseId(words[0] ?? "")
+      if (!words[0] || "error" in ref) {
+        io.out(words[0] ? `brain settings: ${(ref as { error: string }).error}` : `usage: ${USAGE[1]}`)
+        return words[0] ? 1 : 2
+      }
+      const doc = readDoc(home)
+      const r = await rowOf({ home, env, doc }, ref)
+      if (json) {
+        io.out(JSON.stringify({ ...rowJson(r), levels: { computer: doc.levels.computer[r.id] ?? null, person: doc.levels.person[r.id] ?? null, team: doc.levels.team[r.id] ?? null }, lock: doc.locks[r.id] ?? null, history: doc.history.filter((c) => c.id === r.id).slice(-10) }, null, 1))
+        return 0
+      }
+      const f = r.family
+      const st = stateText(r)
+      io.out(`${r.id} = ${shown(r)}`)
+      io.out(`  what: ${f.help}`)
+      io.out(`  from: ${fromText(r)}`)
+      io.out(`  on this computer now: ${showValue(f.type, r.actual.value)}${st ? ` (${st})` : ""}`)
+      io.out(`  levels: ${(["computer", "person", "team"] as const).map((l) => `${l === "computer" ? "this computer" : l === "person" ? "all your computers" : "team default"} ${showValue(f.type, doc.levels[l][r.id]?.value)}`).join("; ")}${doc.locks[r.id] ? `; locked to ${showValue(f.type, doc.locks[r.id]!.value)}` : ""}`)
+      io.out(`  type: ${f.type.kind === "bool" ? "on or off" : f.type.kind === "choice" ? f.type.choices.join(", ") : `${f.type.min.toLocaleString("en-US")} to ${f.type.max.toLocaleString("en-US")} ${f.type.unit}`}${f.default !== undefined ? `; default ${showValue(f.type, f.default)}` : ""}`)
+      io.out(`  changed with: \`brain settings\` on this computer${f.remote === "yes" ? "" : " (it stays a this-computer-only setting)"}`)
+      for (const n of r.notes) io.out(`  note: ${n}`)
+      const hist = doc.history.filter((c) => c.id === r.id).slice(-5)
+      if (hist.length) {
+        io.out("  recent changes:")
+        for (const c of hist) io.out(`    ${changeLine(c, f.type)}`)
+      }
+      return 0
+    }
+    case "set":
+    case "unset": {
+      const level = levelFlag(rest)
+      if (typeof level === "object") {
+        io.out(level.error)
+        return 2
+      }
+      if (sub === "set" ? words.length !== 2 : words.length !== 1) {
+        io.out(`usage: ${USAGE[sub === "set" ? 2 : 3]}`)
+        return 2
+      }
+      const o = sub === "set" ? await setSetting(home, words[0]!, words[1]!, { level, env }) : await unsetSetting(home, words[0]!, { level, env })
+      if (o.change) hooks.changed?.()
+      const code = printOutcome(o, io, sub === "set" ? "saved" : "cleared")
+      // The change goes to the account at once.
+      if (o.change) await withAccount(home, env, io.out, hooks.fetchImpl, deadline)
+      return code
+    }
+    case "history": {
+      const li = rest.indexOf("--limit")
+      const limit = li >= 0 ? Math.max(1, Number(rest[li + 1]) || 20) : 20
+      const ref = words[0] ? parseId(words[0]) : undefined
+      if (ref && "error" in ref) {
+        io.out(`brain settings: ${ref.error}`)
+        return 1
+      }
+      const doc = readDoc(home)
+      const hist = doc.history.filter((c) => !ref || c.id === ref.id).slice(-limit)
+      if (!hist.length) io.out("no changes recorded yet")
+      for (const c of hist) {
+        const r = parseId(c.id)
+        io.out(changeLine(c, "error" in r ? undefined : r.family.type))
+      }
+      return 0
+    }
+    case "ids": {
+      for (const f of FAMILIES) {
+        const type = f.type.kind === "bool" ? "on/off" : f.type.kind === "choice" ? f.type.choices.join("|") : `${f.type.min}-${f.type.max} ${f.type.unit}`
+        io.out(`${pad(f.key.replace("*", "<tool>"), 26)}${pad(type, 30)}${f.label}${f.remote === "no" ? " (this computer only)" : ""}`)
+      }
+      io.out("")
+      io.out(`<tool>: a tool's id, as \`brain settings list\` shows it (claude-code, codex, cursor-ide, gemini-cli, ...)`)
+      return 0
+    }
+    case "help":
+    case "--help":
+    case "-h":
+      USAGE.forEach((l) => io.out(l))
+      return 0
+    default:
+      io.out(`unknown settings command "${sub}"`)
+      USAGE.forEach((l) => io.out(`usage: ${l}`))
+      return 2
+  }
+}
+
+// ---- brain status -------------------------------------------------------------------------------------------------------
+
+const ago = (iso: string | undefined) => {
+  const t = iso ? Date.parse(iso) : NaN
+  if (!Number.isFinite(t)) return ""
+  const m = Math.max(0, Math.round((Date.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`
+}
+
+/** A model by its 100xprompt name (100xprompt Pro), never the gateway's id. */
+const productName = (alias: unknown) => (typeof alias === "string" && MODEL_ALIASES[alias] ? modelName(MODEL_ALIASES[alias]!) : "another model")
+
+/**
+ * `brain status`: this computer at a glance, with whether its settings are applied. On a paired computer it first exchanges
+ * with the account (so a change made in the dashboard is taken and applied); otherwise it only reads.
+ */
+export async function statusCommand(home: string, io: Io = { out: (l) => console.log(l) }, env: Env = process.env, deps: { fetchImpl?: typeof fetch } = {}): Promise<number> {
+  const exchanged = readSettingsFile(home).problem ? undefined : await exchange(home, { env, ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}) })
+  const { VERSION } = await import("../self.ts")
+  const { machineName, gatewayState } = await import("../dashboard/report.ts")
+  const { machineId, readCache } = await import("../dashboard/state.ts")
+  const { canReport, gatewayUrl, sendingOff, signedIn } = await import("../dashboard/send.ts")
+  const { readOrgConfig } = await import("../org/config.ts")
+  const { leanSettings, memoryOn } = await import("./values.ts")
+  const { chittaCandidates, memoryDbPath } = await import("../memory/store.ts")
+  const { existsSync } = await import("node:fs")
+  const file = readSettingsFile(home)
+  const doc = file.doc
+  const rows = await listSettings(home, env)
+  const email = gatewayState(home).email
+
+  io.out(`brain ${VERSION} on ${machineName()} (machine ${machineId(home).slice(0, 8)})`)
+  if (file.problem === "damaged") io.out(`note: ${settingsFile(home)} could not be read: brain's defaults apply and memory counts as off until it is fixed (\`brain settings set\` writes a new one)`)
+  if (file.problem === "newer") io.out(`note: ${settingsFile(home)} was written by a newer brain: update brain to change or apply settings here`)
+  io.out(`gateway: ${signedIn(home) ? `signed in${typeof email === "string" && email ? ` as ${email}` : ""} (${gatewayUrl(home)})` : "not signed in (brain gateway login)"}`)
+  const off = sendingOff(home, env)
+  const push = readCache(home).push ?? {}
+  io.out(`reports: ${off ? `off (${off})` : canReport(home) ? `on${push.lastSentAt ? `, last sent ${ago(push.lastSentAt)}` : ", none sent yet"}${push.lastError ? `; the last attempt failed: ${push.lastError}` : ""}` : "on, once you sign in"}`)
+  const org = env.BRAIN_ORG !== "off" && readOrgConfig(home)
+  // On, and usable: the team's server, or this computer's own store (which needs Chitta, as `brain memory status` says).
+  const local = existsSync(memoryDbPath(home)) || chittaCandidates().some((f) => existsSync(f))
+  io.out(`memory: ${!memoryOn(home) ? `off${file.problem === "damaged" ? " (the settings file cannot be read)" : " (brain settings: memory.enabled)"}` : org ? `on, kept on your team's server (${org.server})` : local ? "on, kept on this computer" : "on, but not available here (Chitta is not installed: brain memory status)"}`)
+  const lean = leanSettings(home, doc)
+  io.out(`lean: ${lean.auto ? `automatic from ${lean.threshold.toLocaleString("en-US")} tokens` : "only with --lean (lean.auto off)"}; outputs over ${lean.minChars.toLocaleString("en-US")} characters become digests`)
+
+  // Each tool with something from brain: on the gateway, brain's tools, or the session hook.
+  const byTool = new Map<string, Row[]>()
+  for (const r of rows) if (r.tool) byTool.set(r.tool, [...(byTool.get(r.tool) ?? []), r])
+  const part = (rs: Row[], key: string) => rs.find((r) => r.family.key === `tools.*.${key}`)
+  const on = (r?: Row) => r?.actual.value === true || r?.actual.value === "partly"
+  const active = [...byTool.entries()].filter(([, rs]) => ["gateway", "mcp", "hooks"].some((k) => on(part(rs, k)))).sort((a, b) => toolName(a[0]).localeCompare(toolName(b[0])))
+  if (active.length) {
+    io.out("tools:")
+    const w = Math.max(...active.map(([t]) => toolName(t).length)) + 2
+    for (const [t, rs] of active) {
+      const g = part(rs, "gateway")
+      const m = part(rs, "model")
+      const ce = part(rs, "contextEdit")
+      const bits = [
+        g ? `gateway ${g.actual.value === true ? `on (${productName(m?.actual.value)}${ce?.actual.value === false ? ", context editing off" : ""})` : g.actual.value === "partly" ? "partly on" : "off"}` : "",
+        part(rs, "mcp") ? `brain tools ${on(part(rs, "mcp")) ? "on" : "off"}` : "",
+        part(rs, "hooks") ? `hook ${on(part(rs, "hooks")) ? "on" : "off"}` : "",
+      ].filter(Boolean)
+      io.out(`  ${pad(toolName(t), w)}${bits.join(", ")}`)
+    }
+  }
+  const quiet = byTool.size - active.length
+  if (quiet > 0) io.out(`${active.length ? "  and" : "tools:"} ${quiet} more tool${quiet === 1 ? "" : "s"} here with nothing from brain (brain settings list shows every setting)`)
+
+  const set = rows.filter((r) => r.from === "computer" || r.from === "person" || r.from === "team" || r.from === "lock")
+  // A value for all the person's computers, for a tool not on this one, is for the others: not a problem here.
+  const elsewhere = rows.filter((r) => r.state === "not on this computer" && r.from !== "computer")
+  const failed = rows.filter((r) => r.state === "failed" || (r.state === "not on this computer" && r.from === "computer"))
+  const drifted = rows.filter((r) => r.state === "changed outside brain")
+  const unreadable = rows.filter((r) => r.state === "can't read" && r.from !== "none")
+  const waiting = rows.filter((r) => r.state === "waiting")
+  const problems = failed.length + drifted.length + unreadable.length + waiting.length
+  io.out(`settings: ${set.length} set${problems ? "" : set.length ? ", all applied" : " (brain's defaults and the tools as they are)"}${failed.length ? `; ${failed.length} not applied` : ""}${drifted.length ? `; ${drifted.length} changed outside brain` : ""}${unreadable.length ? `; ${unreadable.length} can't be read` : ""}${waiting.length ? `; ${waiting.length} waiting (brain sync)` : ""}${elsewhere.length ? `; ${elsewhere.length} for tools on your other computers` : ""}`)
+  for (const r of failed) io.out(`  ${r.id}: ${r.state === "failed" ? `failed: ${r.error}` : "not on this computer"}`)
+  for (const r of unreadable) io.out(`  ${r.id}: can't read it${r.notes[0] ? ` (${r.notes[0]})` : ""}`)
+  for (const r of drifted) io.out(`  ${r.id}: brain set ${showValue(r.family.type, r.value)}, it is ${showValue(r.family.type, r.actual.value)} now${r.notes[0] ? ` (${r.notes[0]})` : ""}`)
+  const acct = exchangeState(home)
+  const waitingNote = acct.waiting ? `; ${acct.waiting} change${acct.waiting === 1 ? "" : "s"} made here wait to be sent` : ""
+  if (!acct.paired) io.out(`account: not paired (\`brain pair\` shows this computer's settings in your dashboard)${waitingNote}`)
+  else io.out(`account: paired, last exchange ${acct.lastSyncAt ? ago(acct.lastSyncAt) : "never"}${acct.lastError ? `; the last attempt failed: ${acct.lastError}` : ""}${waitingNote}`)
+  if (exchanged) for (const l of exchangeLines(exchanged, acct.waiting).filter((l) => !/not reached/.test(l))) io.out(`  ${l.replace(/^account: /, "")}`)
+  for (const h of acct.held) io.out(`  ${h.id}: not taken from your account: ${h.why}`)
+  const refused = acct.refused.slice(-3)
+  if (refused.length) io.out(`  refused by your account (this computer went back to its value): ${refused.map((r) => `${r.id} = ${String(r.value)} (${r.message || r.code})`).join("; ")}`)
+  const recorded = readRecordedEnv(home)
+  // As the code that obeys them reads them: BRAIN_NO_REPORT anything but empty, 0 or false; BRAIN_NO_MEMORY exactly 1.
+  const envOff = [...(off && /BRAIN_NO_REPORT/.test(off) ? ["BRAIN_NO_REPORT"] : []), ...(env.BRAIN_NO_MEMORY === "1" ? ["BRAIN_NO_MEMORY"] : [])]
+  if (envOff.length || env.BRAIN_ORG === "off") io.out(`environment: ${[...envOff, ...(env.BRAIN_ORG === "off" ? ["BRAIN_ORG=off"] : [])].join(", ")} set in this shell`)
+  if (recorded) io.out(`tool folders: as your shell had them ${when(recorded.recordedAt)}`)
+  return 0
+}
+
+// ---- brain sync ---------------------------------------------------------------------------------------------------------
+
+/**
+ * `brain sync`: applies the settings whose value changed since brain last applied them, tries again those that failed,
+ * and sends this computer's report now. (With the dashboard's settings it will also send changes made here and fetch
+ * those made there.)
+ */
+export async function syncCommand(home: string, io: Io = { out: (l) => console.log(l) }, env: Env = process.env, deps: { fetchImpl?: typeof fetch } = {}): Promise<number> {
+  // With the account first (what changed there is taken and applied), then everything that changed or failed here.
+  const x = await exchange(home, { env, ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}) })
+  if (!x.paired) io.out("account: not paired (`brain pair` shows this computer's settings in your dashboard)")
+  else {
+    const lines = exchangeLines(x, exchangeState(home).waiting)
+    io.out(lines.length ? lines.join("\n") : "account: in step with your account")
+  }
+  const r = await reconcile(home, { env, retryFailed: true })
+  const bad = r.applied.filter((x) => x.state === "failed" || x.state === "not on this computer" || x.state === "can't read")
+  const good = r.applied.filter((x) => !bad.includes(x))
+  if (!r.applied.length) io.out("settings: nothing to apply; everything set here is applied")
+  else io.out(`settings: applied ${good.length}${bad.length ? `, ${bad.length} not` : ""}`)
+  for (const x of good) io.out(`  ${x.id} = ${showValue(x.family.type, x.value)}`)
+  for (const x of bad) io.out(`  ${x.id}: ${x.state === "failed" ? `failed: ${x.error}` : "not on this computer"}`)
+  for (const id of r.unknown) io.out(`  ${id}: not a setting this brain knows; left alone`)
+  if (r.elsewhere.length) io.out(`  ${r.elsewhere.length} for tools not on this computer (kept for your other computers): ${r.elsewhere.join(", ")}`)
+
+  const { canReport, gatewayUrl, noticeOnce, sendingOff, sendReport } = await import("../dashboard/send.ts")
+  const off = sendingOff(home, env)
+  if (!canReport(home)) io.out("report: not sent (not signed in: brain gateway login)")
+  else if (off) io.out(`report: not sent (${off})`)
+  else {
+    noticeOnce(home, io.out)
+    const { buildReport } = await import("../dashboard/report.ts")
+    const sent = await sendReport(home, await buildReport(home, { env }), { timeoutMs: 5_000, ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}) })
+    io.out(sent.ok ? `report: sent to ${gatewayUrl(home)}` : `report: not sent (${sent.why})`)
+  }
+  return bad.length || (x.paired && !x.ok) ? 1 : 0
+}

package/src/settings/env.ts

@@ -0,0 +1,101 @@
+// <home>/.brain/env.json: the environment variables that decide where the person's coding tools keep their files, and
+// brain's own opt-outs, as the person's shell has them. A background brain (started by launchd or systemd, later) does not
+// get the person's shell: without this it would edit ~/.claude/settings.json while the person's Claude Code reads
+// $CLAUDE_CONFIG_DIR, and it would send reports the person turned off with BRAIN_NO_REPORT.
+//
+// Recorded by the commands a person runs, never by the ones tools or brain start on their own (the session hook,
+// `brain mcp serve`, background pushes and memory syncs): those run with the tool's environment, not the person's.
+// Only the names below are kept, never anything else (no keys, no tokens); the file is 0600 and stays on this computer.
+import { join } from "node:path"
+import { mkdirSync, readFileSync } from "node:fs"
+import { writeAtomic } from "../fsutil.ts"
+
+export const envFile = (home: string) => join(home, ".brain", "env.json")
+
+/** Where tools keep their files (what brain's connectors, installers and readers look at), and brain's opt-outs. */
+export const ENV_VARS = [
+  "PATH",
+  "XDG_CONFIG_HOME",
+  "XDG_DATA_HOME",
+  "XDG_STATE_HOME",
+  "XDG_CACHE_HOME",
+  "APPDATA",
+  "CLAUDE_CONFIG_DIR",
+  "CODEX_HOME",
+  "GEMINI_CLI_HOME",
+  "HUNDREDXPROMPT_HOME",
+  "COPILOT_HOME",
+  "COPILOT_PROVIDERS_CONFIG",
+  "CONTINUE_GLOBAL_DIR",
+  "CRUSH_GLOBAL_DATA",
+  "FACTORY_HOME",
+  "GOOSE_PATH_ROOT",
+  "GROK_HOME",
+  "HERMES_HOME",
+  "IFLOW_HOME",
+  "KIMI_CODE_HOME",
+  "LETTA_CONFIG_DIR",
+  "LETTA_EXTENSIONS_DIR",
+  "LETTA_MODS_DIR",
+  "MASTRA_APP_DATA_DIR",
+  "OMP_PROFILE",
+  "PI_CONFIG_DIR",
+  "PI_PROFILE",
+  "QWEN_HOME",
+  "VIBE_HOME",
+  "BUN_INSTALL",
+  "BRAIN_CHITTA",
+  "BRAIN_CHITTA_DIRS",
+  "BRAIN_NO_REPORT",
+  "BRAIN_NO_MEMORY",
+  "BRAIN_ORG",
+] as const
+
+export interface RecordedEnv {
+  /** When these values were first seen (the file is rewritten only when one changes). */
+  recordedAt: string
+  vars: Record<string, string>
+}
+
+export function readRecordedEnv(home: string): RecordedEnv | undefined {
+  try {
+    const j = JSON.parse(readFileSync(envFile(home), "utf8"))
+    if (!j || typeof j !== "object" || typeof j.vars !== "object" || !j.vars) return undefined
+    const vars: Record<string, string> = {}
+    for (const k of ENV_VARS) if (typeof j.vars[k] === "string") vars[k] = j.vars[k]
+    return { recordedAt: typeof j.recordedAt === "string" ? j.recordedAt : "", vars }
+  } catch {
+    return undefined
+  }
+}
+
+/** Keeps the person's current values of ENV_VARS (a variable no longer set is dropped). Best effort, never throws. */
+export function recordEnv(home: string, env: Record<string, string | undefined> = process.env): boolean {
+  try {
+    const vars: Record<string, string> = {}
+    for (const k of ENV_VARS) {
+      const v = env[k]
+      // PATH often lists the same folders many times (each shell startup adds them again): kept once each, in order.
+      if (typeof v === "string" && v !== "") vars[k] = k === "PATH" ? [...new Set(v.split(":"))].join(":") : v
+    }
+    const had = readRecordedEnv(home)
+    if (had && JSON.stringify(had.vars) === JSON.stringify(vars)) return false
+    mkdirSync(join(home, ".brain"), { recursive: true, mode: 0o700 })
+    writeAtomic(envFile(home), `${JSON.stringify({ recordedAt: new Date().toISOString(), vars }, null, 1)}\n`, 0o600)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Whether a command line is one a person runs (so its environment is theirs), not one a tool or brain started. */
+export function isPersonsCommand(argv: string[]): boolean {
+  const [cmd, ...rest] = argv
+  if (!cmd || ["--help", "-h", "help", "--version", "-v", "version"].includes(cmd)) return false
+  // The session hook (run by a tool), the MCP server (started by a tool), and the background children brain starts.
+  if (cmd === "hook" || (cmd === "session" && rest[0] === "hook")) return false
+  if (cmd === "mcp" && rest[0] === "serve") return false
+  if (cmd === "dashboard" && rest[0] === "push" && (rest.includes("--quiet") || rest.includes("--at"))) return false
+  if (cmd === "memory" && rest[0] === "sync" && rest.includes("--quiet")) return false
+  return true
+}

package/src/settings/pair.ts

@@ -0,0 +1,83 @@
+// `brain pair [--no-browser] | status | forget`: gives this computer its own token for the person's 100xprompt account, so
+// its settings show in the dashboard (and, from step 3, can be changed there). The person approves the computer in the
+// browser, signed in to their account (docs/settings-contract.md, section 1); the token comes back to a one-use server on
+// 127.0.0.1, as `brain gateway login` does it, and is kept in ~/.brain/machine.key (0600). Never printed.
+import { machineName } from "../dashboard/report.ts"
+import { hardwareHash, MACHINE_TOKEN, machineId, readMachineToken } from "../dashboard/state.ts"
+import type { Env } from "../gateway/common.ts"
+import { askHidden, type BrowserFlow, browserSignIn, type SignInDeps } from "../gateway/signin.ts"
+import { exchange, exchangeState, forgetMachineToken, sendAllAgain, storeMachineToken } from "./account.ts"
+import { exchangeLines } from "./cli.ts"
+
+type Io = { out(l: string): void }
+
+/** The approve page's round trip: /auth/brain, told which computer it is approving; a computer token comes back. */
+export function pairFlow(machine: string, name: string, hw: string | null): BrowserFlow {
+  return {
+    command: "brain pair",
+    path: "/auth/brain",
+    params: { machine, name, ...(hw ? { hw } : {}) },
+    accept: (t) => (MACHINE_TOKEN.test(t.trim()) ? { ok: true, key: t.trim() } : { ok: false, why: "that is not this computer's code from the approve page (it starts with 100x_brain_)" }),
+    opening: "approve this computer in your 100xprompt account",
+    done: () => ({ title: "Computer approved", body: "brain on this computer is now paired with your 100xprompt account. You can close this tab and go back to your terminal." }),
+    paste: "Paste the code from the page's Copy button, or the address the browser could not open",
+  }
+}
+
+const USAGE = [
+  "brain pair [--no-browser]   approve this computer in your 100xprompt account, so its settings show in the dashboard",
+  "brain pair status           whether this computer is paired, and its last exchange with the account",
+  "brain pair forget           forget this computer's token here (remove the computer in the dashboard to revoke it there)",
+]
+
+export async function pairCommand(args: string[], home: string, io: Io = { out: (l) => console.log(l) }, deps: { env?: Env; fetchImpl?: typeof fetch; signIn?: Partial<SignInDeps> } = {}): Promise<number> {
+  const sub = args.find((a) => !a.startsWith("-"))
+  if (args.includes("--help") || args.includes("-h") || sub === "help") {
+    USAGE.forEach((l) => io.out(l))
+    return 0
+  }
+  if (sub === "status") {
+    const st = exchangeState(home)
+    io.out(`paired: ${st.paired ? "yes" : "no (brain pair)"}`)
+    io.out(`computer: ${machineName()} (${machineId(home)})`)
+    if (st.paired) {
+      io.out(`last exchange: ${st.lastSyncAt ?? "never"}${st.lastError ? `; the last attempt failed: ${st.lastError}` : ""}`)
+      io.out(`changes waiting to be sent: ${st.waiting}`)
+      for (const r of st.refused.slice(-5)) io.out(`refused by your account: ${r.id} = ${String(r.value)} (${r.message || r.code})`)
+    }
+    return 0
+  }
+  if (sub === "forget") {
+    io.out(forgetMachineToken(home) ? "forgot this computer's token here. To revoke it on your account too, remove this computer in the dashboard's Brain view." : "this computer is not paired; nothing to forget")
+    return 0
+  }
+  if (sub) {
+    io.out(`unknown pair command "${sub}"`)
+    USAGE.forEach((l) => io.out(`usage: ${l}`))
+    return 2
+  }
+  const machine = machineId(home)
+  const r = await browserSignIn(
+    { say: io.out, ask: process.stdin.isTTY ? askHidden : undefined, browser: !args.includes("--no-browser"), ...deps.signIn },
+    pairFlow(machine, machineName(), hardwareHash()),
+  )
+  if (!r.ok) {
+    io.out(`brain pair: ${r.why}`)
+    return 1
+  }
+  const had = !!readMachineToken(home)
+  storeMachineToken(home, r.key)
+  // The account knows this computer afresh (a first pairing, or again after it was removed): everything set here goes up.
+  sendAllAgain(home)
+  // Checked at once, by sending what was changed here and fetching what the account has.
+  const x = await exchange(home, { timeoutMs: 8_000, ...(deps.env ? { env: deps.env } : {}), ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}) })
+  if (!x.ok && /no longer takes this computer's token|refused this exchange/.test(x.why ?? "")) {
+    forgetMachineToken(home)
+    io.out(`brain pair: the account did not accept the token (${x.why}); nothing was kept`)
+    return 1
+  }
+  io.out(`paired${had ? " again" : ""}: ${machineName()} is linked to your 100xprompt account; its token is in ~/.brain/machine.key (readable only by you).`)
+  io.out(x.ok ? `settings: ${x.sent} change${x.sent === 1 ? "" : "s"} made here sent to your account; the dashboard's Brain view shows this computer's settings.` : `settings: not exchanged yet (${x.why}); \`brain sync\` tries again.`)
+  if (x.ok) for (const l of exchangeLines({ ...x, sent: 0 }, 0)) io.out(l)
+  return 0
+}