@100xprompt/brain 0.1.3 → 0.1.4

package/src/memory/sync.ts

@@ -10,6 +10,7 @@ import { distill } from "./distill.ts"
 import { projectKey } from "./project.ts"
 import { openMemory } from "./store.ts"
 import type { Memory } from "./types.ts"
+import { MEMORY_OFF, memoryOn } from "../settings/values.ts"
 
 export interface SessionSource {
   /** Portable id (`<tool>:<id>`). */
@@ -112,6 +113,7 @@ export async function syncMemory(o: SyncOptions, deps: { memory?: Memory; sessio
   const result: SyncResult = { ingested: 0, items: 0, upToDate: 0, deferred: 0, errors: [], ms: 0 }
   const done = (): SyncResult => ({ ...result, ms: now() - t0 })
 
+  if (!memoryOn(o.home)) return { ...done(), unavailable: MEMORY_OFF }
   const memory = deps.memory ?? openMemory(o.home)
   const status = await memory.status().catch((e: Error) => ({ available: false as const, why: e.message }))
   if (!status.available) return { ...done(), unavailable: status.why ?? "unavailable" }
@@ -156,6 +158,7 @@ export async function syncMemory(o: SyncOptions, deps: { memory?: Memory; sessio
 export function syncInBackground(home: string, cwd: string, cli: string) {
   if (process.env.BRAIN_NO_MEMORY === "1") return
   try {
+    if (!memoryOn(home)) return
     // Only where memory has been set up on this machine: a person who never used it does not get a store created by a hook.
     if (!existsSync(join(home, ".brain", "memory"))) return
     const child = Bun.spawn([process.execPath, cli, "memory", "sync", "--here", "--quiet"], { cwd, stdin: "ignore", stdout: "ignore", stderr: "ignore", env: { ...process.env, BRAIN_HOME: home } })

package/src/settings/account.ts

@@ -0,0 +1,336 @@
+// Exchanging settings with the person's 100xprompt account (docs/settings-contract.md, section 5). A paired computer has
+// its own token (~/.brain/machine.key, from `brain pair`); model API keys never read or change settings.
+//
+//   1. send the outbox: what was changed here, one PATCH per level (this computer, all your computers). Accepted and
+//      refused changes leave it; refused ones are kept to be shown, and the account's value then applies again.
+//   2. fetch what the account has (GET, with the revision last seen: "unchanged" costs nothing).
+//   3. take it: the account's entries become this computer's and the person's levels, except settings only this computer
+//      can have and changes made here that are not sent yet. Changes from elsewhere go into the history.
+//   4. apply what that changed (apply.ts reconcile), and tell the account what applying gave.
+// Network calls never run under the brain lock; the whole exchange keeps to a time budget (3 s for commands). Never run
+// from the session hook, `brain mcp serve` or the background children. Anything the account answers is checked before it
+// is taken: an answer that cannot be read changes nothing here.
+import { existsSync, mkdirSync, rmSync } from "node:fs"
+import type { Env } from "../gateway/common.ts"
+import { writeAtomic } from "../fsutil.ts"
+import { withBrainLockSync } from "../lock.ts"
+import { gatewayUrl, safeUrl } from "../dashboard/send.ts"
+import { brainDir, MACHINE_TOKEN, machineId, machineKeyPath, readMachineToken } from "../dashboard/state.ts"
+import { readOrgConfig } from "../org/config.ts"
+import { type Row, reconcile } from "./apply.ts"
+import { checkValue, parseId } from "./catalog.ts"
+import { type Entry, type Level, readSettingsFile, same, type SettingsDoc, type Source, updateDoc, type Value } from "./store.ts"
+import { memoryOn } from "./values.ts"
+
+export { MACHINE_TOKEN, readMachineToken }
+
+export function storeMachineToken(home: string, token: string): void {
+  withBrainLockSync(home, () => {
+    mkdirSync(brainDir(home), { recursive: true, mode: 0o700 })
+    writeAtomic(machineKeyPath(home), `${token}\n`, 0o600)
+  })
+}
+
+export function forgetMachineToken(home: string): boolean {
+  const had = existsSync(machineKeyPath(home))
+  rmSync(machineKeyPath(home), { force: true })
+  return had
+}
+
+/**
+ * A computer the account knows afresh (paired again after "Remove this machine", or a copied ~/.brain paired as a computer
+ * of its own) has an empty document there: every value set at this computer's level here is sent again, and the next fetch
+ * starts from nothing, so the account's empty document never erases them.
+ */
+export function sendAllAgain(home: string): void {
+  updateDoc(home, (d) => {
+    const at = new Date().toISOString()
+    for (const [id, e] of Object.entries(d.levels.computer)) {
+      const ref = parseId(id)
+      if ("error" in ref || ref.family.remote !== "yes") continue
+      d.outbox = d.outbox.filter((c) => !(c.id === id && c.level === "computer"))
+      d.outbox.push({ id, level: "computer", value: e.value, source: e.source, at: e.at || at, ...(e.command ? { command: e.command } : {}) })
+    }
+    delete d.sync.rev
+    d.sync.machine = machineId(home)
+  })
+}
+
+export interface Exchange {
+  paired: boolean
+  /** The account was reached (sending and fetching worked). */
+  ok: boolean
+  why?: string
+  /** Changes made here the account accepted. */
+  sent: number
+  refused: Array<{ id: string; code: string; message: string }>
+  /** Values that came from the account (changed since the last exchange). */
+  received: string[]
+  applied: Row[]
+  /** Values from the account this computer did not take, and why. */
+  held: Array<{ id: string; why: string }>
+}
+
+const LEVEL_OUT: Record<"computer" | "person", "machine" | "account"> = { computer: "machine", person: "account" }
+const SOURCES: Source[] = ["settings", "command", "dashboard", "admin", "local-page"]
+const isValue = (v: unknown): v is Value => typeof v === "boolean" || (typeof v === "number" && Number.isFinite(v)) || typeof v === "string"
+const obj = (v: unknown): Record<string, any> => (v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, any>) : {})
+const isObj = (v: unknown) => !!v && typeof v === "object" && !Array.isArray(v)
+const MEMORY_HELD = "this computer keeps memory on your team's server: only this computer turns it on (brain settings set memory.enabled on)"
+
+/** An entry as the account sends it, if it is one this brain can keep: a known setting the account may change, at a level it can be set at, with a valid value. */
+function entryFrom(id: string, level: Level, e: unknown): Entry | undefined {
+  const x = obj(e)
+  if (!isValue(x.value) || typeof x.at !== "string" || x.at.length > 40 || !Number.isFinite(Date.parse(x.at))) return undefined
+  const ref = parseId(id)
+  if ("error" in ref || ref.id !== id || ref.family.remote !== "yes" || !ref.family.levels.includes(level) || !checkValue(ref.family.type, x.value)) return undefined
+  return { value: x.value, source: SOURCES.includes(x.source) ? x.source : "dashboard", at: x.at, ...(Number.isSafeInteger(x.rev) ? { rev: x.rev } : {}) }
+}
+
+/** "<machine>.<account>" as two numbers; undefined when it is not one. */
+const revParts = (r: unknown): [number, number] | undefined => {
+  const m = typeof r === "string" ? /^(\d{1,15})\.(\d{1,15})$/.exec(r) : null
+  return m ? [Number(m[1]), Number(m[2])] : undefined
+}
+
+/** Plain words for what the account answered. */
+function trouble(status: number, said: string): string {
+  if (status === 401) return "your account no longer takes this computer's token (was the computer removed in the dashboard?): pair it again with `brain pair`"
+  if (status === 403) return `your account refused this exchange${said ? ` (${said})` : ""}: pair this computer again with \`brain pair\``
+  if (status === 404) return "the gateway does not keep brain settings yet"
+  if (status === 429) return "too many exchanges for now; the next one carries everything"
+  return `the gateway answered HTTP ${status}${said ? `: ${said}` : ""}`
+}
+
+class Unreachable extends Error {}
+class Unreadable extends Error {}
+
+/**
+ * One exchange with the account. Does nothing (paired: false) on a computer that is not paired. Never throws; what went
+ * wrong is in `why` and kept in settings.json for `brain status`.
+ */
+export async function exchange(home: string, o: { env?: Env; fetchImpl?: typeof fetch; timeoutMs?: number; apply?: boolean } = {}): Promise<Exchange> {
+  const out: Exchange = { paired: false, ok: false, sent: 0, refused: [], received: [], applied: [], held: [] }
+  // The computer's id first: a ~/.brain copied from another computer gets its own id here, and drops that one's token.
+  const machine = machineId(home)
+  const token = readMachineToken(home)
+  if (!token) return { ...out, why: "this computer is not paired with your account (brain pair)" }
+  out.paired = true
+  const file = readSettingsFile(home)
+  if (file.problem) return { ...out, why: file.problem === "newer" ? "settings.json was written by a newer brain: update brain to exchange settings here" : "settings.json could not be read: `brain settings set` writes a new one" }
+  const base = gatewayUrl(home)
+  if (!safeUrl(`${base}/api/brain/settings`)) return { ...out, why: `the gateway address ${base} is not https; the token is never sent over it` }
+  // A computer the account knows afresh: everything set here goes again (see sendAllAgain).
+  if (file.doc.sync.machine !== machine) sendAllAgain(home)
+  const deadline = Date.now() + (o.timeoutMs ?? 3_000)
+  const call = async (method: string, path: string, body?: unknown): Promise<{ status: number; json: unknown }> => {
+    const left = deadline - Date.now()
+    if (left <= 0) throw Object.assign(new Error("out of time"), { name: "TimeoutError" })
+    let res: Response
+    try {
+      res = await (o.fetchImpl ?? fetch)(`${base}${path}`, {
+        method,
+        headers: { Authorization: `Bearer ${token}`, ...(body ? { "Content-Type": "application/json" } : {}) },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+        // A redirect is not followed: it could carry the token to another host.
+        redirect: "manual",
+        signal: AbortSignal.timeout(Math.max(200, left)),
+      })
+    } catch (e) {
+      const n = (e as Error)?.name
+      if (n === "TimeoutError" || n === "AbortError") throw e
+      throw new Unreachable(String((e as Error)?.message ?? e))
+    }
+    // Reading the body may run out of time too: that is a failed exchange, never an empty answer.
+    const text = await res.text()
+    let json: unknown
+    try {
+      json = text ? JSON.parse(text) : undefined
+    } catch {
+      json = undefined
+    }
+    return { status: res.status, json }
+  }
+  const said = (j: any) => String(j?.error?.message ?? j?.error ?? j?.message ?? "").slice(0, 200)
+  const fail = (why: string): Exchange => {
+    try {
+      updateDoc(home, (d) => {
+        d.sync.lastError = why
+      })
+    } catch {}
+    return { ...out, why }
+  }
+
+  try {
+    // 1. Send what changed here.
+    const snapshot = readSettingsFile(home).doc.outbox
+    for (const level of ["computer", "person"] as const) {
+      const changes = snapshot.filter((c) => {
+        if (c.level !== level) return false
+        const r = parseId(c.id)
+        return !("error" in r) && r.family.remote === "yes"
+      })
+      if (!changes.length) continue
+      const r = await call("PATCH", "/api/brain/settings", { level: LEVEL_OUT[level], machine, changes: changes.map((c) => ({ id: c.id, value: c.value, source: c.source, at: c.at })) })
+      if (r.status !== 200) return fail(trouble(r.status, said(r.json)))
+      const j = obj(r.json)
+      if (!Array.isArray(j.accepted) || !Array.isArray(j.refused)) throw new Unreadable("PATCH")
+      const accepted = new Map<string, number>()
+      for (const a of j.accepted) if (typeof a?.id === "string") accepted.set(a.id, Number(a.rev))
+      const refused = j.refused.filter((x: any) => typeof x?.id === "string").map((x: any) => ({ id: String(x.id).slice(0, 80), code: String(x.code ?? "refused").slice(0, 40), message: String(x.message ?? "").slice(0, 200) }))
+      out.sent += accepted.size
+      out.refused.push(...refused)
+      const settledIds = new Set([...accepted.keys(), ...refused.map((x: { id: string }) => x.id)])
+      updateDoc(home, (d) => {
+        // Only what was sent leaves the outbox: a change made here meanwhile waits for the next exchange.
+        d.outbox = d.outbox.filter((c) => !(c.level === level && settledIds.has(c.id) && changes.some((s) => s.id === c.id && s.at === c.at && same(s.value, c.value))))
+        for (const [id, rev] of accepted) {
+          const e = d.levels[level][id]
+          if (e && Number.isSafeInteger(rev)) e.rev = rev
+        }
+        const at = new Date().toISOString()
+        for (const x of refused) {
+          const sent = changes.find((c) => c.id === x.id)
+          d.sync.refused.push({ id: x.id, level, value: sent?.value ?? null, code: x.code, message: x.message, at })
+        }
+        d.sync.refused = d.sync.refused.slice(-20)
+      })
+    }
+
+    // 2. Fetch what the account has. After a refusal the account's revision has not moved, but this computer must go back
+    // to the account's value: the whole state is fetched then.
+    const since = out.refused.length ? "" : (readSettingsFile(home).doc.sync.rev ?? "")
+    const r = await call("GET", `/api/brain/settings?machine=${encodeURIComponent(machine)}&since=${encodeURIComponent(since)}`)
+    if (r.status !== 200) return fail(trouble(r.status, said(r.json)))
+    const j = obj(r.json)
+    const now = new Date().toISOString()
+    if (j.unchanged === true && revParts(j.rev)) {
+      updateDoc(home, (d) => {
+        d.sync.lastSyncAt = now
+        delete d.sync.lastError
+      })
+    } else {
+      // Only an answer of the contract's shape is taken: anything else (an HTML page, `{}`) would erase every setting here.
+      const fetched = revParts(j.rev)
+      if (!fetched || !isObj(j.machine) || !isObj(j.machine.entries) || !isObj(j.account) || !isObj(j.account.entries)) throw new Unreadable("GET")
+      // 3. Take it.
+      const org = !!readOrgConfig(home)
+      updateDoc(home, (d) => {
+        // Another brain (a second terminal) may have taken a newer answer meanwhile: an older one is not taken over it.
+        const stored = revParts(d.sync.rev)
+        if (stored && (fetched[0] < stored[0] || fetched[1] < stored[1])) return
+        const pending = new Set(d.outbox.map((c) => `${c.level}\0${c.id}`))
+        const next: Record<"computer" | "person", Record<string, Entry>> = { computer: {}, person: {} }
+        for (const [level, srv] of [
+          ["computer", j.machine.entries],
+          ["person", j.account.entries],
+        ] as Array<["computer" | "person", Record<string, unknown>]>) {
+          // Kept from here: settings only this computer can have, and changes not sent yet.
+          for (const [id, e] of Object.entries(d.levels[level])) {
+            const ref = parseId(id)
+            if (pending.has(`${level}\0${id}`) || "error" in ref || ref.family.remote !== "yes") next[level][id] = e
+          }
+          for (const [id, raw] of Object.entries(srv)) {
+            if (!Object.hasOwn(srv, id) || pending.has(`${level}\0${id}`) || Object.hasOwn(next[level], id)) continue
+            const e = entryFrom(id, level, raw)
+            if (!e) continue
+            const was = d.levels[level][id]
+            // The same value from the same source: kept as it is here (with the command that set it).
+            next[level][id] = was && same(was.value, e.value) && was.source === e.source ? { ...was, ...(e.rev !== undefined ? { rev: e.rev } : {}) } : e
+          }
+        }
+        // Memory turned on from afar on a computer that sends it to a team server: only this computer turns that on. Judged
+        // by the effect (whatever level or source did it): memory off before, on after.
+        const held: Array<{ id: string; why: string }> = []
+        if (org && !memoryOn(home, d) && memoryOn(home, { ...d, levels: { ...d.levels, computer: next.computer, person: next.person } })) {
+          for (const level of ["computer", "person"] as const) {
+            const was = d.levels[level]["memory.enabled"]
+            if (was) next[level]["memory.enabled"] = was
+            else delete next[level]["memory.enabled"]
+          }
+          held.push({ id: "memory.enabled", why: MEMORY_HELD })
+          d.applied["memory.enabled"] = { want: true, ok: false, at: now, error: MEMORY_HELD }
+        }
+        for (const level of ["computer", "person"] as const) {
+          for (const id of new Set([...Object.keys(d.levels[level]), ...Object.keys(next[level])])) {
+            const was = d.levels[level][id]
+            const now2 = next[level][id]
+            if (was && now2 && same(was.value, now2.value) && was.source === now2.source) continue
+            if (!was && !now2) continue
+            // A change from elsewhere goes into the history, with what it replaced here. A removal at this computer's
+            // level comes from the dashboard; one for all the person's computers may come from another computer.
+            d.history.push({
+              id,
+              level,
+              value: now2 ? now2.value : null,
+              source: now2?.source ?? (level === "computer" ? "dashboard" : "settings"),
+              at: now2?.at ?? now,
+              ...(was ? { replaced: { value: was.value, source: was.source, at: was.at, ...(was.command ? { command: was.command } : {}) } } : {}),
+            })
+            out.received.push(id)
+          }
+          d.levels[level] = next[level]
+        }
+        // Team defaults and locks come with step 4: until then the account sends none.
+        const locks: SettingsDoc["locks"] = {}
+        for (const [id, l] of Object.entries(obj(j.locks))) if (Object.hasOwn(obj(j.locks), id) && isValue(obj(l).value) && !("error" in parseId(id))) locks[id] = { value: obj(l).value }
+        d.locks = locks
+        d.history = d.history.slice(-200)
+        d.sync.rev = `${fetched[0]}.${fetched[1]}`
+        d.sync.lastSyncAt = now
+        d.sync.machine = machine
+        delete d.sync.lastError
+        d.sync.held = held
+        out.held = held
+      })
+    }
+    out.ok = true
+  } catch (e) {
+    const name = (e as Error)?.name
+    if (name === "TimeoutError" || name === "AbortError") return fail("the account did not answer in time; changes made here wait for the next exchange")
+    if (e instanceof Unreachable) return fail(`could not reach ${base}`)
+    if (e instanceof Unreadable) return fail("the account's answer could not be read; nothing here was changed")
+    return fail(`the exchange stopped: ${String((e as Error)?.message ?? e).slice(0, 200)}`)
+  }
+
+  // 4. Apply what changed, and say what it gave (a value held back here counts as failed).
+  if (o.apply !== false) {
+    try {
+      out.applied = (await reconcile(home, { env: o.env ?? process.env })).applied
+    } catch {}
+    const applied: Record<string, unknown> = {}
+    for (const row of out.applied)
+      applied[row.id] = { want: row.value ?? null, ok: row.state !== "failed" && row.state !== "not on this computer" && row.state !== "can't read", ...(row.error ? { error: row.error } : {}), ...(row.notes.length ? { notes: row.notes.slice(0, 5) } : {}), at: new Date().toISOString() }
+    for (const h of out.held) applied[h.id] = { want: true, ok: false, error: h.why, at: new Date().toISOString() }
+    if (Object.keys(applied).length && Date.now() < deadline) {
+      try {
+        await call("POST", "/api/brain/settings/applied", { machine, applied })
+      } catch {}
+    }
+  }
+  return out
+}
+
+/** What `brain status` says about the account exchange. */
+export function exchangeState(home: string): {
+  paired: boolean
+  lastSyncAt?: string
+  lastError?: string
+  waiting: number
+  refused: SettingsDoc["sync"]["refused"]
+  held: Array<{ id: string; why: string }>
+} {
+  const d = readSettingsFile(home).doc
+  const waiting = d.outbox.filter((c) => {
+    const r = parseId(c.id)
+    return !("error" in r) && r.family.remote === "yes"
+  }).length
+  return {
+    paired: !!readMachineToken(home),
+    ...(d.sync.lastSyncAt ? { lastSyncAt: d.sync.lastSyncAt } : {}),
+    ...(d.sync.lastError ? { lastError: d.sync.lastError } : {}),
+    waiting,
+    refused: d.sync.refused,
+    held: d.sync.held,
+  }
+}

package/src/settings/apply.ts

@@ -0,0 +1,306 @@
+// The only code that changes a setting. `brain settings`, `brain sync` and (later) the background agent and the local page
+// all call it, so a change looks the same whichever way it was made: it is checked against the catalog, recorded with who
+// made it and what it replaced, applied under the brain lock, read back from the files, and the result kept, so every way
+// in can say whether it worked. brain's other commands (gateway connect, mcp install, ...) make their changes themselves,
+// as before, and record them here (recordChanges, recordConnected) in the same hold of the lock, so they show up the same way.
+import type { Env, GatewaySettings } from "../gateway/common.ts"
+import { connectionState } from "../gateway/connect.ts"
+import { withBrainLock } from "../lock.ts"
+import { type Actual, cleanText, type Ctx, type Family, FAMILIES, HEADER_TOOLS, modelAlias, parseId, parseValue, resolve, settingsHere, type SettingRef } from "./catalog.ts"
+import { type Applied, type Change, type Effective, type Entry, type Level, LEVELS, readSettingsFile, recordChange, same, type SettingsDoc, SettingsUnwritable, settingsFile, type Source, updateDoc, type Value } from "./store.ts"
+
+export type State = "applied" | "default" | "as found" | "waiting" | "failed" | "not on this computer" | "changed outside brain" | "can't read" | "used when connected" | "locked"
+
+export interface Row {
+  id: string
+  family: Family
+  tool?: string
+  /** The value that applies here, and where it comes from. */
+  value?: Value
+  from: Effective["from"]
+  entry?: Entry
+  actual: Actual
+  state: State
+  error?: string
+  notes: string[]
+}
+
+export interface Outcome {
+  ok: boolean
+  /** Why nothing was saved (an unknown setting, a value of the wrong type, a level it cannot be set at). */
+  refused?: string
+  row?: Row
+  change?: Change
+  /** What the person should know beyond the row (the value comes from another level, say). */
+  notes: string[]
+}
+
+const now = () => new Date().toISOString()
+const readDoc = (home: string) => readSettingsFile(home).doc
+const ctxOf = (home: string, env: Env, doc: SettingsDoc = readDoc(home)): Ctx => ({ home, env, doc })
+
+/** A settings file written by a newer brain is read, never acted on: applying what it says could undo what that brain did. */
+function refuseNewer(home: string) {
+  if (readSettingsFile(home).problem === "newer") throw new SettingsUnwritable(`${settingsFile(home)} was written by a newer brain; update brain (bun add -g @100xprompt/brain) to change or apply settings here`)
+}
+
+/** One setting as it stands: what applies, from where, what this computer actually has, and whether that is applied. */
+export async function rowOf(ctx: Ctx, ref: SettingRef): Promise<Row> {
+  const { id, family, tool } = ref
+  const eff = resolve(ctx.doc, ref)
+  let actual: Actual
+  try {
+    actual = await family.read(ctx, tool)
+  } catch (e) {
+    actual = { value: null, note: `could not read it (${cleanText((e as Error).message, ctx.home).slice(0, 160)})` }
+  }
+  const ap: Applied | undefined = ctx.doc.applied[id]
+  // What a tool's files say can hold this computer's paths: cleaned before it is shown, kept or sent.
+  const notes = [...(actual.note ? [cleanText(actual.note, ctx.home)] : []), ...(ap?.ok && ap.notes ? ap.notes : [])]
+  const held = ctx.doc.sync.held.find((h) => h.id === id)
+  const base = { id, family, ...(tool ? { tool } : {}), ...(eff.value !== undefined ? { value: eff.value } : {}), from: eff.from, ...(eff.entry ? { entry: eff.entry } : {}), actual }
+  let state: State
+  let error: string | undefined
+  if (family.apply && tool && eff.from !== "none" && !family.present(ctx, tool)) state = "not on this computer"
+  else if (held) {
+    // A value from the account this computer did not take (memory turned on from afar on a team-memory computer).
+    state = "failed"
+    error = held.why
+  } else if (!family.apply) state = eff.from === "lock" ? "locked" : eff.from === "default" ? "default" : "applied"
+  else if (eff.from === "none") state = actual.value === null && !actual.idle ? "can't read" : "as found"
+  else if (ap && !ap.ok && same(ap.want, eff.value)) {
+    state = ap.missing ? "not on this computer" : "failed"
+    error = ap.error
+  } else if (!ap || !same(ap.want, eff.value)) state = "waiting"
+  else if (actual.value === null) state = actual.idle ? "used when connected" : "can't read"
+  else if (!same(actual.value, eff.value)) state = "changed outside brain"
+  else state = eff.from === "lock" ? "locked" : "applied"
+  return { ...base, state, ...(error ? { error } : {}), notes: [...new Set(notes)] }
+}
+
+/** The settings that have a value at some level (or a lock), as catalog references; ids this brain does not know are left out. */
+function refsSet(doc: SettingsDoc): SettingRef[] {
+  const ids = new Set([...Object.keys(doc.locks), ...LEVELS.flatMap((l) => Object.keys(doc.levels[l]))])
+  return [...ids].map((id) => parseId(id)).filter((r): r is SettingRef => !("error" in r))
+}
+
+/** Every setting on this computer, plus any set at some level for a tool that is not here (it shows as not on this computer). */
+export async function listSettings(home: string, env: Env = process.env): Promise<Row[]> {
+  const ctx = ctxOf(home, env)
+  const refs = settingsHere(ctx)
+  const seen = new Set(refs.map((r) => r.id))
+  for (const r of refsSet(ctx.doc)) if (!seen.has(r.id)) refs.push(r)
+  return Promise.all(refs.map((r) => rowOf(ctx, r)))
+}
+
+const upload = (f: Family) => f.remote === "yes"
+
+/** Marks a tool's model and context editing applied when what they ask for is what the tool was just connected with. */
+function markConnected(d: SettingsDoc, tool: string, s: GatewaySettings, at: string) {
+  const asked: Array<[string, Value]> = [
+    [`tools.${tool}.model`, modelAlias(s.model)!],
+    ...(HEADER_TOOLS.includes(tool) ? [[`tools.${tool}.contextEdit`, s.contextEdit] as [string, Value]] : []),
+  ]
+  for (const [id, has] of asked) {
+    const ref = parseId(id)
+    if ("error" in ref) continue
+    const v = resolve(d, ref).value
+    if (v !== undefined && same(v, has)) d.applied[id] = { want: v, ok: true, at }
+  }
+}
+
+/** Applies what now applies for `ref` (inside the lock), and keeps the result. Settings brain reads where it uses them have nothing to apply. */
+async function applyNow(home: string, env: Env, ref: SettingRef): Promise<void> {
+  const doc = readDoc(home)
+  const eff = resolve(doc, ref)
+  if (!ref.family.apply) return
+  if (eff.value === undefined) {
+    // Nobody sets it any more: brain stops managing it and leaves it as it is.
+    updateDoc(home, (d) => {
+      delete d.applied[ref.id]
+    })
+    return
+  }
+  let r
+  try {
+    r = await ref.family.apply(ctxOf(home, env, doc), eff.value, ref.tool)
+  } catch (e) {
+    r = { ok: false, error: cleanText((e as Error).message, home) }
+  }
+  const at = now()
+  const record: Applied = { want: eff.value, ok: r.ok, at, ...(r.error ? { error: r.error } : {}), ...(r.notes?.length ? { notes: r.notes } : {}), ...(r.missing ? { missing: true } : {}) }
+  const connected = r.ok && ref.tool && ref.family.key !== "tools.*.mcp" && ref.family.key !== "tools.*.hooks" ? connectionState(home, ref.tool, env) : undefined
+  updateDoc(home, (d) => {
+    d.applied[ref.id] = record
+    // Connecting a tool (or changing its model) also applies its model and context editing when those are what it got.
+    if (connected?.state === "connected" && connected.settings) markConnected(d, ref.tool!, connected.settings, at)
+  })
+}
+
+const LEVEL_WORD: Record<"computer" | "person", string> = { computer: "this computer", person: "all your computers" }
+
+/**
+ * `brain settings set <id> <value> [--for computer|me]`: saves the value at the level, then applies what applies here. A
+ * value that cannot be applied stays saved (it is what the person wants), marked failed with the reason; `brain sync`
+ * tries it again. A value for all the person's computers, for a tool that is not on this one, is saved and not applied here.
+ */
+export async function setSetting(home: string, id: string, given: string, o: { level?: "computer" | "person"; source?: Source; env?: Env } = {}): Promise<Outcome> {
+  const env = o.env ?? process.env
+  const level = o.level ?? "computer"
+  const ref = parseId(id)
+  if ("error" in ref) return { ok: false, refused: ref.error, notes: [] }
+  const parsed = parseValue(ref.family.type, given)
+  if ("error" in parsed) return { ok: false, refused: `${ref.id}: ${parsed.error}`, notes: [] }
+  if (!ref.family.levels.includes(level)) return { ok: false, refused: `${ref.id} can only be set on this computer`, notes: [] }
+  const here = !ref.tool || ref.family.present(ctxOf(home, env), ref.tool)
+  if (level === "computer" && !here) return { ok: false, refused: `${ref.id}: this tool has not run on this computer; nothing was saved`, notes: [] }
+  return withBrainLock(
+    home,
+    async () => {
+      let change: Change | undefined
+      updateDoc(home, (d) => {
+        change = recordChange(d, { id: ref.id, level, value: parsed.value, source: o.source ?? "settings", at: now() }, { upload: upload(ref.family) })
+      })
+      const notes: string[] = []
+      if (here) await applyNow(home, env, ref)
+      else notes.push(`${ref.tool} is not on this computer: nothing to apply here`)
+      const doc = readDoc(home)
+      const eff = resolve(doc, ref)
+      if (eff.from === "lock") notes.push(`your team admin has locked ${ref.id}: that value applies here`)
+      else if (eff.from !== level) notes.push(`this computer keeps its own value for ${ref.id}; \`brain settings unset ${ref.id}\` uses the one for all your computers`)
+      if (level === "person") notes.push("saved for all your computers: it reaches the others once settings sync with your 100xprompt account")
+      const row = await rowOf(ctxOf(home, env, doc), ref)
+      const ok = !here || (row.state !== "failed" && row.state !== "not on this computer")
+      return { ok, row, ...(change ? { change } : {}), notes }
+    },
+    { what: `changing ${ref.id}` },
+  )
+}
+
+/** `brain settings unset <id>`: clears the value at the level; what is set at the level above applies, or brain stops managing it. */
+export async function unsetSetting(home: string, id: string, o: { level?: "computer" | "person"; env?: Env } = {}): Promise<Outcome> {
+  const env = o.env ?? process.env
+  const level = o.level ?? "computer"
+  const ref = parseId(id)
+  if ("error" in ref) return { ok: false, refused: ref.error, notes: [] }
+  return withBrainLock(
+    home,
+    async () => {
+      let change: Change | undefined
+      updateDoc(home, (d) => {
+        change = recordChange(d, { id: ref.id, level, value: null, source: "settings", at: now() }, { upload: upload(ref.family) })
+      })
+      if (!change) return { ok: true, notes: [`nothing was set for ${ref.id} on ${LEVEL_WORD[level]}`] }
+      const here = !ref.tool || ref.family.present(ctxOf(home, env), ref.tool)
+      if (here) await applyNow(home, env, ref)
+      const doc = readDoc(home)
+      const eff = resolve(doc, ref)
+      const notes = eff.from === "none" ? ["brain no longer manages it: it stays as it is now"] : []
+      const row = await rowOf(ctxOf(home, env, doc), ref)
+      return { ok: row.state !== "failed", row, change, notes }
+    },
+    { what: `clearing ${ref.id}` },
+  )
+}
+
+/**
+ * Applies every setting whose value changed since brain last applied it (and, with `retryFailed`, those that failed and
+ * brain entries that broke). A setting brain applied that someone changed by hand since is NOT put back: that would fight
+ * the person; it shows as "changed outside brain" until it is set again. A tool that is not on this computer is skipped.
+ * Tools first, so a connect carries the tool's model and context editing. Never acts on a newer brain's settings file.
+ */
+export async function reconcile(home: string, o: { env?: Env; retryFailed?: boolean } = {}): Promise<{ applied: Row[]; unknown: string[]; elsewhere: string[] }> {
+  const env = o.env ?? process.env
+  refuseNewer(home)
+  return withBrainLock(
+    home,
+    async () => {
+      refuseNewer(home)
+      const doc = readDoc(home)
+      const ids = new Set([...Object.keys(doc.locks), ...LEVELS.flatMap((l) => Object.keys(doc.levels[l]))])
+      const unknown: string[] = []
+      const refs: SettingRef[] = []
+      for (const id of ids) {
+        const r = parseId(id)
+        if ("error" in r) unknown.push(id)
+        else if (r.family.apply) refs.push(r)
+      }
+      const order = (r: SettingRef) => FAMILIES.indexOf(r.family)
+      refs.sort((a, b) => order(a) - order(b))
+      const done: SettingRef[] = []
+      const elsewhere: string[] = []
+      for (const r of refs) {
+        const cur = readDoc(home)
+        const ctx = ctxOf(home, env, cur)
+        const eff = resolve(cur, r)
+        const ap = cur.applied[r.id]
+        if (eff.value === undefined) continue
+        if (r.tool && !r.family.present(ctx, r.tool)) {
+          elsewhere.push(r.id)
+          continue
+        }
+        const changed = !ap || !same(ap.want, eff.value)
+        const retry = !!o.retryFailed && ((ap && !ap.ok) || (eff.value === true && !!r.family.repair?.(ctx, r.tool)))
+        if (!changed && !retry) continue
+        await applyNow(home, env, r)
+        done.push(r)
+      }
+      const ctx = ctxOf(home, env)
+      return { applied: await Promise.all(done.map((r) => rowOf(ctx, r))), unknown, elsewhere }
+    },
+    { what: "applying settings" },
+  )
+}
+
+/**
+ * What one of brain's other commands just did, recorded at this computer's level as that command's change (`brain mcp
+ * install` records tools.<tool>.mcp on); null clears this computer's value. The command already made the change, so it is
+ * marked applied. Call it inside the command's own hold of the brain lock. Never fails the command.
+ */
+export function recordChanges(home: string, changes: Array<{ id: string; value: Value | null }>, command: string): Change[] {
+  const out: Change[] = []
+  try {
+    updateDoc(home, (d) => {
+      const at = now()
+      for (const c of changes) {
+        const ref = parseId(c.id)
+        if ("error" in ref) continue
+        const ch = recordChange(d, { id: ref.id, level: "computer", value: c.value, source: "command", command, at }, { upload: upload(ref.family) })
+        if (ch) out.push(ch)
+        if (c.value !== null && ref.family.apply) d.applied[ref.id] = { want: c.value, ok: true, at }
+      }
+    })
+  } catch {}
+  return out
+}
+
+/**
+ * `brain gateway connect` (s: the settings it connected with) or `disconnect` (s undefined), recorded inside the same hold
+ * of the lock: the tool on or off, and for a connect the model it got (cleared when it is a model brain has no short name
+ * for) and its context editing. A value already in force is not recorded again, so a choice made with `brain settings`
+ * keeps its source; what is asked for and now in force is marked applied (a model that failed earlier, say).
+ */
+export function recordConnected(home: string, tool: string, s: GatewaySettings | undefined): void {
+  const command = s ? "brain gateway connect" : "brain gateway disconnect"
+  try {
+    updateDoc(home, (d) => {
+      const at = now()
+      const put = (id: string, value: Value | null) => {
+        const ref = parseId(id)
+        if ("error" in ref) return
+        const cur = resolve(d, ref).value
+        if (value === null ? d.levels.computer[ref.id] === undefined : cur !== undefined && same(cur, value)) return
+        recordChange(d, { id: ref.id, level: "computer", value, source: "command", command, at }, { upload: upload(ref.family) })
+      }
+      put(`tools.${tool}.gateway`, !!s)
+      if (s) {
+        const alias = modelAlias(s.model)
+        put(`tools.${tool}.model`, alias && alias !== "other" ? alias : null)
+        if (HEADER_TOOLS.includes(tool)) put(`tools.${tool}.contextEdit`, s.contextEdit)
+      }
+      const g = parseId(`tools.${tool}.gateway`)
+      if (!("error" in g)) d.applied[g.id] = { want: !!s, ok: true, at }
+      if (s) markConnected(d, tool, s, at)
+    })
+  } catch {}
+}