@100xprompt/brain 0.1.4 → 0.1.5

package/README.md

@@ -210,6 +210,19 @@ brain pair            # approve this computer in your 100xprompt account (in the
 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
@@ -266,6 +279,7 @@ 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.4",
+  "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

@@ -45,6 +45,7 @@ brain status                                       this computer at a glance: si
 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`
 
@@ -231,7 +232,14 @@ async function main() {
   }
   if (cmd === "status") {
     const { statusCommand } = await import("./settings/cli.ts")
-    process.exit(await statusCommand(home))
+    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")

package/src/dashboard/report.ts

@@ -76,12 +76,16 @@ export interface SettingsRow {
   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[]
 }
 
@@ -97,6 +101,9 @@ export async function settingsSection(home: string, env: Env): Promise<SettingsS
     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
@@ -108,6 +115,7 @@ export async function settingsSection(home: string, env: Env): Promise<SettingsS
       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 {
@@ -126,6 +134,7 @@ export async function settingsSection(home: string, env: Env): Promise<SettingsS
           ...(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 } : {}),
         }
       }),
     }

package/src/lock.ts

@@ -93,6 +93,9 @@ export function processStart(pid: number, now = Date.now()): number | undefined
 let started: number | undefined
 const myStart = () => (started ??= processStart(process.pid) ?? Math.round(performance.timeOrigin))
 
+/** This process's start, as holderGone() judges this process (what a loop records to be judged alive by itself too). */
+export const ownStart = () => myStart()
+
 function readOwner(home: string): LockOwner | undefined {
   try {
     const o = JSON.parse(readFileSync(ownerPath(home), "utf8"))

package/src/service.ts

@@ -0,0 +1,473 @@
+// `brain service install | uninstall | status | run`: a brain that runs in the background, so a settings change made in the
+// dashboard reaches this computer by itself (docs/settings-contract.md, section 6).
+//
+//   install   macOS: a LaunchAgent (~/Library/LaunchAgents/com.100xprompt.brain.plist, `launchctl bootstrap gui/<uid>`);
+//             Linux: a systemd user unit (~/.config/systemd/user/brain.service, `systemctl --user enable --now`). Both start
+//             ~/.brain/bin/brain, a small script named brain (so the system's notice names brain, not bun) that runs the
+//             bun on the person's PATH with this brain's cli.ts. Never from a temporary bunx copy.
+//   run       the loop: every 60 s one exchange with the account (account.ts); when it took or applied anything, the report
+//             goes at once. Offline or failing: it waits longer each time (2, 4, 8, at most 10 minutes). One per home: a
+//             second waits until the first stops. It exits with RESTART_EXIT when the brain on disk is a newer version
+//             (launchd / systemd start the new one: they restart it only after that or a crash), and with 0 when brain was
+//             removed from disk (so nothing restarts it).
+// The person's environment comes from ~/.brain/env.json (their tool folders and opt-outs): written into the plist / unit,
+// and read again every round, so a brain started by launchd edits the files the person's tools read.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { dirname, join, resolve as resolvePath } from "node:path"
+import { writeAtomic } from "./fsutil.ts"
+import { holderGone, ownStart, withBrainLockSync } from "./lock.ts"
+import { CLI_PATH, isEphemeral, stableBun, VERSION } from "./self.ts"
+import { ENV_VARS, readRecordedEnv } from "./settings/env.ts"
+
+export const LABEL = "com.100xprompt.brain"
+export const plistPath = (home: string) => join(home, "Library", "LaunchAgents", `${LABEL}.plist`)
+export const unitPath = (home: string) => join(home, ".config", "systemd", "user", "brain.service")
+export const wrapperPath = (home: string) => join(home, ".brain", "bin", "brain")
+export const serviceStatePath = (home: string) => join(home, ".brain", "service.json")
+export const serviceLogPath = (home: string) => join(home, ".brain", "logs", "service.log")
+
+type Env = Record<string, string | undefined>
+type Io = { out(l: string): void }
+
+export interface ServiceDeps {
+  /** Runs launchctl / systemctl (tests replace it). */
+  run?: (argv: string[]) => { code: number; out: string }
+  platform?: string
+  uid?: number
+  /** The cli.ts the service starts (default: this brain's). */
+  cli?: string
+  bun?: string
+}
+
+const runCmd = (argv: string[]): { code: number; out: string } => {
+  try {
+    const p = Bun.spawnSync(argv, { stdout: "pipe", stderr: "pipe", timeout: 15_000 })
+    return { code: p.exitCode ?? 1, out: `${p.stdout.toString()}${p.stderr.toString()}` }
+  } catch (e) {
+    return { code: 1, out: String((e as Error).message) }
+  }
+}
+
+export interface ServiceState {
+  pid?: number
+  startedAt?: number
+  version?: string
+  lastRunAt?: string
+  lastOkAt?: string
+  lastError?: string
+}
+
+/** The exit code that has launchd / systemd start brain again (a newer brain is on disk). 0 leaves it stopped. */
+export const RESTART_EXIT = 75
+
+export function readServiceState(home: string): ServiceState {
+  try {
+    const j = JSON.parse(readFileSync(serviceStatePath(home), "utf8"))
+    return j && typeof j === "object" ? j : {}
+  } catch {
+    return {}
+  }
+}
+
+function writeServiceState(home: string, s: ServiceState) {
+  try {
+    mkdirSync(join(home, ".brain"), { recursive: true, mode: 0o700 })
+    writeAtomic(serviceStatePath(home), `${JSON.stringify(s, null, 1)}\n`, 0o600)
+  } catch {}
+}
+
+/** Whether the service is installed here (its plist or unit exists), and whether its loop is alive (cheap: no launchctl). */
+export function serviceState(home: string, platform: string = process.platform, every = loopEvery()): { installed: boolean; running: boolean; lastRunAt: string | null } {
+  const installed = existsSync(platform === "darwin" ? plistPath(home) : unitPath(home))
+  const s = readServiceState(home)
+  const alive = typeof s.pid === "number" && typeof s.startedAt === "number" && !holderGone({ pid: s.pid, startedAt: s.startedAt, at: "" })
+  // Its last round, or its start when it has had none yet (the first round can take its full 10 s).
+  const last = s.lastRunAt ? Date.parse(s.lastRunAt) : s.startedAt
+  const recent = typeof last === "number" && Number.isFinite(last) && Date.now() - last < Math.max(every, 60_000) * 12
+  return { installed, running: alive && recent, lastRunAt: s.lastRunAt ?? null }
+}
+
+/** The environment the service runs with: the person's recorded values, and where brain keeps its files. */
+function serviceEnv(home: string, env: Env): Record<string, string> {
+  const out: Record<string, string> = {}
+  for (const [k, v] of Object.entries(readRecordedEnv(home)?.vars ?? {})) if (typeof v === "string" && v) out[k] = v
+  // A brain kept somewhere other than the home folder (BRAIN_HOME) keeps it there in the background too.
+  if (env.BRAIN_HOME) out.BRAIN_HOME = env.BRAIN_HOME
+  if (!out.PATH && env.PATH) out.PATH = env.PATH
+  return out
+}
+
+const xml = (s: string) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" })[c]!)
+const shq = (s: string) => `'${s.replace(/'/g, `'\\''`)}'`
+
+export function plistText(wrapper: string, env: Record<string, string>, log: string): string {
+  const envXml = Object.entries(env)
+    .map(([k, v]) => `    <key>${xml(k)}</key>\n    <string>${xml(v)}</string>`)
+    .join("\n")
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(wrapper)}</string>
+    <string>service</string>
+    <string>run</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>LowPriorityIO</key>
+  <true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+${envXml}
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${xml(log)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(log)}</string>
+</dict>
+</plist>
+`
+}
+
+/**
+ * A value inside systemd's double quotes: \ " and line breaks escaped, % doubled (a specifier otherwise), and in a command
+ * line $ doubled too (a variable otherwise).
+ */
+const sdq = (v: string, command = false) => {
+  let t = v.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/%/g, "%%")
+  if (command) t = t.replace(/\$/g, "$$$$")
+  return `"${t}"`
+}
+
+export function unitText(wrapper: string, env: Record<string, string>, log: string): string {
+  const envLines = Object.entries(env)
+    .map(([k, v]) => `Environment=${sdq(`${k}=${v}`)}`)
+    .join("\n")
+  // The log path is taken as it is after "append:" (no quotes there): only % needs doubling, and a line break cannot be kept.
+  const logPath = log.replace(/%/g, "%%").replace(/[\r\n]/g, "")
+  return `[Unit]
+Description=brain by 100xprompt: keeps this computer's settings in step with your account
+
+[Service]
+ExecStart=${sdq(wrapper, true)} service run
+Restart=on-failure
+RestartSec=30
+StandardOutput=append:${logPath}
+StandardError=append:${logPath}
+${envLines}
+
+[Install]
+WantedBy=default.target
+`
+}
+
+/** `brain service install`: the wrapper, the plist or unit, and the system told to start it. */
+export function installService(home: string, io: Io, env: Env = process.env, deps: ServiceDeps = {}): number {
+  const platform = deps.platform ?? process.platform
+  if (platform !== "darwin" && platform !== "linux") {
+    io.out("brain service: not on this system yet (macOS and Linux only); run `brain sync` to take changes made in the dashboard")
+    return 1
+  }
+  const cli = deps.cli ?? CLI_PATH
+  if (isEphemeral(cli)) {
+    io.out("brain service: this brain is a temporary bunx copy, which a reboot or cache clean removes; install brain first: bun add -g @100xprompt/brain")
+    return 1
+  }
+  // launchd and systemd read the real home's folders: a brain kept elsewhere (BRAIN_HOME, used by tests) cannot have one.
+  if (env.BRAIN_HOME && env.HOME && resolvePath(env.BRAIN_HOME) !== resolvePath(env.HOME)) {
+    io.out("brain service: BRAIN_HOME points away from your home folder, and the system starts background services only from your home's; run it without BRAIN_HOME")
+    return 1
+  }
+  const run = deps.run ?? runCmd
+  const bun = deps.bun ?? stableBun()
+  const wrapper = wrapperPath(home)
+  const vars = serviceEnv(home, env)
+  const file = platform === "darwin" ? plistPath(home) : unitPath(home)
+  // A script an earlier install left is kept when this one fails: a loaded service still starts it.
+  const hadWrapper = existsSync(wrapper)
+  try {
+    mkdirSync(dirname(wrapper), { recursive: true, mode: 0o700 })
+    mkdirSync(dirname(serviceLogPath(home)), { recursive: true, mode: 0o700 })
+    // Named brain, so the system's "background item added" notice says brain; it only starts this brain. A brain (or bun)
+    // removed from disk ends it quietly: exit 0, which the system does not restart.
+    writeAtomic(
+      wrapper,
+      `#!/bin/sh\n# brain's background service (brain service install). It runs this brain; brain service uninstall removes it.\n[ -f ${shq(cli)} ] && command -v ${shq(bun)} >/dev/null 2>&1 || exit 0\nexec ${shq(bun)} ${shq(cli)} "$@"\n`,
+      0o755,
+    )
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, platform === "darwin" ? plistText(wrapper, vars, serviceLogPath(home)) : unitText(wrapper, vars, serviceLogPath(home)), { mode: 0o644 })
+  } catch (e) {
+    if (!hadWrapper)
+      try {
+        rmSync(wrapper, { force: true })
+      } catch {}
+    const err = e as NodeJS.ErrnoException
+    const why = err?.code === "EACCES" || err?.code === "EPERM" ? "permission denied" : String(err?.message ?? e).slice(0, 200)
+    // The file or folder that failed, as the error names it (the wrapper's folder, the log's, LaunchAgents...).
+    const at = typeof err?.path === "string" ? err.path : file
+    io.out(`brain service: could not write ${at} (${why}); check that you own ${dirname(at)} (sudo chown $USER ${dirname(at)}), then run brain service install again`)
+    return 1
+  }
+  if (platform === "darwin") {
+    const uid = deps.uid ?? process.getuid?.() ?? 501
+    // Loaded afresh: an older one (another version, other environment) goes first.
+    run(["launchctl", "bootout", `gui/${uid}/${LABEL}`])
+    const r = run(["launchctl", "bootstrap", `gui/${uid}`, file])
+    if (r.code !== 0) {
+      io.out(`brain service: macOS did not start it (launchctl: ${r.out.trim().slice(0, 200) || `exit ${r.code}`}); the file is at ${file}`)
+      return 1
+    }
+  } else {
+    run(["systemctl", "--user", "daemon-reload"])
+    const r = run(["systemctl", "--user", "enable", "brain.service"])
+    // Restarted, not just started: an install again (another brain, other environment) takes effect at once.
+    const r2 = r.code === 0 ? run(["systemctl", "--user", "restart", "brain.service"]) : r
+    if (r2.code !== 0) {
+      io.out(`brain service: systemd did not start it (systemctl: ${r2.out.trim().slice(0, 200) || `exit ${r2.code}`}); the unit is at ${file}`)
+      return 1
+    }
+  }
+  io.out("brain service: installed and started. Every minute it takes changes made in your dashboard and applies them here.")
+  io.out(`  log: ${serviceLogPath(home)}; stop it: brain service uninstall`)
+  return 0
+}
+
+export function uninstallService(home: string, io: Io, deps: ServiceDeps = {}): number {
+  const platform = deps.platform ?? process.platform
+  const run = deps.run ?? runCmd
+  let had = false
+  if (platform === "darwin") {
+    const uid = deps.uid ?? process.getuid?.() ?? 501
+    if (existsSync(plistPath(home))) {
+      had = true
+      run(["launchctl", "bootout", `gui/${uid}/${LABEL}`])
+      rmSync(plistPath(home), { force: true })
+    }
+  } else if (platform === "linux" && existsSync(unitPath(home))) {
+    had = true
+    run(["systemctl", "--user", "disable", "--now", "brain.service"])
+    rmSync(unitPath(home), { force: true })
+    run(["systemctl", "--user", "daemon-reload"])
+  }
+  rmSync(wrapperPath(home), { force: true })
+  io.out(had ? "brain service: stopped and removed; `brain sync` (or brain status) still takes dashboard changes by hand" : "brain service: not installed here")
+  return 0
+}
+
+const ago = (iso?: string) => {
+  const t = iso ? Date.parse(iso) : NaN
+  if (!Number.isFinite(t)) return "never"
+  const s = Math.max(0, Math.round((Date.now() - t) / 1000))
+  return s < 90 ? `${s}s ago` : s < 5400 ? `${Math.round(s / 60)}m ago` : `${Math.round(s / 3600)}h ago`
+}
+
+export function serviceStatusLines(home: string, platform: string = process.platform): string[] {
+  if (platform !== "darwin" && platform !== "linux") return ["service: not on this system yet (brain sync takes the dashboard's changes)"]
+  const st = serviceState(home, platform)
+  const s = readServiceState(home)
+  if (!st.installed) return ["service: not installed (brain service install: dashboard changes then apply by themselves)"]
+  return [
+    `service: installed, ${st.running ? `running (version ${s.version ?? "?"}, last round ${ago(s.lastRunAt)})` : "not running right now"}`,
+    ...(s.lastError ? [`  the last round failed: ${s.lastError}`] : []),
+    `  log: ${serviceLogPath(home)}`,
+  ]
+}
+
+// ---- the loop -------------------------------------------------------------------------------------------------------------
+
+/** BRAIN_SERVICE_EVERY_MS: the time between rounds (tests use a short one). */
+export function loopEvery(env: Env = process.env): number {
+  const n = Number(env.BRAIN_SERVICE_EVERY_MS)
+  return env.BRAIN_SERVICE_EVERY_MS && Number.isFinite(n) && n >= 10 ? n : 60_000
+}
+
+/** The wait after `failures` failed rounds in a row: 1, 2, 4, 8 times the round, at most 10 minutes. */
+export const backoff = (every: number, failures: number) => (failures <= 0 ? every : Math.min(Math.max(every * 2 ** failures, every), Math.max(every, 600_000)))
+
+/** The version of the brain on disk now (a `bun add -g` while the service runs replaces it). */
+function versionOnDisk(cli: string): string | undefined {
+  try {
+    return JSON.parse(readFileSync(join(dirname(cli), "..", "package.json"), "utf8")).version
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The person's recorded environment, applied to this process: what their shell has now (a tool folder or opt-out they
+ * dropped is dropped here too, whatever the plist or unit started this process with). PATH stays when none is recorded.
+ */
+export function refreshEnv(home: string, env: Env = process.env) {
+  const rec = readRecordedEnv(home)
+  if (!rec) return
+  for (const k of ENV_VARS) {
+    const v = rec.vars[k]
+    if (typeof v === "string" && v) env[k] = v
+    else if (k !== "PATH") delete env[k]
+  }
+}
+
+export interface LoopOptions {
+  /** Stop after this many rounds (tests). */
+  rounds?: number
+  env?: Env
+  fetchImpl?: typeof fetch
+  say?: (line: string) => void
+  cli?: string
+}
+
+type Turn = { ours: true } | { ours: false; pid: number }
+
+/**
+ * This loop's turn for the home, read, judged and written under the brain lock (two loops starting at once never both
+ * run): another live loop keeps it; otherwise `state` is written as this loop's. Called every round, so a loop that lost
+ * its turn stops exchanging.
+ */
+function keepTurn(home: string, state: ServiceState, every: number): Turn {
+  return withBrainLockSync(
+    home,
+    () => {
+      const cur = readServiceState(home)
+      const mine = cur.pid === state.pid && cur.startedAt === state.startedAt
+      // Another loop has the turn while its process lives and it has run a round lately (as serviceState judges running):
+      // a process id reused by something else, where its start cannot be told (no ps), never holds it for good.
+      const last = cur.lastRunAt ? Date.parse(cur.lastRunAt) : cur.startedAt
+      const lately = typeof last === "number" && Number.isFinite(last) && Date.now() - last < Math.max(every, 60_000) * 12
+      if (!mine && lately && typeof cur.pid === "number" && typeof cur.startedAt === "number" && cur.pid !== process.pid && !holderGone({ pid: cur.pid, startedAt: cur.startedAt, at: "" }))
+        return { ours: false, pid: cur.pid }
+      writeServiceState(home, state)
+      return { ours: true }
+    },
+    { what: "the background service's turn" },
+  )
+}
+
+/**
+ * `brain service run`: the loop. Returns when it should stop: the brain on disk changed ("updated"), brain was removed
+ * from disk ("gone"), or (tests) after `rounds` ("another" when another loop had the home all along). A round that fails
+ * in any way is a failed round, never the end of the process.
+ */
+export async function runService(home: string, o: LoopOptions = {}): Promise<"stopped" | "another" | "updated" | "gone"> {
+  const env = o.env ?? process.env
+  const say = o.say ?? ((l: string) => process.stdout.write(`${new Date().toISOString()} ${l}\n`))
+  const cli = o.cli ?? CLI_PATH
+  // Recorded as this process judges itself (lock.ts), so its own reports say it runs.
+  const state: ServiceState = { pid: process.pid, startedAt: ownStart(), version: VERSION }
+  say(`brain service ${VERSION} started`)
+  const { exchange } = await import("./settings/account.ts")
+  const { sendingOff, sendReport, canReport } = await import("./dashboard/send.ts")
+  let failures = 0
+  let waiting: number | undefined
+  let everOurs = false
+  for (let round = 1; ; round++) {
+    let wait = loopEvery(env)
+    try {
+      refreshEnv(home, env)
+      // Gone twice, 2 s apart: `bun add -g` replaces the package with cli.ts missing for a few milliseconds.
+      if (!existsSync(cli) && (await Bun.sleep(2_000), !existsSync(cli))) {
+        say("brain is no longer on this computer: this service stops (brain service uninstall removes what is left)")
+        return "gone"
+      }
+      const now = versionOnDisk(cli)
+      if (now && now !== VERSION) {
+        say(`brain on disk is now ${now}: this ${VERSION} stops, and the system starts the new one`)
+        if (everOurs) keepTurn(home, { ...state, lastRunAt: new Date().toISOString() }, loopEvery(env))
+        return "updated"
+      }
+      const turn = keepTurn(home, state, loopEvery(env))
+      if (!turn.ours) {
+        if (waiting !== turn.pid) say(`another brain service runs for this home (process ${turn.pid}); this one waits until it stops`)
+        waiting = turn.pid
+        if (o.rounds && round >= o.rounds) return everOurs ? "stopped" : "another"
+        await Bun.sleep(wait)
+        continue
+      }
+      if (waiting !== undefined) say("the other brain service stopped: this one takes over")
+      waiting = undefined
+      everOurs = true
+      const x = await exchange(home, { env, timeoutMs: 10_000, ...(o.fetchImpl ? { fetchImpl: o.fetchImpl } : {}) })
+      const at = new Date().toISOString()
+      if (!x.paired) {
+        state.lastRunAt = at
+        delete state.lastError
+      } else if (x.ok) {
+        failures = 0
+        Object.assign(state, { lastRunAt: at, lastOkAt: at })
+        delete state.lastError
+      } else {
+        failures++
+        Object.assign(state, { lastRunAt: at, lastError: x.why ?? "unknown" })
+        say(`round failed: ${x.why}`)
+      }
+      // Written before the report: the report says this loop runs.
+      keepTurn(home, state, loopEvery(env))
+      if (x.ok && (x.received.length || x.applied.length)) {
+        say(`took ${x.received.length} change(s) from your account, applied ${x.applied.length}`)
+        // The dashboard sees the result at once.
+        if (canReport(home) && !sendingOff(home, env)) {
+          try {
+            const { buildReport } = await import("./dashboard/report.ts")
+            const r = await sendReport(home, await buildReport(home, { env }), o.fetchImpl ? { fetchImpl: o.fetchImpl } : {})
+            if (!r.ok) say(`report not sent: ${r.why}`)
+          } catch {}
+        }
+      }
+      wait = backoff(loopEvery(env), failures)
+    } catch (e) {
+      // The brain lock busy for long, a disk that is full, anything else: this round failed, the loop goes on.
+      failures++
+      state.lastRunAt = new Date().toISOString()
+      state.lastError = `the round stopped: ${String((e as Error)?.message ?? e).slice(0, 200)}`
+      say(state.lastError)
+      try {
+        if (everOurs) keepTurn(home, state, loopEvery(env))
+      } catch {}
+      wait = backoff(loopEvery(env), failures)
+    }
+    if (o.rounds && round >= o.rounds) return "stopped"
+    await Bun.sleep(wait)
+  }
+}
+
+// ---- the command ---------------------------------------------------------------------------------------------------------
+
+const USAGE = [
+  "brain service install     run brain in the background, so changes made in your dashboard apply here by themselves",
+  "brain service uninstall   stop it and remove it",
+  "brain service status      whether it is installed and running, and its last round",
+]
+
+export async function serviceCommand(args: string[], home: string, io: Io = { out: (l) => console.log(l) }): Promise<number> {
+  const sub = args[0]
+  switch (sub) {
+    case "install":
+      return installService(home, io)
+    case "uninstall":
+      return uninstallService(home, io)
+    case "status":
+    case undefined:
+      serviceStatusLines(home).forEach((l) => io.out(l))
+      return 0
+    case "run":
+      // Only a newer brain on disk (or a crash) has the system start it again; brain removed from disk stays stopped.
+      return (await runService(home)) === "updated" ? RESTART_EXIT : 0
+    default:
+      io.out(`unknown service command "${sub}"`)
+      USAGE.forEach((l) => io.out(`usage: ${l}`))
+      return 2
+  }
+}

package/src/settings/account.ts

@@ -18,7 +18,7 @@ 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 { checkValue, parseId, resolve } 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"
 
@@ -40,14 +40,16 @@ export function forgetMachineToken(home: string): boolean {
 /**
  * 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.
+ * starts from nothing, so the account's empty document never erases them. Not the dashboard's or an admin's: those are the
+ * account's to keep (a computer never sends them as its own; the gateway refuses that), and an account that forgot this
+ * computer forgot them too.
  */
 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
+      if ("error" in ref || ref.family.remote !== "yes" || !COMPUTER_SOURCES.includes(e.source)) 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 } : {}) })
     }
