Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Merge master into capy/gbra202-docs-doctor-wave
garrytanbe9328f0f038
diff --cc INSTALL_FOR_AGENTS.mdindex 4f1cbbd85b,938a7178a8..575785d4bc--- a/INSTALL_FOR_AGENTS.md+++ b/INSTALL_FOR_AGENTS.md@@@ -42,17 -30,23 +42,17 @@@ If you fetched this file by URL withou## Step 1: Install GBrain<!-- npm-trap + #218 recovery: canonical copy lives in README.md ("Install" warning) — sync edits. -->-> **NEVER install from the npm registry.** GBrain is not distributed on npm; the npm-> package named `gbrain` is an unrelated package. Do NOT run `npm install -g gbrain` or-> `bun add -g gbrain` (note the missing `github:` prefix — that's the trap). The only-> supported sources are `github:garrytan/gbrain` (optionally pinned as-> `github:garrytan/gbrain#latest-stable`, the form the bootstrap flow mandates) and a-> git clone, exactly as shown below.-> If an unrelated npm install is already present, remove it first-> (`npm uninstall -g gbrain` / `bun remove -g gbrain`); `gbrain doctor` also detects this.--> **On Codex or Claude Code?** After the CLI install below, the plugin is the-> fastest way to wire the MCP server + curated skills:-> `codex plugin marketplace add garrytan/gbrain@codex-plugin` +-> `codex plugin add gbrain@gbrain` (Claude Code: `/plugin marketplace add-> garrytan/gbrain` + `/plugin install gbrain@gbrain`). Details:-> docs/mcp/CODEX.md and docs/mcp/CLAUDE_CODE.md.+> **NEVER install from the npm registry.** The npm package named `gbrain` is unrelated and+> can shadow the real binary. Never run `npm install -g gbrain` or `bun add -g gbrain` (the+> missing `github:` prefix is the trap). Install only `github:garrytan/gbrain#latest-stable`+> (plain `github:garrytan/gbrain` installs master) or a git clone, as below. Already installed+> from npm? Remove it (`npm uninstall -g gbrain` / `bun remove -g gbrain`); `gbrain doctor` detects it.++> **On Codex or Claude Code?** After the install, the plugin wires MCP plus curated skills:+> `codex plugin marketplace add garrytan/gbrain@codex-plugin` + `codex plugin add gbrain@gbrain`+> (Claude Code: `/plugin marketplace add garrytan/gbrain` + `/plugin install gbrain@gbrain`).- Default path (Bun 1.4.0 or newer is required — gbrain is a Bun + TypeScript runtime; on an older Bun, run `bun upgrade` first):+ Default path (Bun 1.4.4 or newer is required — gbrain is a Bun + TypeScript runtime; on an older Bun, run `bun upgrade` first):```bashcurl -fsSL https://bun.sh/install | bashdiff --cc README.mdindex c5121e4c7a,ee8178a7c4..628abd0d1d--- a/README.md+++ b/README.md@@@ -90,38 -88,31 +90,38 @@@ This is the difference between a searc## Install-Requires **Bun 1.4.4 or newer**. Existing worker installations should follow the-[authorization and queue upgrade guide](docs/guides/authorization-upgrade.md)-before restarting services with this version.+> [!TIP]+> **Fastest: hosted GBrain at [gbrain.io](https://gbrain.io/cli?ref=readme), for any harness.** One command launches a GBrain hosted on gbrain.io; Claude Code, Codex, ChatGPT, Cursor and every other AI you use connect to it, with nothing to keep online.+>+> ```bash+> curl -sSL https://gbrainio.terminalwire.sh | bash+> gbrainio terminal connect # in a new terminal+> gbrainio workspace new # pick a plan in the browser+> claude mcp add --transport http --scope user gbrain https://gbrain.io/mcp+> codex mcp add gbrain --url https://gbrain.io/mcp+> ```+>+> The installer is a shell script for macOS and Linux; read it before you run it.++### Here's how to self-host it+- GBrain is MIT-licensed and free to self-host. It needs **Bun 1.4.0 or newer**; existing worker installs read the [authorization and queue upgrade guide](docs/guides/authorization-upgrade.md) before restarting on this version.++GBrain is MIT-licensed and free to self-host. It needs **Bun 1.4.4 or newer**; existing worker installs read the [authorization and queue upgrade guide](docs/guides/authorization-upgrade.md) before restarting on this version.> [!WARNING]> **GBrain is NOT distributed on npm.** The npm `gbrain` package is unrelated and> can shadow the real binary, so never run `npm install -g gbrain` or-> `bun add -g gbrain`. Install only via `bun install -g github:garrytan/gbrain`-> or `git clone` + `bun install && bun link`.-> Installed it by mistake? `npm uninstall -g gbrain` / `bun remove -g gbrain`, then-> reinstall; `gbrain doctor` detects it.-> Schema not migrated ([#218](https://github.com/garrytan/gbrain/issues/218))?-> Run `gbrain apply-migrations --yes --no-autopilot-install`; exit 1 means it's still-> behind: run `gbrain doctor --json`, not `--yes` (`wedged`: relay its fix).--**Claude Code or Codex, fastest path:**+> `bun add -g gbrain`. Install only via `bun install -g github:garrytan/gbrain#latest-stable`+> or `git clone` + `bun install && bun link`. Installed by mistake? `gbrain doctor` gives the fix.+> Schema not migrated ([#218](https://github.com/garrytan/gbrain/issues/218))? Run+> `gbrain apply-migrations --yes --no-autopilot-install`; if it exits 1, run `gbrain doctor --json`, not another `--yes` (`wedged`: relay its fix).```bash-bun install -g github:garrytan/gbrain-gbrain setup claude-code # or codex; --dry-run previews, --remove undoes+bun install -g github:garrytan/gbrain#latest-stable+gbrain setup claude-code # or: gbrain setup codex+gbrain init --pglite --no-embedding # any other harness, or no agent```- `gbrain setup` shows what it will write first (`--dry-run` previews, `--remove` undoes), creates a keyless brain only if none exists, wires MCP and hooks, and smoke-tests them ([setup guide](docs/guides/setup.md)). For any other coding agent, paste:-`setup` shows the brain, source, launcher and owner it resolved before writing, runs `gbrain init --pglite --no-embedding` only when no brain exists, writes the stdio MCP entry, read-context hooks (owned by hash, plus Codex hook trust) and a brain-first block in its instruction file (`--no-instructions` skips it), and smoke-tests them. Capture and providers stay off unless accepted; a hosted brain keeps `gbrain connect --install`. [Setup guide](docs/guides/setup.md).--Start with the agent you already use. For Grok Bot and Muse, the dedicated guides above install an isolated launcher, repairable runtime, and memory in a verified persistent directory. For a coding agent, paste:++`gbrain setup` shows what it will write first (`--dry-run` previews, `--remove` undoes), creates a keyless brain only if none exists, wires MCP, hooks and a brain-first block in the agent's instruction file (`--no-instructions` skips it), and smoke-tests them ([setup guide](docs/guides/setup.md)). For any other coding agent, paste:```textAdd GBrain memory to this existing agent. Read and follow:@@@ -158,12 -216,41 +158,12 @@@ The repo is not a complete backup; see### Connect GBrain to your AI client (MCP)- - **Local stdio client:** `claude mcp add gbrain -- "$(command -v gbrain)" serve --surface full`; Codex, Cursor, Windsurf and other stdio clients take the same command.-For a hosted brain, start with the [native OAuth and private machine connection guide](docs/guides/hosted-harness-access.md). To open the dashboard, register clients, edit access, or invalidate tokens, use [MCP administration](docs/mcp/ADMIN.md). A **profile** controls MCP authority; a **surface** controls which granted tools are visible. Neither grants owner dashboard access. New memory profiles use the full surface. `--surface verbs` retains exactly the seven memory verbs, with orientation available through `gbrain://capabilities`. Thin CLI connections use the full surface and remain restricted by their grants.--Pick your product, then run `gbrain setup <harness> --instructions-only`: agents seldom call a brain nobody told them about.--**Upgrading a brain indexed before v0.48.3.0?** Rebuild its search chunks first: [upgrade recovery guide](skills/migrations/v0.48.3.0.md). **Say to your agent:** *"Upgrade gbrain and check whether my search index needs rebuilding."*--- **[Claude Code](docs/mcp/CLAUDE_CODE.md)** — plugin: `/plugin marketplace add garrytan/gbrain` + `/plugin install gbrain@gbrain` (MCP + skills; persona variants `gbrain-coding` / `gbrain-daily` install curated subsets; pick one). Marketplace-free skills: `gbrain skillpack scaffold --harness claude-code` copies a persona-curated skill set into your user-scope skills dir. Or by hand: `claude mcp add gbrain -- "$(command -v gbrain)" serve`. Remote with just a bearer token: `gbrain connect https://your-host/mcp --token gbrain_xxx` prints a paste-ready block (or `--install` wires it up and smoke-tests the token).-- **[Codex](docs/mcp/CODEX.md)** — plugin (recommended): `codex plugin marketplace add garrytan/gbrain@codex-plugin` + `codex plugin add gbrain@gbrain` installs the MCP server AND the curated skill set. Or connect-only: `gbrain connect https://your-host/mcp --token gbrain_xxx --agent codex` (or `--install`); the token path reads `$GBRAIN_REMOTE_TOKEN` at runtime, while the private-handoff installer writes a private managed HTTP header so the connection survives a new shell.-- **[Cursor / Windsurf / any stdio MCP client](docs/mcp/CLAUDE_CODE.md)** — same shape, add `{"command": "gbrain", "args": ["serve", "--surface", "full"]}` to your MCP config.-- **[Hermes](docs/mcp/HERMES.md)** — `printf 'Y\n' | hermes mcp add gbrain --env GBRAIN_HOME=$HOME --connect-timeout 60 --command $(which gbrain) --args serve --surface starter`. Keep `--args` last, and verify with `hermes mcp test gbrain` (the add exits 0 even on failure).-- **[Grok Bot](docs/guides/grok-bot.md)** — recommended: keep the brain on your computer, publish it with `gbrain mcp expose --funnel`, grant the Bot a `memory-writer` client and install the thin CLI at `/workspace/gbrain`; or install memory inside the Bot computer when no machine of yours stays online. Bots share local files and credentials; sources organize memory without isolating Bots. **Say to your agent:** *"connect grok bot to my brain"*.-- **[Muse personal agent](docs/guides/muse.md)** — first verify its durable user-files location; then either connect it to your published brain (`gbrain mcp expose --funnel` + thin CLI) or install the local CLI there. Native MCP configuration and skill activation are not assumed. **Say to your agent:** *"connect muse to my brain"*.-- **[Grok Build](docs/mcp/GROK.md)** — `grok mcp add gbrain -e "GBRAIN_HOME=$HOME" -- "$(command -v gbrain)" serve --surface starter`. The add is lazy (exit 0 without connecting) — verify with `grok mcp doctor gbrain`, which spawns the server. Verified against Grok Build v1.0.4.-- **[opencode](docs/mcp/OPENCODE.md)** (opencode.ai / SST — not OpenClaw) — `opencode mcp add gbrain --env GBRAIN_HOME=$HOME -- "$(command -v gbrain)" serve --surface starter`, or let `gbrain bootstrap hooks --harness opencode` write the config for you. The add is lazy — verify with `opencode mcp list`, which spawns the server (`✓ gbrain connected`). Remote: `gbrain connect https://your-host/mcp --token gbrain_xxx --agent opencode [--install]` — the config stores only the `{env:GBRAIN_REMOTE_TOKEN}` interpolation. Verified against opencode v1.18.18.-- **[OpenClaw](docs/mcp/OPENCLAW.md)** — the ClawHub bundle plugin registers gbrain automatically (`openclaw.plugin.json` ships in this repo), or register the stdio server with `openclaw mcp add gbrain --command "$(command -v gbrain)" --arg serve --env GBRAIN_HOME=$HOME` (absolute path: the launchd gateway PATH lacks `~/.bun/bin`); verify with `openclaw mcp list`.-- **[Claude Desktop (Cowork)](docs/mcp/CLAUDE_DESKTOP.md)** — Settings → Integrations → add the URL of your HTTP server. Remote only; the local `claude_desktop_config.json` does not work for remote servers.-- **[Claude Cowork (team plan)](docs/mcp/CLAUDE_COWORK.md)** — org Owner adds the connector under Organization Settings → Connectors.-- **[Perplexity Computer](docs/mcp/PERPLEXITY.md)** — choose native OAuth or a managed bearer connection according to the actual connector settings. The owner registers the matching client and delivers any confidential credentials privately.-- **[ChatGPT](docs/mcp/CHATGPT.md)** — native OAuth with PKCE. Register the exact callback and token authentication method shown in its MCP settings, then start the connection in ChatGPT and complete owner consent.--For the HTTP server itself:--```bash-gbrain serve # stdio MCP (local subprocess; for Claude Code, Cursor, Windsurf)-gbrain serve --http # HTTP MCP with OAuth 2.1 + admin dashboard at /admin- # (required for Claude Desktop, Cowork, Perplexity, ChatGPT)-gbrain mcp expose # publish serve --http on your Tailscale tailnet with HTTPS + a user service-gbrain mcp expose --funnel # same name, public HTTPS — for agents that run in a vendor's cloud-```--`gbrain mcp expose` is the recommended way to run the server from your own computer: it installs Tailscale if needed (after a consent prompt), signs in, publishes the server on `https://your-machine.your-tailnet.ts.net/mcp`, keeps the admin token in a private file, installs a launchd / systemd user service, and prints separate owner-login, native OAuth, and machine-client next steps (`--status` re-checks, `--remove` undoes only its own changes). Local coding agents on the same machine: `gbrain bootstrap harness --yes --port 3131` on a Postgres brain; on PGLite mint a token before the service runs (`gbrain auth create local-agents --scopes read,write`) and pass `--token`, or grant a scoped client through the running server (`gbrain mcp grant … --admin-token-file ~/.gbrain/serve/admin-token`). Tailnet-only by default; `--funnel` is the explicit opt-in for cloud agents. **Say to your agent:** *"use my brain over mcp"* — *"reach my brain from my phone"*. Guide: [use your brain from anywhere over MCP](docs/guides/remote-mcp.md).--The HTTP server includes optional dynamic client registration, scope-gated access (`read` / `write` / `admin` / `agent`), owner-approved OAuth authorization, and rate limiting. Dynamic registration cannot grant delegation; `admin` implies neither `agent` nor owner administration. Start with the [MCP task guide](docs/mcp/README.md) for deployment, client setup, administration, and alternatives to Tailscale (ngrok, Railway, Fly.io).++- **Local stdio client:** `claude mcp add gbrain -- "$(command -v gbrain)" serve --surface starter` (`--surface full` lists every tool); Codex, Cursor, Windsurf and other stdio clients take the same command. Then run `gbrain setup <harness> --instructions-only`: agents seldom call a brain nobody told them about.+- **Plugins with curated skills:** Codex `codex plugin marketplace add garrytan/gbrain@codex-plugin` + `codex plugin add gbrain@gbrain`; Claude Code `/plugin marketplace add garrytan/gbrain` + `/plugin install gbrain@gbrain`.+- **This brain from anywhere:** `gbrain mcp expose` publishes it on your Tailscale tailnet as a user service (`--funnel` for cloud agents such as Grok Bot, Muse and ChatGPT). [Guide](docs/guides/remote-mcp.md).+- **A brain on another host:** `gbrain connect https://your-host/mcp --token gbrain_xxx --install` (add `--agent codex` for Codex). Hosted brains use [native OAuth or a private handoff](docs/guides/hosted-harness-access.md); dashboard, clients and permissions live in [MCP administration](docs/mcp/ADMIN.md).-Running several brains behind one tool catalog? Give each one an identity with `gbrain config set mcp.instructions "<identity>"` so a connected agent can tell them apart ([details](docs/mcp/DEPLOY.md#operations)). **Say to your agent:** *"Tell connected agents which brain this is"*.+Per-client guides: [Claude Code](docs/mcp/CLAUDE_CODE.md) · [Codex](docs/mcp/CODEX.md) · [ChatGPT](docs/mcp/CHATGPT.md) · [Claude Desktop](docs/mcp/CLAUDE_DESKTOP.md) · [Claude Cowork](docs/mcp/CLAUDE_COWORK.md) · [Perplexity](docs/mcp/PERPLEXITY.md) · [Hermes](docs/mcp/HERMES.md) · [OpenClaw](docs/mcp/OPENCLAW.md) · [opencode](docs/mcp/OPENCODE.md) · [Grok Build](docs/mcp/GROK.md) · [Grok Bot](docs/guides/grok-bot.md) · [Muse](docs/guides/muse.md) · [everything MCP](docs/mcp/README.md).## Two ways to query your braindiff --cc docs/architecture/key-files/files-and-sync-1.mdindex 92687b80c6,60733422ea..0918898eb9--- a/docs/architecture/key-files/files-and-sync-1.md+++ b/docs/architecture/key-files/files-and-sync-1.md@@@ -5,7 -5,7 +5,7 @@@ Current behavior and load-bearing invar- `src/core/audit-week-file.ts` — single source of truth for ISO-week audit JSONL filename math. Exports `isoWeek(d)`, `isoWeekFilename(prefix, now?)`, `resolveAuditDir()` (honors `GBRAIN_AUDIT_DIR`). Year-boundary correctness pinned by tests at 2020-W53 (the 53-week year), 2025-W01 rolling in from 2024-12-30 (Monday), 2026-W01. Four call sites: `src/core/minions/handlers/shell-audit.ts`, `src/core/facts/phantom-audit.ts`, `src/core/audit-slug-fallback.ts`, `src/core/cycle/budget-meter.ts`. Each keeps its `compute<X>AuditFilename` thin wrapper.- - `src/core/brain-repo-durability.ts` + `src/commands/sources-harden.ts` — brain-repo git durability. `hardenBrainRepo(opts)` makes a brain's working tree durable, idempotently: divergence-safe pull, a LOCAL untracked `.git/hooks/post-commit` auto-push safety net (never committed — a pulled commit can't rewrite executed code next to the token; installed into the active `core.hooksPath` dir and excluded via `.git/info/exclude` when that dir is tracked), a committed `scripts/brain-commit-push.sh` delegating to `gbrain git commit-push` (`src/core/git/commit-push.ts`, #6530; guide `docs/guides/shared-checkout-git.md`) that never exits 0 without a confirmed push, and a hook running the harden-captured CLI with `--push-only --require-clean` (both `# gbrain-protocol: 2`; harden never downgrades), durability rules patched into the active resolver file (`findResolverFile` → RESOLVER.md > AGENTS.md; taxonomy from the repo's own `_brain-filing-rules.json`, else its top-level content folders, else the bundled default, #7629), a minimal DB-free pull cron (launchd/crontab running `gbrain sources pull --path <dir>` so it never opens the PGLite single-writer lock), and a push-probe verify (no heartbeat commit). Credential is REPO-scoped (`acceptPat` from `--pat-file`/`GBRAIN_GITHUB_PAT`, warns on loose perms; reuses an existing repo-local `credential.helper`, else a `0600` store wired via repo-local config); the token is redacted everywhere via `redactSecretsInText` and never enters the repo, remote URL, logs, or `DurabilityReport`. `unhardenBrainRepo` removes the cron/hook/credential wiring (ownership-fingerprinted); `sources remove` runs it only AFTER the source row's DELETE commits (a refused or raced delete leaves the scaffolding intact; post-commit teardown failure is loud but non-fatal). CLI: `gbrain sources harden <id|--all>` / `pull <id>|--path <dir>` / `unharden <id>`; auto-harden fires on `sources add --url ... --pat-file` for managed clones (`--no-harden` opts out). `sources pull --path` is dispatched in `src/cli.ts` BEFORE `connectEngine` so the cron stays DB-free. CLI-only (writes executables + an OS cron + a credential helper on the host); never exposed over MCP. `isDurabilityHardened(repoPath)` (the durability hook banner is installed) and `commitWriteThroughFile(repoPath, absPath, slug, action = 'write-through')` are the shared helpers every write-through sink (page write/delete, facts fence, timeline, lint --fix) uses to best-effort commit ONE file path-limited on a hardened repo — never throws, false on any failure; `action` only labels the subject (`gbrain: <action> <slug>`; `'delete write-through'` for removals). `isDurabilityHardenedAsync(repoPath)` is the owners' non-blocking probe (#6210: rejects `git_unavailable` when unsure); it and the persistence Git runner (`effect-git.ts`) spawn through `execFileBounded` (defined in the import-free `src/core/bounded-child-exec.ts` and re-exported here; `git-remote.ts` `pullRepo` shares it), which settles at its deadline or on abort from its own timer because Bun can drop a child's pipe events and, before 1.3.14, its exit event (oven-sh/bun#30301) when bun:test `expect().resolves/.rejects` re-enters the event loop; an unbounded wait there stranded `disposePersistenceConsumer` and hung every later test in the file (test: `test/bounded-child-exec.test.ts`). Tests: `test/brain-repo-durability.serial.test.ts`, `test/git-remote-durable.serial.test.ts`, `test/brain-durability-hook.serial.test.ts`, `test/durability-cron.test.ts`. `brain_remote_contains_commit` checks the exact `refs/heads/<branch>` at every effective push URL, fetches each advertised tip without writing `FETCH_HEAD`, and proves ancestry of the captured commit; branch existence, a different fetch destination, or a stale tracking ref is not enough. Probe diagnostics are suppressed, ambiguous URL resolution fails closed, and recovery is skipped if local HEAD has moved since the failed push. This check runs after a rejected push and after retry failure, logging `ok-already-on-remote` on confirmation; `getLastPushOutcome` recognizes it as success. Existing unmanaged installations must rerun `gbrain sources harden <source-id>` to refresh both the local hook and committed helper; upgrading the CLI alone does not rewrite those scripts. Managed worktrees retain the persistence outbox as their Git writer; generated legacy helpers refuse to bypass it. Locks, waits, outcomes and the per-checkout conflict record: the guide. Tests: `test/git-commit-push-6530.serial.test.ts`.-- `src/core/brain-repo-durability.ts` + `src/commands/sources-harden.ts` — brain-repo git durability. `hardenBrainRepo(opts)` makes a brain's working tree durable, idempotently: divergence-safe pull, a LOCAL untracked `.git/hooks/post-commit` auto-push safety net (never committed — a pulled commit can't rewrite executed code next to the token; installed into the active `core.hooksPath` dir and excluded via `.git/info/exclude` when that dir is tracked), a committed `scripts/brain-commit-push.sh` delegating to `gbrain git commit-push` (`src/core/git/commit-push.ts`, #6530; guide `docs/guides/shared-checkout-git.md`) that never exits 0 without a confirmed push, and a hook running the harden-captured CLI with `--push-only --require-clean` (both `# gbrain-protocol: 2`; harden never downgrades), durability rules patched into the active resolver file (`findResolverFile` → RESOLVER.md > AGENTS.md; taxonomy rendered from the bundled `_brain-filing-rules.json`), a minimal DB-free pull cron (launchd/crontab running `gbrain sources pull --path <dir>` so it never opens the PGLite single-writer lock), and a push-probe verify (no heartbeat commit). Credential is REPO-scoped (`acceptPat` from `--pat-file`/`GBRAIN_GITHUB_PAT`, warns on loose perms; reuses an existing repo-local `credential.helper`, else a `0600` store wired via repo-local config); the token is redacted everywhere via `redactSecretsInText` and never enters the repo, remote URL, logs, or `DurabilityReport`. `unhardenBrainRepo` removes the cron/hook/credential wiring (ownership-fingerprinted); `sources remove` runs it only AFTER the source row's DELETE commits (a refused or raced delete leaves the scaffolding intact; post-commit teardown failure is loud but non-fatal). CLI: `gbrain sources harden <id|--all>` / `pull <id>|--path <dir>` / `unharden <id>`; auto-harden fires on `sources add --url ... --pat-file` for managed clones (`--no-harden` opts out). `sources pull --path` is dispatched in `src/cli.ts` BEFORE `connectEngine` so the cron stays DB-free. CLI-only (writes executables + an OS cron + a credential helper on the host); never exposed over MCP. `isDurabilityHardened(repoPath)` (the durability hook banner is installed) and `commitWriteThroughFile(repoPath, absPath, slug, action = 'write-through')` are the shared helpers every write-through sink (page write/delete, facts fence, timeline, lint --fix) uses to best-effort commit ONE file path-limited on a hardened repo — never throws, false on any failure; `action` only labels the subject (`gbrain: <action> <slug>`; `'delete write-through'` for removals). `isDurabilityHardenedAsync(repoPath)` is the owners' non-blocking probe (#6210: rejects `git_unavailable` when unsure); it and the persistence Git runner (`effect-git.ts`) spawn through `execFileBounded` (defined in the import-free `src/core/bounded-child-exec.ts` and re-exported here; `git-remote.ts` `pullRepo` shares it), which settles at its deadline or on abort from its own timer because Bun can drop a child's pipe events and, before 1.3.14, its exit event (oven-sh/bun#30301) when bun:test `expect().resolves/.rejects` re-enters the event loop; an unbounded wait there stranded `disposePersistenceConsumer` and hung every later test in the file (test: `test/bounded-child-exec.test.ts`). Tests: `test/brain-repo-durability.serial.test.ts`, `test/git-remote-durable.serial.test.ts`, `test/brain-durability-hook.serial.test.ts`, `test/durability-cron.test.ts`. `brain_remote_contains_commit` checks the exact `refs/heads/<branch>` at every effective push URL, fetches each advertised tip without writing `FETCH_HEAD`, and proves ancestry of the captured commit; branch existence, a different fetch destination, or a stale tracking ref is not enough. Probe diagnostics are suppressed, ambiguous URL resolution fails closed, and recovery is skipped if local HEAD has moved since the failed push. This check runs after a rejected push and after retry failure, logging `ok-already-on-remote` on confirmation; `getLastPushOutcome` recognizes it as success. Existing unmanaged installations must rerun `gbrain sources harden <source-id>` to refresh both the local hook and committed helper; upgrading the CLI alone does not rewrite those scripts. Managed worktrees retain the persistence outbox as their Git writer; generated legacy helpers refuse to bypass it. Locks, waits, outcomes and the per-checkout conflict record: the guide. Tests: `test/git-commit-push-6530.serial.test.ts`.++- `src/core/brain-repo-durability.ts` + `src/commands/sources-harden.ts` — brain-repo git durability. `hardenBrainRepo(opts)` makes a brain's working tree durable, idempotently: divergence-safe pull, a LOCAL untracked `.git/hooks/post-commit` auto-push safety net (never committed — a pulled commit can't rewrite executed code next to the token; installed into the active `core.hooksPath` dir and excluded via `.git/info/exclude` when that dir is tracked), a committed `scripts/brain-commit-push.sh` delegating to `gbrain git commit-push` (`src/core/git/commit-push.ts`, #6530; guide `docs/guides/shared-checkout-git.md`) that never exits 0 without a confirmed push, and a hook running the harden-captured CLI with `--push-only --require-clean` (both `# gbrain-protocol: 2`; harden never downgrades), durability rules patched into the active resolver file (`findResolverFile` → RESOLVER.md > AGENTS.md; taxonomy: repo `_brain-filing-rules.json`, else top folders, else bundled, #7629), a minimal DB-free pull cron (launchd/crontab running `gbrain sources pull --path <dir>` so it never opens the PGLite single-writer lock), and a push-probe verify (no heartbeat commit). Credential is REPO-scoped (`acceptPat` from `--pat-file`/`GBRAIN_GITHUB_PAT`, warns on loose perms; reuses an existing repo-local `credential.helper`, else a `0600` store wired via repo-local config); the token is redacted everywhere via `redactSecretsInText` and never enters the repo, remote URL, logs, or `DurabilityReport`. `unhardenBrainRepo` removes the cron/hook/credential wiring (ownership-fingerprinted); `sources remove` runs it only AFTER the source row's DELETE commits (a refused or raced delete leaves the scaffolding intact; post-commit teardown failure is loud but non-fatal). CLI: `gbrain sources harden <id|--all>` / `pull <id>|--path <dir>` / `unharden <id>`; auto-harden fires on `sources add --url ... --pat-file` for managed clones (`--no-harden` opts out). `sources pull --path` is dispatched in `src/cli.ts` BEFORE `connectEngine` so the cron stays DB-free. CLI-only (writes executables + an OS cron + a credential helper on the host); never exposed over MCP. `isDurabilityHardened(repoPath)` (the durability hook banner is installed) and `commitWriteThroughFile(repoPath, absPath, slug, action = 'write-through')` are the shared helpers every write-through sink (page write/delete, facts fence, timeline, lint --fix) uses to best-effort commit ONE file path-limited on a hardened repo — never throws, false on any failure; `action` only labels the subject (`gbrain: <action> <slug>`; `'delete write-through'` for removals). `isDurabilityHardenedAsync(repoPath)` is the owners' non-blocking probe (#6210: rejects `git_unavailable` when unsure); it and the persistence Git runner (`effect-git.ts`) spawn through `execFileBounded` (defined in the import-free `src/core/bounded-child-exec.ts` and re-exported here; `git-remote.ts` `pullRepo` shares it), which settles at its deadline or on abort from its own timer because Bun can drop a child's pipe events and, before 1.3.14, its exit event (oven-sh/bun#30301) when bun:test `expect().resolves/.rejects` re-enters the event loop; an unbounded wait there stranded `disposePersistenceConsumer` and hung every later test in the file (test: `test/bounded-child-exec.test.ts`). Tests: `test/brain-repo-durability.serial.test.ts`, `test/git-remote-durable.serial.test.ts`, `test/brain-durability-hook.serial.test.ts`, `test/durability-cron.test.ts`. `brain_remote_contains_commit` checks the exact `refs/heads/<branch>` at every effective push URL, fetches each advertised tip without writing `FETCH_HEAD`, and proves ancestry of the captured commit; branch existence, a different fetch destination, or a stale tracking ref is not enough. Probe diagnostics are suppressed, ambiguous URL resolution fails closed, and recovery is skipped if local HEAD has moved since the failed push. This check runs after a rejected push and after retry failure, logging `ok-already-on-remote` on confirmation; `getLastPushOutcome` recognizes it as success. Existing unmanaged installations must rerun `gbrain sources harden <source-id>` to refresh both the local hook and committed helper; upgrading the CLI alone does not rewrite those scripts. Managed worktrees retain the persistence outbox as their Git writer; generated legacy helpers refuse to bypass it. Locks, waits, outcomes and the per-checkout conflict record: the guide. Tests: `test/git-commit-push-6530.serial.test.ts`.- `src/core/classic-file-holds.ts` — classic sync's deterministic per-file refusals as holds in the shared hold store. `classifyClassicFile(root, relPath, gitRoot)` reads metadata only (lstat, the symlink target's realpath, an open+close of a regular file; for a missing path `git ls-tree HEAD` and `git ls-files -v` with optional locks off) and returns `file_unreadable` (`symlink_in_repo`, `symlink_outside_root`, `symlink_dangling`, `symlink_loop`, `permission_denied`, `not_regular_file`), `absent_from_worktree` (`skip_worktree`, `deleted_locally`), or null (a readable file, a directory, a path HEAD lacks, any other error, all left to the drain's existing paths). `classicFileHoldFix` is `gitHoldFix`'s builder for both codes: the user's step for a symlink or permission, `ask_user` between restore and committing the deletion for an absent file; `<checkout>` is an `inputs` placeholder. Pinned by `test/pathological/s-classic-file-holds.test.ts` (+ its Postgres wrapper).- `src/core/classic-rename-holds.ts` — `gitHoldFix`'s builder for classic sync's two rename holds (GBRA-133): `rename_identity_unreadable` (S-51; the database refused to compare a renamed file's title or id, so the new file waits and the old page stays whole; written by `holdUnreadableRenames` in `src/commands/sync/holds.ts` and decided again by `redecideUnreadableRenames` when the file changes) and `rename_reconcile_failed` (S-67; the `renames.ts` reconcile threw something other than its unprovable verdict or a transient database error while finding stale rows, so the rename is held with the error's class and code only; a failed delete keeps the `<rename:…>` marker). Both fixes are the user's. Pinned by `test/pathological/s-51-rename-identity-unreadable.test.ts` and `test/pathological/s-70-classifier-origin.test.ts`.diff --cc llms-full.txtindex ffa9a8b246,fe2131f05b..42bbcbc55a--- a/llms-full.txt+++ b/llms-full.txt@@@ -2693,17 -2695,23 +2706,17 @@@ If you fetched this file by URL withou## Step 1: Install GBrain<!-- npm-trap + #218 recovery: canonical copy lives in README.md ("Install" warning) — sync edits. -->-> **NEVER install from the npm registry.** GBrain is not distributed on npm; the npm-> package named `gbrain` is an unrelated package. Do NOT run `npm install -g gbrain` or-> `bun add -g gbrain` (note the missing `github:` prefix — that's the trap). The only-> supported sources are `github:garrytan/gbrain` (optionally pinned as-> `github:garrytan/gbrain#latest-stable`, the form the bootstrap flow mandates) and a-> git clone, exactly as shown below.-> If an unrelated npm install is already present, remove it first-> (`npm uninstall -g gbrain` / `bun remove -g gbrain`); `gbrain doctor` also detects this.--> **On Codex or Claude Code?** After the CLI install below, the plugin is the-> fastest way to wire the MCP server + curated skills:-> `codex plugin marketplace add garrytan/gbrain@codex-plugin` +-> `codex plugin add gbrain@gbrain` (Claude Code: `/plugin marketplace add-> garrytan/gbrain` + `/plugin install gbrain@gbrain`). Details:-> docs/mcp/CODEX.md and docs/mcp/CLAUDE_CODE.md.+> **NEVER install from the npm registry.** The npm package named `gbrain` is unrelated and+> can shadow the real binary. Never run `npm install -g gbrain` or `bun add -g gbrain` (the+> missing `github:` prefix is the trap). Install only `github:garrytan/gbrain#latest-stable`+> (plain `github:garrytan/gbrain` installs master) or a git clone, as below. Already installed+> from npm? Remove it (`npm uninstall -g gbrain` / `bun remove -g gbrain`); `gbrain doctor` detects it.++> **On Codex or Claude Code?** After the install, the plugin wires MCP plus curated skills:+> `codex plugin marketplace add garrytan/gbrain@codex-plugin` + `codex plugin add gbrain@gbrain`+> (Claude Code: `/plugin marketplace add garrytan/gbrain` + `/plugin install gbrain@gbrain`).- Default path (Bun 1.4.0 or newer is required — gbrain is a Bun + TypeScript runtime; on an older Bun, run `bun upgrade` first):+ Default path (Bun 1.4.4 or newer is required — gbrain is a Bun + TypeScript runtime; on an older Bun, run `bun upgrade` first):```bashcurl -fsSL https://bun.sh/install | bash@@@ -5074,38 -5082,31 +5087,38 @@@ This is the difference between a searc## Install-Requires **Bun 1.4.4 or newer**. Existing worker installations should follow the-[authorization and queue upgrade guide](docs/guides/authorization-upgrade.md)-before restarting services with this version.+> [!TIP]+> **Fastest: hosted GBrain at [gbrain.io](https://gbrain.io/cli?ref=readme), for any harness.** One command launches a GBrain hosted on gbrain.io; Claude Code, Codex, ChatGPT, Cursor and every other AI you use connect to it, with nothing to keep online.+>+> ```bash+> curl -sSL https://gbrainio.terminalwire.sh | bash+> gbrainio terminal connect # in a new terminal+> gbrainio workspace new # pick a plan in the browser+> claude mcp add --transport http --scope user gbrain https://gbrain.io/mcp+> codex mcp add gbrain --url https://gbrain.io/mcp+> ```+>+> The installer is a shell script for macOS and Linux; read it before you run it.++### Here's how to self-host it+- GBrain is MIT-licensed and free to self-host. It needs **Bun 1.4.0 or newer**; existing worker installs read the [authorization and queue upgrade guide](docs/guides/authorization-upgrade.md) before restarting on this version.++GBrain is MIT-licensed and free to self-host. It needs **Bun 1.4.4 or newer**; existing worker installs read the [authorization and queue upgrade guide](docs/guides/authorization-upgrade.md) before restarting on this version.> [!WARNING]> **GBrain is NOT distributed on npm.** The npm `gbrain` package is unrelated and> can shadow the real binary, so never run `npm install -g gbrain` or-> `bun add -g gbrain`. Install only via `bun install -g github:garrytan/gbrain`-> or `git clone` + `bun install && bun link`.-> Installed it by mistake? `npm uninstall -g gbrain` / `bun remove -g gbrain`, then-> reinstall; `gbrain doctor` detects it.-> Schema not migrated ([#218](https://github.com/garrytan/gbrain/issues/218))?-> Run `gbrain apply-migrations --yes --no-autopilot-install`; exit 1 means it's still-> behind: run `gbrain doctor --json`, not `--yes` (`wedged`: relay its fix).--**Claude Code or Codex, fastest path:**+> `bun add -g gbrain`. Install only via `bun install -g github:garrytan/gbrain#latest-stable`+> or `git clone` + `bun install && bun link`. Installed by mistake? `gbrain doctor` gives the fix.+> Schema not migrated ([#218](https://github.com/garrytan/gbrain/issues/218))? Run+> `gbrain apply-migrations --yes --no-autopilot-install`; if it exits 1, run `gbrain doctor --json`, not another `--yes` (`wedged`: relay its fix).```bash-bun install -g github:garrytan/gbrain-gbrain setup claude-code # or codex; --dry-run previews, --remove undoes+bun install -g github:garrytan/gbrain#latest-stable+gbrain setup claude-code # or: gbrain setup codex+gbrain init --pglite --no-embedding # any other harness, or no agent```- `gbrain setup` shows what it will write first (`--dry-run` previews, `--remove` undoes), creates a keyless brain only if none exists, wires MCP and hooks, and smoke-tests them ([setup guide](docs/guides/setup.md)). For any other coding agent, paste:-`setup` shows the brain, source, launcher and owner it resolved before writing, runs `gbrain init --pglite --no-embedding` only when no brain exists, writes the stdio MCP entry, read-context hooks (owned by hash, plus Codex hook trust) and a brain-first block in its instruction file (`--no-instructions` skips it), and smoke-tests them. Capture and providers stay off unless accepted; a hosted brain keeps `gbrain connect --install`. [Setup guide](docs/guides/setup.md).--Start with the agent you already use. For Grok Bot and Muse, the dedicated guides above install an isolated launcher, repairable runtime, and memory in a verified persistent directory. For a coding agent, paste:++`gbrain setup` shows what it will write first (`--dry-run` previews, `--remove` undoes), creates a keyless brain only if none exists, wires MCP, hooks and a brain-first block in the agent's instruction file (`--no-instructions` skips it), and smoke-tests them ([setup guide](docs/guides/setup.md)). For any other coding agent, paste:```textAdd GBrain memory to this existing agent. Read and follow:@@@ -5142,12 -5210,41 +5155,12 @@@ The repo is not a complete backup; see### Connect GBrain to your AI client (MCP)- - **Local stdio client:** `claude mcp add gbrain -- "$(command -v gbrain)" serve --surface full`; Codex, Cursor, Windsurf and other stdio clients take the same command.-For a hosted brain, start with the [native OAuth and private machine connection guide](docs/guides/hosted-harness-access.md). To open the dashboard, register clients, edit access, or invalidate tokens, use [MCP administration](docs/mcp/ADMIN.md). A **profile** controls MCP authority; a **surface** controls which granted tools are visible. Neither grants owner dashboard access. New memory profiles use the full surface. `--surface verbs` retains exactly the seven memory verbs, with orientation available through `gbrain://capabilities`. Thin CLI connections use the full surface and remain restricted by their grants.--Pick your product, then run `gbrain setup <harness> --instructions-only`: agents seldom call a brain nobody told them about.--**Upgrading a brain indexed before v0.48.3.0?** Rebuild its search chunks first: [upgrade recovery guide](skills/migrations/v0.48.3.0.md). **Say to your agent:** *"Upgrade gbrain and check whether my search index needs rebuilding."*--- **[Claude Code](docs/mcp/CLAUDE_CODE.md)** — plugin: `/plugin marketplace add garrytan/gbrain` + `/plugin install gbrain@gbrain` (MCP + skills; persona variants `gbrain-coding` / `gbrain-daily` install curated subsets; pick one). Marketplace-free skills: `gbrain skillpack scaffold --harness claude-code` copies a persona-curated skill set into your user-scope skills dir. Or by hand: `claude mcp add gbrain -- "$(command -v gbrain)" serve`. Remote with just a bearer token: `gbrain connect https://your-host/mcp --token gbrain_xxx` prints a paste-ready block (or `--install` wires it up and smoke-tests the token).-- **[Codex](docs/mcp/CODEX.md)** — plugin (recommended): `codex plugin marketplace add garrytan/gbrain@codex-plugin` + `codex plugin add gbrain@gbrain` installs the MCP server AND the curated skill set. Or connect-only: `gbrain connect https://your-host/mcp --token gbrain_xxx --agent codex` (or `--install`); the token path reads `$GBRAIN_REMOTE_TOKEN` at runtime, while the private-handoff installer writes a private managed HTTP header so the connection survives a new shell.-- **[Cursor / Windsurf / any stdio MCP client](docs/mcp/CLAUDE_CODE.md)** — same shape, add `{"command": "gbrain", "args": ["serve", "--surface", "full"]}` to your MCP config.-- **[Hermes](docs/mcp/HERMES.md)** — `printf 'Y\n' | hermes mcp add gbrain --env GBRAIN_HOME=$HOME --connect-timeout 60 --command $(which gbrain) --args serve --surface starter`. Keep `--args` last, and verify with `hermes mcp test gbrain` (the add exits 0 even on failure).-- **[Grok Bot](docs/guides/grok-bot.md)** — recommended: keep the brain on your computer, publish it with `gbrain mcp expose --funnel`, grant the Bot a `memory-writer` client and install the thin CLI at `/workspace/gbrain`; or install memory inside the Bot computer when no machine of yours stays online. Bots share local files and credentials; sources organize memory without isolating Bots. **Say to your agent:** *"connect grok bot to my brain"*.-- **[Muse personal agent](docs/guides/muse.md)** — first verify its durable user-files location; then either connect it to your published brain (`gbrain mcp expose --funnel` + thin CLI) or install the local CLI there. Native MCP configuration and skill activation are not assumed. **Say to your agent:** *"connect muse to my brain"*.-- **[Grok Build](docs/mcp/GROK.md)** — `grok mcp add gbrain -e "GBRAIN_HOME=$HOME" -- "$(command -v gbrain)" serve --surface starter`. The add is lazy (exit 0 without connecting) — verify with `grok mcp doctor gbrain`, which spawns the server. Verified against Grok Build v1.0.4.-- **[opencode](docs/mcp/OPENCODE.md)** (opencode.ai / SST — not OpenClaw) — `opencode mcp add gbrain --env GBRAIN_HOME=$HOME -- "$(command -v gbrain)" serve --surface starter`, or let `gbrain bootstrap hooks --harness opencode` write the config for you. The add is lazy — verify with `opencode mcp list`, which spawns the server (`✓ gbrain connected`). Remote: `gbrain connect https://your-host/mcp --token gbrain_xxx --agent opencode [--install]` — the config stores only the `{env:GBRAIN_REMOTE_TOKEN}` interpolation. Verified against opencode v1.18.18.-- **[OpenClaw](docs/mcp/OPENCLAW.md)** — the ClawHub bundle plugin registers gbrain automatically (`openclaw.plugin.json` ships in this repo), or register the stdio server with `openclaw mcp add gbrain --command "$(command -v gbrain)" --arg serve --env GBRAIN_HOME=$HOME` (absolute path: the launchd gateway PATH lacks `~/.bun/bin`); verify with `openclaw mcp list`.-- **[Claude Desktop (Cowork)](docs/mcp/CLAUDE_DESKTOP.md)** — Settings → Integrations → add the URL of your HTTP server. Remote only; the local `claude_desktop_config.json` does not work for remote servers.-- **[Claude Cowork (team plan)](docs/mcp/CLAUDE_COWORK.md)** — org Owner adds the connector under Organization Settings → Connectors.-- **[Perplexity Computer](docs/mcp/PERPLEXITY.md)** — choose native OAuth or a managed bearer connection according to the actual connector settings. The owner registers the matching client and delivers any confidential credentials privately.-- **[ChatGPT](docs/mcp/CHATGPT.md)** — native OAuth with PKCE. Register the exact callback and token authentication method shown in its MCP settings, then start the connection in ChatGPT and complete owner consent.--For the HTTP server itself:--```bash-gbrain serve # stdio MCP (local subprocess; for Claude Code, Cursor, Windsurf)-gbrain serve --http # HTTP MCP with OAuth 2.1 + admin dashboard at /admin- # (required for Claude Desktop, Cowork, Perplexity, ChatGPT)-gbrain mcp expose # publish serve --http on your Tailscale tailnet with HTTPS + a user service-gbrain mcp expose --funnel # same name, public HTTPS — for agents that run in a vendor's cloud-```--`gbrain mcp expose` is the recommended way to run the server from your own computer: it installs Tailscale if needed (after a consent prompt), signs in, publishes the server on `https://your-machine.your-tailnet.ts.net/mcp`, keeps the admin token in a private file, installs a launchd / systemd user service, and prints separate owner-login, native OAuth, and machine-client next steps (`--status` re-checks, `--remove` undoes only its own changes). Local coding agents on the same machine: `gbrain bootstrap harness --yes --port 3131` on a Postgres brain; on PGLite mint a token before the service runs (`gbrain auth create local-agents --scopes read,write`) and pass `--token`, or grant a scoped client through the running server (`gbrain mcp grant … --admin-token-file ~/.gbrain/serve/admin-token`). Tailnet-only by default; `--funnel` is the explicit opt-in for cloud agents. **Say to your agent:** *"use my brain over mcp"* — *"reach my brain from my phone"*. Guide: [use your brain from anywhere over MCP](docs/guides/remote-mcp.md).--The HTTP server includes optional dynamic client registration, scope-gated access (`read` / `write` / `admin` / `agent`), owner-approved OAuth authorization, and rate limiting. Dynamic registration cannot grant delegation; `admin` implies neither `agent` nor owner administration. Start with the [MCP task guide](docs/mcp/README.md) for deployment, client setup, administration, and alternatives to Tailscale (ngrok, Railway, Fly.io).++- **Local stdio client:** `claude mcp add gbrain -- "$(command -v gbrain)" serve --surface starter` (`--surface full` lists every tool); Codex, Cursor, Windsurf and other stdio clients take the same command. Then run `gbrain setup <harness> --instructions-only`: agents seldom call a brain nobody told them about.+- **Plugins with curated skills:** Codex `codex plugin marketplace add garrytan/gbrain@codex-plugin` + `codex plugin add gbrain@gbrain`; Claude Code `/plugin marketplace add garrytan/gbrain` + `/plugin install gbrain@gbrain`.+- **This brain from anywhere:** `gbrain mcp expose` publishes it on your Tailscale tailnet as a user service (`--funnel` for cloud agents such as Grok Bot, Muse and ChatGPT). [Guide](docs/guides/remote-mcp.md).+- **A brain on another host:** `gbrain connect https://your-host/mcp --token gbrain_xxx --install` (add `--agent codex` for Codex). Hosted brains use [native OAuth or a private handoff](docs/guides/hosted-harness-access.md); dashboard, clients and permissions live in [MCP administration](docs/mcp/ADMIN.md).-Running several brains behind one tool catalog? Give each one an identity with `gbrain config set mcp.instructions "<identity>"` so a connected agent can tell them apart ([details](docs/mcp/DEPLOY.md#operations)). **Say to your agent:** *"Tell connected agents which brain this is"*.+Per-client guides: [Claude Code](docs/mcp/CLAUDE_CODE.md) · [Codex](docs/mcp/CODEX.md) · [ChatGPT](docs/mcp/CHATGPT.md) · [Claude Desktop](docs/mcp/CLAUDE_DESKTOP.md) · [Claude Cowork](docs/mcp/CLAUDE_COWORK.md) · [Perplexity](docs/mcp/PERPLEXITY.md) · [Hermes](docs/mcp/HERMES.md) · [OpenClaw](docs/mcp/OPENCLAW.md) · [opencode](docs/mcp/OPENCODE.md) · [Grok Build](docs/mcp/GROK.md) · [Grok Bot](docs/guides/grok-bot.md) · [Muse](docs/guides/muse.md) · [everything MCP](docs/mcp/README.md).## Two ways to query your brain