@@ -73,6 +75,8 @@ export interface Exchange {
 
 const LEVEL_OUT: Record<"computer" | "person", "machine" | "account"> = { computer: "machine", person: "account" }
 const SOURCES: Source[] = ["settings", "command", "dashboard", "admin", "local-page"]
+/** The sources a computer sends its changes with; the dashboard's and an admin's come only from the account. */
+const COMPUTER_SOURCES: Source[] = ["settings", "command", "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)
@@ -87,6 +91,9 @@ function entryFrom(id: string, level: Level, e: unknown): Entry | undefined {
   return { value: x.value, source: SOURCES.includes(x.source) ? x.source : "dashboard", at: x.at, ...(Number.isSafeInteger(x.rev) ? { rev: x.rev } : {}) }
 }
 
+const sameEntry = (x: Entry | undefined, y: Entry | undefined) =>
+  x === y || (!!x && !!y && same(x.value, y.value) && x.source === y.source && x.at === y.at && x.rev === y.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
@@ -120,8 +127,6 @@ export async function exchange(home: string, o: { env?: Env; fetchImpl?: typeof
   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()
@@ -162,6 +167,14 @@ export async function exchange(home: string, o: { env?: Env; fetchImpl?: typeof
   }
 
   try {
+    // A computer the account knows afresh: everything set here goes again (see sendAllAgain).
+    if (file.doc.sync.machine !== machine) sendAllAgain(home)
+    // A change this computer cannot send as its own (an older brain queued the dashboard's) would wait for good and keep
+    // the account's value from being taken: it leaves the outbox.
+    if (readSettingsFile(home).doc.outbox.some((c) => !COMPUTER_SOURCES.includes(c.source)))
+      updateDoc(home, (d) => {
+        d.outbox = d.outbox.filter((c) => COMPUTER_SOURCES.includes(c.source))
+      })
     // 1. Send what changed here.
     const snapshot = readSettingsFile(home).doc.outbox
     for (const level of ["computer", "person"] as const) {
@@ -220,6 +233,10 @@ export async function exchange(home: string, o: { env?: Env; fetchImpl?: typeof
         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}`))
+        // The levels as they were, to tell what taking the answer changes in the value in force here.
+        const before: SettingsDoc = { ...d, levels: { ...d.levels } }
+        // The same value written again on the account (a newer rev at another time: the dashboard's "try again").
+        const again: string[] = []
         const next: Record<"computer" | "person", Record<string, Entry>> = { computer: {}, person: {} }
         for (const [level, srv] of [
           ["computer", j.machine.entries],
@@ -235,8 +252,14 @@ export async function exchange(home: string, o: { env?: Env; fetchImpl?: typeof
             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
+            if (was && same(was.value, e.value) && was.source === e.source) {
+              if (e.rev !== undefined && was.rev !== undefined && e.rev > was.rev && e.at !== was.at) {
+                next[level][id] = { ...e, ...(was.command ? { command: was.command } : {}) }
+                again.push(id)
+              }
+              // The same value from the same source: kept as it is here (with the command that set it).
+              else next[level][id] = { ...was, ...(e.rev !== undefined ? { rev: e.rev } : {}) }
+            } else next[level][id] = e
           }
         }
         // Memory turned on from afar on a computer that sends it to a team server: only this computer turns that on. Judged
@@ -275,6 +298,20 @@ export async function exchange(home: string, o: { env?: Env; fetchImpl?: typeof
         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
+        // The value in force here set from the account (set, set again, the same value from another source, or cleared down
+        // to another level's equal value) is applied afresh, even where it failed or was changed by hand since: that is the
+        // person setting it (again). A change at a level that does not decide here applies nothing.
+        // A setting with nothing to apply set again is still taken, so what it gave is said (below, after applying).
+        for (const id of new Set([...out.received, ...again])) {
+          const ref = parseId(id)
+          if ("error" in ref) continue
+          const a = resolve(d, ref)
+          if (a.value === undefined || (a.from !== "computer" && a.from !== "person" && a.from !== "team")) continue
+          const b = resolve(before, ref)
+          if (b.from === a.from && sameEntry(b.entry, a.entry)) continue
+          if (ref.family.apply) delete d.applied[id]
+          if (!out.received.includes(id)) out.received.push(id)
+        }
         d.history = d.history.slice(-200)
         d.sync.rev = `${fetched[0]}.${fetched[1]}`
         d.sync.lastSyncAt = now
@@ -295,13 +332,31 @@ export async function exchange(home: string, o: { env?: Env; fetchImpl?: typeof
 
   // 4. Apply what changed, and say what it gave (a value held back here counts as failed).
   if (o.apply !== false) {
+    let elsewhere: string[] = []
     try {
-      out.applied = (await reconcile(home, { env: o.env ?? process.env })).applied
+      const r = await reconcile(home, { env: o.env ?? process.env })
+      out.applied = r.applied
+      elsewhere = r.elsewhere
     } catch {}
     const applied: Record<string, unknown> = {}
+    const at = new Date().toISOString()
     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() }
+      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 }
+    // A value taken that has nothing to apply (brain reads it where it is used: lean.*, memory.enabled) is in force once
+    // taken; one for a tool not on this computer waits for that tool. Both are said, so the dashboard never waits on them.
+    // (A value in force set from the account is applied afresh above, so it is among the applied rows.)
+    if (out.received.length) {
+      const doc = readSettingsFile(home).doc
+      for (const id of out.received) {
+        const ref = parseId(id)
+        if ("error" in ref || Object.hasOwn(applied, id) || out.held.some((h) => h.id === id)) continue
+        const want = resolve(doc, ref).value
+        if (want === undefined) continue
+        if (!ref.family.apply) applied[id] = { want, ok: true, at }
+        else if (elsewhere.includes(id)) applied[id] = { want, ok: false, error: `${ref.tool ?? "this tool"} is not on this computer: brain applies it once it is`, at }
+      }
+    }
+    for (const h of out.held) applied[h.id] = { want: true, ok: false, error: h.why, at }
     if (Object.keys(applied).length && Date.now() < deadline) {
       try {
         await call("POST", "/api/brain/settings/applied", { machine, applied })

package/src/settings/cli.ts

@@ -173,6 +173,9 @@ async function withAccount(home: string, env: Env, say: (l: string) => void, fet
   return x
 }
 
+/** An exchange that took or applied something changed what the report says (a cleared value shows only there). */
+export const tookSomething = (x: Exchange | undefined) => !!x?.ok && (x.received.length > 0 || x.applied.length > 0)
+
 /**
  * `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).
@@ -195,7 +198,7 @@ export async function settingsCommand(
   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)
+  if (["list", "get", "history", "set", "unset"].includes(sub) && !file.problem && tookSomething(await withAccount(home, env, note, hooks.fetchImpl, deadline))) hooks.changed?.()
   switch (sub) {
     case "list": {
       const ti = rest.indexOf("--tool")
@@ -262,7 +265,7 @@ export async function settingsCommand(
       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)
+      if (o.change && tookSomething(await withAccount(home, env, io.out, hooks.fetchImpl, deadline))) hooks.changed?.()
       return code
     }
     case "history": {
@@ -319,8 +322,10 @@ const productName = (alias: unknown) => (typeof alias === "string" && MODEL_ALIA
  * `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> {
+export async function statusCommand(home: string, io: Io = { out: (l) => console.log(l) }, env: Env = process.env, deps: { fetchImpl?: typeof fetch; changed?: () => void } = {}): Promise<number> {
   const exchanged = readSettingsFile(home).problem ? undefined : await exchange(home, { env, ...(deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {}) })
+  // What it took from the account goes to the dashboard in a report too (the computer may have no background service).
+  if (tookSomething(exchanged)) deps.changed?.()
   const { VERSION } = await import("../self.ts")
   const { machineName, gatewayState } = await import("../dashboard/report.ts")
   const { machineId, readCache } = await import("../dashboard/state.ts")
@@ -392,6 +397,8 @@ export async function statusCommand(home: string, io: Io = { out: (l) => console
   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 { serviceStatusLines } = await import("../service.ts")
+  if (acct.paired) serviceStatusLines(home).forEach((l) => io.out(l))
   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"] : [])]

package/src/settings/env.ts

@@ -95,6 +95,8 @@ export function isPersonsCommand(argv: string[]): boolean {
   // 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
+  // The background service is started by launchd or systemd, with the environment it was given, not the person's shell.
+  if (cmd === "service" && rest[0] === "run") 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

@@ -79,5 +79,8 @@ export async function pairCommand(args: string[], home: string, io: Io = { out:
   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)
+  const { serviceState } = await import("../service.ts")
+  // macOS and Linux only for now; elsewhere `brain sync` takes the dashboard's changes.
+  if ((process.platform === "darwin" || process.platform === "linux") && !serviceState(home).installed) io.out("next: `brain service install` runs brain in the background, so changes you make in the dashboard apply here by themselves.")
   return 0
 }