Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Install without a postinstall script, and connect the agent on first run before reporting settings (GST-2732) (#9383)
Garry Tanccdde5edc433
diff --git a/.github/workflows/upgrade-matrix.yml b/.github/workflows/upgrade-matrix.ymlindex a820dec251..8a138ae8fa 100644--- a/.github/workflows/upgrade-matrix.yml+++ b/.github/workflows/upgrade-matrix.yml@@ -71,7 +71,6 @@ on:- 'src/commands/apply-migrations.ts'- 'src/commands/apply-migrations-schema.ts'- 'src/commands/migrations/**'- - 'scripts/postinstall.ts'- 'scripts/upgrade-matrix.ts'- 'scripts/upgrade-matrix/**'- '.github/workflows/upgrade-matrix.yml'diff --git a/AGENTS.md b/AGENTS.mdindex 1c963d49bb..9a7e2799c6 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -31,25 +31,21 @@ start here.Reason `wedged` means one migration failed three or more times in a row: relay its `fix` (ask the user)instead of reinstalling; they fix the cause, then `gbrain apply-migrations --force-retry <version>`.-Bun blocks gbrain's postinstall on `bun install -g` (`Blocked 1 postinstall`); a new install can skip it: the script only repeats the refusal every gbrain command prints on a Bun below the floor and runs `gbrain apply-migrations --yes --non-interactive`, which has nothing to migrate before a brain exists, and `gbrain setup` creates the brain and applies its setup migrations.-2. Set up keyless memory for the harness: `gbrain setup claude-code` (on Codex, `gbrain setup codex`)creates the brain if none exists, wires MCP and verifies it. Otherwise, or for any other harness, init keylessmemory: `gbrain init --pglite --no-embedding` (zero-config). For 1000+ files ormulti-machine sync, init suggests Postgres + pgvector via Supabase.-3. **STOP — ask the user about search mode.** `gbrain init` auto-applied a- default but printed a 9-cell cost matrix (mode × downstream model)- preceded by `[AGENT]` markers. You MUST relay the matrix to the operator- and confirm their choice before continuing. Cost spread between corners- is about 200x — silent acceptance is the wrong default. After- `gbrain setup <harness>` the harness is already wired when the matrix- appears in setup's one first-run settings block, so there is nothing left- to continue: relay the matrix and the other settings in the reply that- reports the install, as the settings in effect and how to change them,- and apply the user's choice when they give it. Don't end the install on a- question that needs another turn before memory works. See- [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) Step 3.5 for the- exact ask-the-user protocol. The same banner fires on `gbrain post-upgrade`+3. **Connect, then tell the user the search mode in effect.** `gbrain init`+ auto-applied a default and printed a 9-cell cost matrix (mode × downstream+ model) preceded by `[AGENT]` markers. Cost spread between corners is about+ 200x, so the user must see it, but don't stop the install to ask: on every+ harness, connect memory first (`gbrain setup <harness>` does it on Claude+ Code and Codex; elsewhere, do the `harness_wiring` step init printed), then+ relay the matrix and the other settings in the reply that reports the+ install, as the settings in effect and how to change them, and apply the+ user's choice when they give it. Nothing paid turns on without a key the+ user supplied. See [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md)+ Step 3.5 for the wording. The same banner fires on `gbrain post-upgrade`for a brain created before v0.32.3, when search modes arrived.4. Read [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) for the full step-by-stepflow (keyless memory, optional API capabilities, maintenance, verification).diff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.mdindex 0c67f36ac1..32dbce25c5 100644--- a/INSTALL_FOR_AGENTS.md+++ b/INSTALL_FOR_AGENTS.md@@ -25,7 +25,7 @@ GBrain is MIT-licensed and free to self-host; the rest of this guide installs it> **Choose the installation path first.** Inside **[Grok Bot](docs/guides/grok-bot.md)** or **[Muse](docs/guides/muse.md)**, use their dedicated guide: the recommended shape keeps the brain on the user's own computer, published with `gbrain mcp expose --funnel` ([remote MCP](docs/guides/remote-mcp.md)), and installs the thin CLI inside the agent; `scripts/setup-in-agent.sh` is the in-agent alternative, and its receipt tracks repair and native enablement. To make a brain on this computer reachable from the user's other devices, apps, or cloud agents over MCP, follow the **[remote MCP guide](docs/guides/remote-mcp.md)** (`gbrain mcp expose`; confirm the plan before installing Tailscale or a service; `--funnel` only for cloud agents). For an **[existing hosted brain](docs/guides/hosted-harness-access.md)**, choose the harness's native OAuth/PKCE flow or a private machine handoff. Owner login, client management, permissions, and revocation use the separate [MCP administration](docs/mcp/ADMIN.md) path. This guide covers a local brain for other existing agents.>-> **Memory-only path:** install → initialize → relay and confirm the Step 3.5 search-mode choice → connect the harness → verify memory (with `gbrain setup <harness>`, initialize and connect are one command and the search-mode choice is relayed in the reply that reports the install). Skip identity replacement, private-repo bootstrap, automatic capture, cron installation, and paid enrichment unless requested. A keyword-only brain needs no API key. The required search-mode choice still applies; published API cost examples are not prices for the user’s harness subscription.+> **Memory-only path:** install → initialize → connect the harness → verify memory → report the install with the Step 3.5 search mode and settings in effect (with `gbrain setup <harness>`, initialize and connect are one command). Never end the install on a question. Skip identity replacement, private-repo bootstrap, automatic capture, cron installation, and paid enrichment unless requested. A keyword-only brain needs no API key. The user still sees the search-mode matrix; published API cost examples are not prices for the user’s harness subscription.>> Only if the user asks for a **new persistent personal agent** with identity and a private repo, follow `BOOTSTRAP_FOR_AGENTS.md`.@@ -87,8 +87,6 @@ key ([Step 3](#step-3-create-the-brain)). On any other harness, `gbrain init --p> bun install && bun link> ```-Bun blocks gbrain's postinstall on `bun install -g` (`Blocked 1 postinstall`); a new install can skip it: the script only repeats the refusal every gbrain command prints on a Bun below the floor and runs `gbrain apply-migrations --yes --non-interactive`, which has nothing to migrate before a brain exists, and `gbrain setup` creates the brain and applies its setup migrations.-## Step 2: API KeysConfigured cloud providers receive text: embedding inputs, queries and candidate@@ -162,21 +160,23 @@ gbrain init --pglite --no-embedding # keyless memory, no server neededgbrain doctor --json # inspect diagnostics and any warnings```-**The first-run decision bundle.** Init asks every first-run question once, in-one bundle, and does not wait for the answers: it applies defaults and exits 0.-Human output prints it as an `[AGENT]` block; `gbrain init --json` carries it-as a notice of kind `ask` with `decisions[]`:+**The first-run settings.** Init applies its defaults and exits 0; nothing waits+for an answer. When no agent is connected yet it prints a `harness_wiring`+notice: connecting gbrain to the agent you run in is part of the install, so do+it now (Step 5), not after the user replies. It also prints the settings in+effect once, as an `[AGENT]` block (`gbrain init --json`: a notice of kind+`ask` with `decisions[]`):-| Decision | What the user picks | Default |+| Setting | What the user can change | In effect ||---|---|---|| `search_mode` | `conservative`, `balanced` or `tokenmax`, with the cost matrix (Step 3.5) | the mode init applied, with its reason |-| `writeback` | whether you save salient facts from conversations without being asked | recommended `salient`; off until the user agrees |-| `harness_wiring` | registering gbrain in the harness you run in (Step 5) | the exact registration command for the detected harness |+| `writeback` | whether you save salient facts from conversations without being asked | off; gbrain recommends `salient`, which the user opts into || `skills_scaffold` | optional bundled skills in the agent workspace | skip |+| `upkeep` | free upkeep while the agent's session is open | on |-Relay the bundle's one `user_message` to the user ("Reply 'defaults' to accept-…") and apply each answer with the command its option names. One round-trip-covers Step 3.5 and the wiring question. Details:+Connect first, then report the install and relay the bundle's `user_message`+in that reply, as the settings in effect and how to change them. Apply an+answer with the command its option names whenever the user gives one. Details:[first run](docs/protocol/AGENT_OPERATOR_v1.md#first-run).The user's markdown files and canonical skills are SEPARATE from this tool repo.@@ -278,20 +278,18 @@ The bundled skills `skills/db-repair/` (triggers on the marker) and`skills/postgres-adopt/` (detect / prefer / install / migrate-wrap) drive thisloop; full reference in `docs/ENGINES.md` ("Engine detection and access repair").-## Step 3.5: Confirm search mode with the user (DO NOT SKIP)+## Step 3.5: Tell the user which search mode is in effect (DO NOT SKIP)-This is the `search_mode` decision from the first-run bundle.+This is the `search_mode` setting from the first-run settings.`gbrain init` auto-applied a default search mode: `tokenmax` with a chat key(Anthropic, OpenAI or Google), `balanced` with a ready reranker but no chat key,and `conservative` when your subagent tier is Haiku-class or neither exists. The init output-included the cost matrix below preceded by `[AGENT]` markers. You must NOT-silently accept the default. Stop and ask the operator.--After `gbrain setup <harness>` the harness is already wired when the matrix-appears, so there is nothing to stop before: show the matrix and the applied-mode in the reply that reports the install, as a choice the user can make at-any time, and run `gbrain config set search.mode <mode>` when they pick one.-Don't hold the install open for the answer.+included the cost matrix below preceded by `[AGENT]` markers. Don't accept it+silently, and don't stop the install to ask either: on every harness, connect+gbrain first (with `gbrain setup <harness>` or the `harness_wiring` step), then+show the matrix and the applied mode in the reply that reports the install, as+a choice the user can make at any time, and run+`gbrain config set search.mode <mode>` when they pick one.If you already know the operator's choice, record it at install time instead:`gbrain init --search-mode <conservative|balanced|tokenmax>` stores it as the@@ -318,9 +316,9 @@ Estimated downstream input cost of the retrieved payload @ 10K queries/mo:**Ask the operator (paraphrase if needed):**-> Your gbrain just installed with search mode `<auto-applied default>`. This is-> a one-time setup decision that controls retrieval payload size. Which mode-> do you want?+> Your gbrain is installed and connected, with search mode+> `<auto-applied default>`. It controls retrieval payload size, and you can+> change it any time. The modes:>> 1) conservative — tight 4K budget, 10 chunks max, no reranker.> Best for Haiku subagents, cost-sensitive setups, high-volume loops.@@ -827,9 +825,8 @@ again. Pass `--no-bun-floor-check` only after checking the target yourselfwhen the floor cannot be read (offline). See[Bun floor](docs/guides/upgrades-auto-update.md#bun-floor).-The autopilot opt-out skips installation and service rewrites, including package-postinstall hooks; it does not skip other migrations. Keep the environment form-on the package-manager command because hooks run before `post-upgrade`.+The autopilot opt-out skips installation and service rewrites; it does not skip+other migrations.`GBRAIN_NO_REEMBED=1` separately skips the potentially paid reindex step.For an existing service deployment, review its migration guide instead ofassuming memory-only options are the desired maintenance policy. Verify a knowndiff --git a/behavior-changes.d/first_run_connects_then_reports_gst2732.md b/behavior-changes.d/first_run_connects_then_reports_gst2732.mdnew file mode 100644index 0000000000..7bc3136942--- /dev/null+++ b/behavior-changes.d/first_run_connects_then_reports_gst2732.md@@ -0,0 +1 @@+`gbrain init` no longer asks the user to approve connecting gbrain to their agent. The first-run bundle (`first_run_decisions`) now lists the settings in effect and how to change them, with no "Reply 'defaults'" question: search mode as applied, automatic saving (`writeback`) shown as in effect `off` with `salient` recommended (it was shown as default `salient` while off), skills and upkeep. Connecting the agent moved out of the bundle into its own `harness_wiring` notice (kind info, actor agent, no consent), because it is an install step. The install docs (AGENTS.md step 3, INSTALL_FOR_AGENTS.md Step 3.5) drop the STOP for every harness: connect first, then relay the settings and the cost matrix in the reply that reports the install. Nothing paid turns on from these settings without a key the user supplied.diff --git a/behavior-changes.d/install_no_postinstall_gst2732.md b/behavior-changes.d/install_no_postinstall_gst2732.mdnew file mode 100644index 0000000000..585843a1f0--- /dev/null+++ b/behavior-changes.d/install_no_postinstall_gst2732.md@@ -0,0 +1 @@+gbrain ships no postinstall script, so `bun install -g github:garrytan/gbrain#stable` no longer ends with Bun's "Blocked 1 postinstall" line and a clone's `bun install` no longer prints "postinstall skipped". Nothing it did is lost: every command already refuses on a Bun below the floor, `gbrain setup` applies a new brain's setup migrations, `gbrain upgrade` runs migrations in post-upgrade, and the first command on a brain applies pending schema migrations. New: when upgrade migrations are still pending (after reinstalling over an older brain with `bun install -g`), every command except apply-migrations, upgrade, post-upgrade, doctor, init, setup and serve prints a `migrations_pending` notice naming them, with `gbrain apply-migrations --yes` as the fix.diff --git a/changelog.d/capy-install-no-postinstall.md b/changelog.d/capy-install-no-postinstall.mdnew file mode 100644index 0000000000..aeff89254d--- /dev/null+++ b/changelog.d/capy-install-no-postinstall.md@@ -0,0 +1,10 @@+**A first install prints no Bun error and ends with memory connected, on every agent harness.**++### Changed+- gbrain no longer ships a postinstall script, so `bun install -g github:garrytan/gbrain#stable` no longer ends with "Blocked 1 postinstall", and a clone's `bun install` no longer prints "postinstall skipped". The script did nothing on a fresh install; migrations already run in `gbrain setup`, `gbrain upgrade` and on the first command.+- After reinstalling over an older brain, commands print a `migrations_pending` notice naming the upgrade migrations still to run, with `gbrain apply-migrations --yes` as the fix.+- `gbrain init` treats connecting the agent as an install step (its own `harness_wiring` notice), not a setting awaiting approval. The first-run settings are reported as in effect, with how to change them, and no "Reply 'defaults'" question; automatic saving shows as off (recommended salient) instead of "default: salient".+- The install docs no longer tell agents to stop and ask about search mode: connect first, then report the settings and the cost matrix in the install reply.++<!-- behavior-change: install_no_postinstall_gst2732 -->+<!-- behavior-change: first_run_connects_then_reports_gst2732 -->diff --git a/docs/INSTALL.md b/docs/INSTALL.mdindex 7263622c7c..95ae8a4d79 100644--- a/docs/INSTALL.md+++ b/docs/INSTALL.md@@ -56,7 +56,7 @@ skips interactive prompts, not all side effects.GBRAIN_NO_AUTOPILOT_INSTALL=1 GBRAIN_NO_REEMBED=1 gbrain upgrade --no-autopilot-install```-The autopilot opt-out reaches package postinstall hooks and migration+The autopilot opt-out reaches the migrationorchestrators, and skips existing service-unit rewrites. Other migrations stillrun. `GBRAIN_NO_REEMBED=1` independently skips potentially paid reindexing.The same command upgrades a clone linked with Bun: it fetches, checks the new@@ -77,7 +77,7 @@ bun install -g github:garrytan/gbrain#stablegbrain init --pglite --no-embedding```-> **If `bun install -g` hits a postinstall error** (Bun blocks postinstall hooks in some environments), the CLI prints a recovery hint pointing at [#218](https://github.com/garrytan/gbrain/issues/218). Run `gbrain doctor` to diagnose, then `gbrain apply-migrations --yes --no-autopilot-install` manually. The deterministic fallback is `git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain && GBRAIN_NO_AUTOPILOT_INSTALL=1 bun install && bun link`.+> **Reinstalled over an existing brain?** The install runs no scripts. The first gbrain command applies schema migrations, and when upgrade migrations are still pending it says so with the command that runs them ([#218](https://github.com/garrytan/gbrain/issues/218)): `gbrain apply-migrations --yes --no-autopilot-install`. Run `gbrain doctor` if that exits 1. The deterministic fallback is `git clone https://github.com/garrytan/gbrain.git ~/gbrain && cd ~/gbrain && GBRAIN_NO_AUTOPILOT_INSTALL=1 bun install && bun link`.The init flow detects your repo size and suggests Supabase for brains > 1000 markdown files. Agent-harness installs that want Postgres first can run the ladder instead:diff --git a/docs/architecture/key-files/commands-6.md b/docs/architecture/key-files/commands-6.mdindex 0a8968cb16..a5326d4b09 100644--- a/docs/architecture/key-files/commands-6.md+++ b/docs/architecture/key-files/commands-6.md@@ -12,7 +12,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/commands/transcripts.ts` — the transcripts command family, all local-only (`ctx.remote=false` by construction). `recent`: raw `.txt` corpus reads via `listRecentTranscripts` (same library as the gated `get_recent_transcripts` op). `ingest <path-or-glob>`: the cross-harness session importer — resolves ONE source id (6-tier chain), threads activePack once, streams progress (phase `transcripts.ingest`), and calls `runTranscriptsIngest` with the CLI's `makeContext` context, so on a writer-claimed brain each rendered part is submitted as a `put_page` write request naming the page's current revision (a part whose publication would change nothing is screened request-free first and takes no admission; unmanaged brains and dry runs keep the direct importer; `recover codex --apply` passes the same context; pinned by `test/transcripts-managed-ingest.test.ts`); embedding is OFF by default (embed backfill is the catch-up lane; the embed flag opts in); the max-bytes flag (validated size string, e.g. `4gb`) overrides the per-format file/store byte caps for oversized stores while omission preserves each adapter's native default; the since-last watermark is an op-checkpoint (op `transcripts-ingest`, fingerprint = source + pathspec + format + adapter version + any explicit byte cap via `ingestCheckpointFingerprintInput` — a checkpoint written under one cap is never silently reused under another, so a capped run's skipped tail can't read as scanned; the pathspec binds the user-stated paths resolved + sorted, and the no-arg/all lane substitutes hostname + sorted harness roots so DB-backed checkpoints shared across a brain's machines never let one machine inherit another's watermark and skip sessions it never scanned) advanced ONLY after a clean, untruncated, non-dry scan (a Codex sub-agent rollout, `session_meta` payload.source.subagent, has no user turn by design: the adapter reports `subagentRollout`, the scan counts it in `subagentRollouts` and prints `N sub-agent rollouts (no user turns by design)`, and it keeps the scan clean; an ordinary assistant-only rollout is still `userTurnsMissing` drift); no-arg = confined discovery table, the all flag imports the discovered set. `status`: found-vs-imported gap table (disk scan vs ONE conversation-pages frontmatter query — `executeRaw`, both engines — in `src/core/transcripts/discover.ts`) — the correctness surface that catches late-arriving sessions no watermark can. The facts flag hands EVERY touched slug (including hash-skipped) to `src/core/transcripts/ingest-facts.ts`; a page that fails extraction counts in `facts.pagesFailed`, stays unfinished, and makes the command exit 1; a pass that stopped at its budget reports `facts.budgetExhausted` and `facts.budgetReason`, and pages skipped as too large or held by another run count in `facts.pagesSkippedTooLarge` and `facts.pagesLockSkipped` (#8722). Registered in CLI_ONLY + CLI_ONLY_SELF_HELP + SELF_HELP_WITHOUT_ENGINE (engine-free help). `expandTilde(raw)` (bare `~`, leading `~/` or `~\\` → home dir; `~user` forms and a mid-string `~` stay literal) is the one tilde expansion `expandPaths` applies to every path spec. `recover codex` (`src/commands/transcripts-recover.ts`, logic `src/core/transcripts/recover.ts`; D15 for #5163): finds codex conversation pages in one source with no `**User**` anchor, re-parses the retained rollouts (discovery root + archived store, or given paths) and classifies each session recoverable / still userless / unrecoverable (rollout gone); preview by default, `--apply` re-imports only the recoverable rollouts through `runTranscriptsIngest` (content-hash dedup, no facts, no watermark write). Pinned by `test/transcripts-recover-codex.test.ts`. `audit-secrets [--source-id S] [--json]` (`src/commands/transcripts-audit.ts`, logic `src/core/transcripts/secret-audit.ts`): the read-only installed-base audit that streams imported conversation pages (`type = 'conversation'` with `transcript_import` frontmatter) in id-keyset batches of 25, scans title and body with the transcript-lane detectors, lists slug, source, hit counts per pattern and up to 20 line numbers (never values or previews), and caches the summary without slugs in config row `transcripts.secret_audit` for the doctor check `transcript_secret_exposure` (`src/commands/doctor/checks/transcript-secrets.ts`, brain category), which counts imported conversation pages and reads that summary (never scans): no audit, an older `TRANSCRIPT_SECRET_AUDIT_VERSION` or a source-scoped audit warns with the audit as fix; hits warn with the audit's age; a clean full audit is ok. Pinned by `test/transcripts-secret-audit.test.ts`.-- `src/commands/upgrade.ts` — self-update CLI. It sets `GBRAIN_UPGRADE_OWNS_MIGRATIONS=1` for the install step, so package postinstall (`scripts/postinstall.ts`) skips `apply-migrations`; post-upgrade owns them. An install step that fails or times out after `gbrain --version` already reports a newer version counts as installed. The run ends with a `Binary:` line (installed version, or upgrade failed) and a `Migrations:` line: complete; running, with the lock holder's host and pid when post-upgrade exits 75; or failed, with the recovery command (`--force-retry <v>` for wedged versions). `runPostUpgrade()` enumerates migrations from the TS registry (`src/commands/migrations/index.ts`) and tail-calls `runApplyMigrations(['--yes', '--non-interactive'])` so the mechanical side of every outstanding migration runs unconditionally. After schema apply it prints the one-shot auto_chronicle default-on `[AGENT]` notice (`core/chronicle/upgrade-notice.ts`). Install methods are bun, bun-link and binary (a compiled binary is found by Bun's `/$bunfs/` entrypoint, so a release asset keeps its published name); anything else is `unknown` and prints manual steps. It never runs `clawhub update gbrain`, which would install whatever skill anyone publishes under that name (#8464; `test/upgrade.serial.test.ts`). Before the swap of a bun-link or package install it refuses (exit 78, nothing changed) a target whose Bun floor is above the host's Bun or unreadable (`--no-bun-floor-check` overrides, manual only; `src/core/bun-floor.ts`); after the swap it runs `gbrain --help` as a smoke that passes the startup Bun check and, on failure, exits 1 with per-method recovery (#5855). Everything the post-swap tail needs is imported statically, so the old process never loads new-release modules into its cached graph (#6604; the supervisor step constant lives in the import-free leaf `src/commands/movement-step.ts`; guard: `test/upgrade-post-swap-imports.test.ts`). A tag-pinned reinstall hint (`bunReinstallCommand`, `reinstallHintLines`) probes `git ls-remote --exit-code --tags … refs/tags/v<x>` before `bun remove -g gbrain`, prints a restore line, and on Windows prints one step per line; `planPinnedReinstall` probes the tag itself (published / not published / unknown) and falls back to the newest published `v<x>` tag (`latestPublishedVersion`) when the requested one is missing (#6662, D24; `test/upgrade-release-tag-hint.test.ts`). A verified version equal to the running one after the install step is no swap (#6828): it prints `No newer version was installed`, skips `last_upgrade`, `JUST_UPGRADED`, the cache reset and the smoke, and on a tag pin with no newer published tag the hint moves the install off the pin with `to_version: latest`, never a cached unpublished version (#6718). With `GBRAIN_SWAP_RECEIPT` set it writes a `SwapReceipt` (`installed` / `not_installed` / `installed_broken`) for the autopilot channel (`test/autopilot-unpublished-target-6828.test.ts`). Tests: `upgrade-migration-outcome.test.ts`, `upgrade-no-autopilot.serial.test.ts`, `upgrade-bun-link-arc.serial.test.ts`. `post-upgrade --json` (D2, `json: 'document'`): human lines go to stderr and stdout is one report `{status, apply_migrations:{exit_code}, schema, warnings[]}`; it calls `applyMigrations()` and still ends on any status apply-migrations returns (a failure is one envelope leading with the report). GBRA-175: `--channel stable|alpha` (`latest` is an alias of `alpha`; resolution order in the Release channels entry below): `resolveStableRelease` maps the commit `refs/tags/stable` peels to onto its `v<version>` tag through `git ls-remote`, and `installStableRelease` installs exactly that release (bun: remove then add `#v<version>`, restoring the previous release on failure; bun-link: fast-forward only; binary: `fetchReleaseByTag`), never downgrading. Before the swap `preflightHostRestart` refuses (`restart_refused`, exit 3) when a running process could not be restarted; after post-upgrade the new build runs `gbrain upgrade --restart-only` (`--no-restart` skips it). Tests: `upgrade-stable-channel.test.ts`. A global install pinned to a tag or commit (`bunGlobalExactTagPin(root, true)`) is replaced with the newest published release the same way instead of `bun update`, which keeps the pin. `parseChannelArg` and `resolveStableRelease` live in `src/core/stable-channel.ts` (re-exported).+- `src/commands/upgrade.ts` — self-update CLI. The package has no postinstall, so the install step runs no migrations; post-upgrade owns them (`GBRAIN_UPGRADE_OWNS_MIGRATIONS=1` is still set for the install step). An install step that fails or times out after `gbrain --version` already reports a newer version counts as installed. The run ends with a `Binary:` line (installed version, or upgrade failed) and a `Migrations:` line: complete; running, with the lock holder's host and pid when post-upgrade exits 75; or failed, with the recovery command (`--force-retry <v>` for wedged versions). `runPostUpgrade()` enumerates migrations from the TS registry (`src/commands/migrations/index.ts`) and tail-calls `runApplyMigrations(['--yes', '--non-interactive'])` so the mechanical side of every outstanding migration runs unconditionally. After schema apply it prints the one-shot auto_chronicle default-on `[AGENT]` notice (`core/chronicle/upgrade-notice.ts`). Install methods are bun, bun-link and binary (a compiled binary is found by Bun's `/$bunfs/` entrypoint, so a release asset keeps its published name); anything else is `unknown` and prints manual steps. It never runs `clawhub update gbrain`, which would install whatever skill anyone publishes under that name (#8464; `test/upgrade.serial.test.ts`). Before the swap of a bun-link or package install it refuses (exit 78, nothing changed) a target whose Bun floor is above the host's Bun or unreadable (`--no-bun-floor-check` overrides, manual only; `src/core/bun-floor.ts`); after the swap it runs `gbrain --help` as a smoke that passes the startup Bun check and, on failure, exits 1 with per-method recovery (#5855). Everything the post-swap tail needs is imported statically, so the old process never loads new-release modules into its cached graph (#6604; the supervisor step constant lives in the import-free leaf `src/commands/movement-step.ts`; guard: `test/upgrade-post-swap-imports.test.ts`). A tag-pinned reinstall hint (`bunReinstallCommand`, `reinstallHintLines`) probes `git ls-remote --exit-code --tags … refs/tags/v<x>` before `bun remove -g gbrain`, prints a restore line, and on Windows prints one step per line; `planPinnedReinstall` probes the tag itself (published / not published / unknown) and falls back to the newest published `v<x>` tag (`latestPublishedVersion`) when the requested one is missing (#6662, D24; `test/upgrade-release-tag-hint.test.ts`). A verified version equal to the running one after the install step is no swap (#6828): it prints `No newer version was installed`, skips `last_upgrade`, `JUST_UPGRADED`, the cache reset and the smoke, and on a tag pin with no newer published tag the hint moves the install off the pin with `to_version: latest`, never a cached unpublished version (#6718). With `GBRAIN_SWAP_RECEIPT` set it writes a `SwapReceipt` (`installed` / `not_installed` / `installed_broken`) for the autopilot channel (`test/autopilot-unpublished-target-6828.test.ts`). Tests: `upgrade-migration-outcome.test.ts`, `upgrade-no-autopilot.serial.test.ts`, `upgrade-bun-link-arc.serial.test.ts`. `post-upgrade --json` (D2, `json: 'document'`): human lines go to stderr and stdout is one report `{status, apply_migrations:{exit_code}, schema, warnings[]}`; it calls `applyMigrations()` and still ends on any status apply-migrations returns (a failure is one envelope leading with the report). GBRA-175: `--channel stable|alpha` (`latest` is an alias of `alpha`; resolution order in the Release channels entry below): `resolveStableRelease` maps the commit `refs/tags/stable` peels to onto its `v<version>` tag through `git ls-remote`, and `installStableRelease` installs exactly that release (bun: remove then add `#v<version>`, restoring the previous release on failure; bun-link: fast-forward only; binary: `fetchReleaseByTag`), never downgrading. Before the swap `preflightHostRestart` refuses (`restart_refused`, exit 3) when a running process could not be restarted; after post-upgrade the new build runs `gbrain upgrade --restart-only` (`--no-restart` skips it). Tests: `upgrade-stable-channel.test.ts`. A global install pinned to a tag or commit (`bunGlobalExactTagPin(root, true)`) is replaced with the newest published release the same way instead of `bun update`, which keeps the pin. `parseChannelArg` and `resolveStableRelease` live in `src/core/stable-channel.ts` (re-exported).- Release channels: `src/core/self-upgrade.ts` resolves the channel (`resolveReleaseChannel`: `--channel`, `GBRAIN_RELEASE_CHANNEL`, `self_upgrade.channel`, default `stable`; `latest` normalizes to `alpha`; an invalid value at the first present source is an error) and keeps the update cache (`update-check.<channel>.json`, tagged with the evidence policy; an older answer never overwrites a newer one) and the time-based snooze (`update-snoozed.<channel>.json`) per channel; `offeredVersion` never offers a downgrade except to move off a `known_bad` version. `src/core/stable-channel.ts` reads and strictly parses the evidence record (`stable.json` on `stable-record`; `requiredEvidenceKeys`: `soak_run`, plus `matrix_run` from `MATRIX_REQUIRED_FROM`), maps failures to `stable_missing` / `stable_invalid` / `stable_unreadable` with sanitized causes, and `resolveStableRelease` checks the `stable` and `v<version>` tags against the record commit. `src/commands/upgrade-channel.ts` plans an upgrade's target (`channelTarget`, `runUpgradeDryRun` for `gbrain upgrade --dry-run --json`) and refuses with the typed code. `src/commands/check-update.ts` `refreshUpdateCache` never reads a bare VERSION for stable and never falls back to alpha. `src/core/release-channel-notice.ts` prints the one-time `[gbrain notice release_channel]` line on stderr (marker file under `notices/`; not under `--json`, `serve` or `mcp`; only when no channel is set). `src/core/install-ref.ts` is the one ref every install surface names, linted by `scripts/check-install-ref.ts`. Tests: `test/release-channel-w1.serial.test.ts`, `test/upgrade-stable-channel.test.ts`, `test/install-ref.test.ts`. Docs: `docs/guides/upgrades-auto-update.md#stable-channel`.- `src/commands/upgrade-restart.ts` — GBRA-175: the host side of the upgrade restart. Real process sources (consumer heartbeat rows on Postgres, the supervisor PID file, the worker registry, `ps -U <uid> -ww -o pid=,ppid=,etime=,command=` with `/proc/<pid>/environ` GBRAIN_HOME matching on Linux; the install version above each entry point), the installed serve and autopilot services with the pid each manager runs (`hostServices`: `systemctl --user show -p MainPID`, `launchctl list`), `terminateIfUnchanged` (SIGTERM an MCP pid only while `ps` still shows the same server and start time), `restartRefusal` (ask_user + `--stop-mcp` when only MCP servers block, else the first manual step for the user), `preflightHostRestart` (pre-swap, every process stale) and `runHostRestart` (`gbrain upgrade --restart-only [--stop-mcp] [--dry-run] [--json]`: plan, run, verify for up to 180 s (360 s after an autopilot hand-off) with the warm-socket probe `probeCliSocket`). #7475: `restartServeAfterSelfUpgrade`, called each autopilot-daemon tick, restarts the serve the serve service runs once it is on an older build than the relaunched autopilot. It runs once per installed build (#8013: `serve-restart-attempt.json` survives autopilot relaunches), skips a serve service whose wrapper belongs to another brain (`serveServiceRunsWrapper`), runs the restart without blocking the daemon (`hostExecutor` spawns asynchronously, 120 s cap), only in auto mode, in quiet hours and when the brain is idle (`computeAutopilotIdle`), and audits as `restart_serve`. #8776: `autopilotLauncher` (this brain's gbrain cron line from `crontab -l`, else `self_upgrade.autopilot_launcher external`) feeds the planner's hand-off; `upgradeRestartReadiness` is the preflight plan from the process table alone, which doctor's `self_upgrade_health` reads (local doctor only). `planServeRestart` reports a serve the service does not run, or one on another install, as `manual` and never restarts it. A serve counts as older only on evidence (a recorded build below this one, or no recorded build and a start before the install's `package.json` was written); a newer or unknown serve, or an install on disk that is not this build, is left alone. Tests: `upgrade-restart.test.ts`, `autopilot-serve-restart-7475.test.ts`, `autopilot-serve-restart-8013.test.ts`.- `src/core/upgrade-restart.ts` — GBRA-175: the pure half of the upgrade restart. `collectHostProcesses` (the process table is the authority: a heartbeat, PID-file or registry record whose pid `ps` does not show as gbrain is dropped; `gbrainEntry` skips wrappers such as tini, `bunx`, `bun x` and `bun run <bin>`, skips interpreter flags that take a value, resolves a relative entry against the process's `/proc/<pid>/cwd` and accepts a `src/cli.ts` whose package two levels up is named gbrain (#8723); a process's parent is its nearest gbrain ancestor, and a worker with none is refused naming its parent's pid and executable, never its command line), `planRestart` (a service restarts only processes under its manager's pid; `supervisorRestartArgv` keeps the launch options and PID file, read from `--pid-file <path>`, and drops a `--flag=value` token that is neither a global flag nor `--job-isolation=`, because the supervisor that holds it ignored it and this build's `=` gate refuses it (#7619); an autopilot under no installed service gets a `handoff` step when `ctx.autopilotLauncher` is known (#8776: SIGTERM while the pid is unchanged, then the launcher must bring autopilot back), else a manual step naming `gbrain autopilot --install`; anything else is a `ManualStep`), `runRestartSteps`, `restartProblems` (old pids gone, one build, roles and the supervised worker back, warm socket accepts) and `unverifiedBuilds`. A stale process whose `install_root` is another install than the one being upgraded gets a `replace_copy` step first when it is a Bun global copy (`bunGlobalCopyOf`: probe the tag, `bun remove -g` then `bun add -g` under its `BUN_INSTALL`, restore on failure), else a manual step from `copyFix`; after the restart `mismatchedBuilds` names any process back on another build, and the host's `mismatchFix` chains that replacement with `gbrain upgrade --restart-only`.diff --git a/docs/architecture/key-files/core-utilities-2.md b/docs/architecture/key-files/core-utilities-2.mdindex 78dd2faa06..3da004c9b5 100644--- a/docs/architecture/key-files/core-utilities-2.md+++ b/docs/architecture/key-files/core-utilities-2.md@@ -26,7 +26,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/core/restore-target.ts` -- `resolveRestoreTarget(engine, source, repo)`: the source and repo `gbrain export --restore-only` restores, shared with `gbrain storage status` so its printed restore command restores exactly the files it lists. An explicit source (already resolved) wins; a repo without a source selects the one active source registered at that exact path, refuses a repo registered only to an archived source, else selects the only active source; neither selects the flagless resolver chain's source and its `local_path` (the legacy `sync.repo_path` answers for `default` only). `restoreFilePath(repo, slug, sourcePath, sourcePathBytes, slugRootMode)` is the file whose absence makes the restore write a page: the recorded `source_path` resolved in the repo in the source's slug-root mode (`scannerSlugRootMode`), else `<slug>.md`; an over-long or unsafe recorded path throws. Refusals throw `RestoreTargetError`; resolver and database errors propagate unchanged.-- `src/core/runtime-version.ts` — Bun 1.4.4 minimum (`MINIMUM_BUN_VERSION`; 1.4.0-1.4.2 leak every chunk a postgres.js TLS connection reads, #7644 #7596). `unsupportedBunMessage` names the found and required versions and the fix (`bun upgrade`, restart, `gbrain post-upgrade` for an interrupted upgrade). `exitOnUnsupportedBun` is the CLI entrypoint gate: every command below the floor exits 1 before dispatch (`--version` still prints, exit 0, so an older gbrain's upgrade can verify the swap; `autopilot` also writes the refusal to stdout, its service log); `scripts/postinstall.ts` prints it when an install lands on an older Bun; the guarded HTTP transport asserts it; doctor reports it as `bun_runtime`. Package engines, runtime checks and the CI Bun matrices share the same floor (`test/scripts/ci-pr-scope.test.ts`). `compareBunVersions`/`bunVersionMeets` order Bun versions by semver (a `-canary` prerelease sits below its release; `+revision` metadata is ignored), shared with the upgrade floor gate. `SECURE_BUN_VERSION` (1.4.4) is the first Bun with the Brotli fix for CVE-2026-111497 (#7373): the floor is not below it, so a runtime without the fix is refused; doctor's `bun_runtime` warns (`gbrain upgrade` for a standalone binary, `bun upgrade` for a bun install) only for a supported runtime below it, and the CI primary pin may not drop below it (`test/scripts/ci-pr-scope.test.ts`).+- `src/core/runtime-version.ts` — Bun 1.4.4 minimum (`MINIMUM_BUN_VERSION`; 1.4.0-1.4.2 leak every chunk a postgres.js TLS connection reads, #7644 #7596). `unsupportedBunMessage` names the found and required versions and the fix (`bun upgrade`, restart, `gbrain post-upgrade` for an interrupted upgrade). `exitOnUnsupportedBun` is the CLI entrypoint gate: every command below the floor exits 1 before dispatch (`--version` still prints, exit 0, so an older gbrain's upgrade can verify the swap; `autopilot` also writes the refusal to stdout, its service log); the guarded HTTP transport asserts it; doctor reports it as `bun_runtime`. Package engines, runtime checks and the CI Bun matrices share the same floor (`test/scripts/ci-pr-scope.test.ts`). `compareBunVersions`/`bunVersionMeets` order Bun versions by semver (a `-canary` prerelease sits below its release; `+revision` metadata is ignored), shared with the upgrade floor gate. `SECURE_BUN_VERSION` (1.4.4) is the first Bun with the Brotli fix for CVE-2026-111497 (#7373): the floor is not below it, so a runtime without the fix is refused; doctor's `bun_runtime` warns (`gbrain upgrade` for a standalone binary, `bun upgrade` for a bun install) only for a supported runtime below it, and the CI primary pin may not drop below it (`test/scripts/ci-pr-scope.test.ts`).- `src/core/self-upgrade-swap.ts` — autopilot swap settlement (#6828): `prepareSwapReceipt`/`settleAutopilotSwap` read the receipt `gbrain upgrade --swap-only` writes (`GBRAIN_SWAP_RECEIPT`; one from another run is ignored, none falls back to `gbrain --version`). Unchanged version, or exit 0 with nothing newer confirmed: hold, no known-bad, `self_upgrade.last_check_ts` (24 h retry). Failure: known-bad names the installed version; when that is not the checked one, also throttle and drop the update cache. Floor refusal (78): hold. Real swap: breadcrumb on the installed version. Tests: `autopilot-unpublished-target-6828.test.ts`, `autopilot-bun-floor.test.ts`.- `src/core/self-upgrade-recovery.ts` — #6828 known-bad recovery: `neverInstalledFailedVersions` (pure) lists `self_upgrade.failed_versions` entries proven never installed: the no-op swap's own `last_upgrade` (`from` == `to` == running) is timestamped inside that entry's swap window, the entry has one failure (`crash-on-launch` after `swapped`, same running version), and no audit row ran it. Audit rows alone are not proof. `findNeverInstalledFailures` reads config, every audit file (`readAllSelfUpgrades`) and `last_upgrade`; used by `gbrain self-upgrade --clear-never-installed [--apply]` and the `self_upgrade_health` fix. Tests: `self-upgrade-never-installed-6828.test.ts`.diff --git a/docs/ci-upgrade-matrix.md b/docs/ci-upgrade-matrix.mdindex da4c674bd2..a91dcf37e2 100644--- a/docs/ci-upgrade-matrix.md+++ b/docs/ci-upgrade-matrix.md@@ -183,7 +183,7 @@ Against the upgrade-breakage classes in the GBRA-224 plan:| I: packaged skill and host migrations | Yes: `apply-migrations` runs every orchestrator on a brain the old release created || J: embedding backfill holds created by an upgrade | Yes on keyed cells: embedding a new page and vector query after the upgrade || C: mixed versions, stale resident processes | Partly: a stdio serve and (Postgres) a supervisor across the upgrade, one build afterwards, and the old binary on the upgraded brain; not long-lived multi-host fleets |-| E: runtime floor, postinstall, Bun | Partly: the real Bun-floor read and global install on the runner's Bun; not older Bun versions |+| E: runtime floor, Bun | Partly: the real Bun-floor read and global install on the runner's Bun; not older Bun versions || G: migration orchestrator chain on managed brains | Partly: the chain on fresh small brains; not managed multi-writer brains |Not covered: scale (classes B and F stay with the production soak and thediff --git a/docs/guides/authorization-upgrade.md b/docs/guides/authorization-upgrade.mdindex 9c90025b4a..3d509c7001 100644--- a/docs/guides/authorization-upgrade.md+++ b/docs/guides/authorization-upgrade.md@@ -113,8 +113,7 @@ no tools; only an absent trusted-local binding uses the default registry.For a linked source checkout, update that checkout to the chosen releasethrough its normal Git workflow, then run `bun install --ignore-scripts`.- Do not use `gbrain upgrade --swap-only` for this source/package cutover: its- underlying Bun installation can still run postinstall. Plain `gbrain upgrade`,+ Do not use `gbrain upgrade --swap-only` for this source/package cutover. Plain `gbrain upgrade`,`gbrain post-upgrade`, and `gbrain apply-migrations --yes` can run pendingsetup phases that start autopilot or perform other maintenance.diff --git a/docs/guides/minions-fix.md b/docs/guides/minions-fix.mdindex 2c35d9e200..1086090cf0 100644--- a/docs/guides/minions-fix.md+++ b/docs/guides/minions-fix.md@@ -427,8 +427,8 @@ It's idempotent. On an install that already migrated it's a cheap no-op.## ContextThe Minions schema, queue, worker, and migration skill ship together, and-the migration fires automatically on `gbrain upgrade` and via the-`postinstall` hook. An install is half-migrated when the schema is present+the migration fires automatically on `gbrain upgrade` (and on+`gbrain apply-migrations --yes`). An install is half-migrated when the schema is presentbut the migration never completed: no `~/.gbrain/preferences.json`,autopilot still runs inline, cron jobs still call `agentTurn`. This guidecovers detecting that state and finishing the migration.diff --git a/docs/guides/shared-brain-skills.md b/docs/guides/shared-brain-skills.mdindex 482e60df7a..137bb7cf15 100644--- a/docs/guides/shared-brain-skills.md+++ b/docs/guides/shared-brain-skills.md@@ -418,8 +418,8 @@ gbrain config set shared_skills.migration.enabled false```The key is brain-level database config, so it applies to every machine that-uses that database. From then on `gbrain apply-migrations` (including the-`bun install` postinstall, `gbrain upgrade` and `gbrain post-upgrade`) skips+uses that database. From then on `gbrain apply-migrations` (including+`gbrain upgrade` and `gbrain post-upgrade`) skipsv0.53.0 entirely: no inventory, no `shared_skills.migration.v1*` configwrites, and the applied-migration re-check does not run. `gbrainapply-migrations --list` and `--dry-run` show it as `declined` with the key,diff --git a/docs/protocol/AGENT_OPERATOR_v1.md b/docs/protocol/AGENT_OPERATOR_v1.mdindex 714a6b798c..c99abda3ab 100644--- a/docs/protocol/AGENT_OPERATOR_v1.md+++ b/docs/protocol/AGENT_OPERATOR_v1.md@@ -267,11 +267,28 @@ stdout (`--json`):"root_identity": "(device and inode of the content root)"},"notices": [+ {+ "code": "harness_wiring",+ "kind": "info",+ "why": "gbrain is not connected to an agent here, and this step is not a command the agent runs by itself; say so in the reply that reports the install, without waiting on it. Which agent app should get gbrain memory? The install guide has a one-line command for each. For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "fix": {+ "consent": [+ "persistent_install"+ ],+ "actor": "user",+ "next": "report",+ "why": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "user_message": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",+ "docs": "https://github.com/garrytan/gbrain/blob/master/docs/protocol/MEMORY_VERBS_v1.md#install-the-4-command-quickstart",+ "requires_exclusive": false+ },+ "contract_version": 1+ },{"code": "first_run_decisions","kind": "ask",- "why": "The brain is ready. These settings were applied with defaults or need the user's choice; none blocks using the brain.",- "user_message": "gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: conservative; writeback: salient; harness_wiring: skip; upkeep: on), or tell me what to change.",+ "why": "The brain is ready and these first-run settings are in effect as listed; none blocks memory. Relay them once, in the reply that reports the install, as the current settings and how to change them; do not hold the install open or end it waiting on an answer. When the user picks an option, run its command. Nothing paid turns on from these settings without a key the user supplied.",+ "user_message": "gbrain is installed. In effect: search mode conservative; agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). Upkeep: free upkeep runs on its own while your agent's gbrain session is open. Nothing is deleted or paid for without you. Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule. Estimated downstream input cost of the retrieved payload at 10K queries/month (Haiku 5.5 / Sonnet 5.5 / Opus 5.5): conservative $4 / $80 / $160, balanced $10 / $200 / $400, tokenmax $20 / $400 / $800 per month. Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.","decisions": [{"id": "search_mode",@@ -352,24 +369,8 @@ stdout (`--json`):]}],- "default": "salient",- "default_reason": "Recommended for a personal brain: the brain learns what the user tells their agents. It is opt-in, so it applies only when the user accepts the defaults or picks it."- },- {- "id": "harness_wiring",- "question": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",- "options": [- {- "id": "wire",- "label": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw)."- },- {- "id": "skip",- "label": "Do not register gbrain with an agent harness now."- }- ],- "default": "skip",- "default_reason": "No agent harness was detected."+ "default": "off",+ "default_reason": "In effect now: agents save only what the user asks them to remember. salient is recommended for a personal brain; it is opt-in, so it turns on only when the user picks it."},{"id": "upkeep",@@ -402,7 +403,7 @@ stdout (`--json`):}```-stdout is one document; the brain is ready and nothing blocks using it. The `first_run_decisions` notice is `kind: ask`, so the agent relays its `user_message` ("gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: conservative; writeback: salient; harness_wiring: skip; upkeep: on), or tell me what to change.") once and stops. The decisions are `search_mode` (default `conservative`), `writeback` (default `salient`), `harness_wiring` (default `skip`), `upkeep` (default `on`); each option carries the exact argv to apply it, so a reply of "defaults" needs no command at all.+stdout is one document; the brain is ready and nothing blocks using it. The agent first does the `harness_wiring` step: connecting gbrain to itself is part of the install, not a setting. It then reports the install and relays the `first_run_decisions` `user_message` ("gbrain is installed. In effect: search mode conservative; agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). Upkeep: free upkeep runs on its own while your agent's gbrain session is open. Nothing is deleted or paid for without you. Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule. Estimated downstream input cost of the retrieved payload at 10K queries/month (Haiku 5.5 / Sonnet 5.5 / Opus 5.5): conservative $4 / $80 / $160, balanced $10 / $200 / $400, tokenmax $20 / $400 / $800 per month. Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.") once in that reply, without waiting for an answer. The settings in effect are `search_mode` (default `conservative`), `writeback` (default `off`), `upkeep` (default `on`); each option carries the exact argv to apply it when the user picks one.### 5. A caller mistake over stdio MCP, recorded: `run` (journey)@@ -1272,19 +1273,23 @@ stays up on its port in status-only mode instead of exiting:## First run-`gbrain init` emits one decision bundle instead of scattered prompts: an-`[AGENT]` block in human output, and a notice of kind `ask` in `init --json`.-Init does not wait for the answers; it exits 0 with defaults applied.+`gbrain init` applies its defaults and exits 0. It emits a `harness_wiring`+notice when no agent is connected yet, and one bundle of the settings in+effect: an `[AGENT]` block in human output, and a notice of kind `ask` in+`init --json`. Nothing in the bundle waits for an answer.-| Decision | Options | Default |+| Setting | Options | In effect ||---|---|---|| `search_mode` | `conservative`, `balanced`, `tokenmax`, with the cost matrix | applied at init, with the reason |-| `writeback` | `off`, `salient`, `all` | recommended `salient` (the user opts in) |-| `harness_wiring` | the registration command for the detected harness | the readiness `harness_wiring` fix |+| `writeback` | `off`, `salient`, `all` | `off`; gbrain recommends `salient` (the user opts in) || `skills_scaffold` | optional | skip |+| `upkeep` | `on`, `off` | `on` (free tier only without a key) |-Relay the bundle's one `user_message` ("Reply 'defaults' to accept …"); apply-each answer with the decision's `argv`. Then:+Connect first, then report the install and relay the bundle's `user_message`+in that reply: the settings in effect, the cost matrix and how to change each.+Don't end the install on a question. Apply an answer with the option's `argv`+whenever the user gives one. Nothing paid turns on from these settings without+a key the user supplied. The steps:1. Register gbrain with the harness using the `harness_wiring` fix. Theregistration always uses the absolute gbrain path and `--surface starter`,diff --git a/docs/tutorials/connect-coding-agent.md b/docs/tutorials/connect-coding-agent.mdindex 7b3688b170..b2e026ce01 100644--- a/docs/tutorials/connect-coding-agent.md+++ b/docs/tutorials/connect-coding-agent.md@@ -54,9 +54,9 @@ For the intended unconfigured local brain:gbrain init --pglite --no-embedding```-PGLite runs locally without a database server or Docker. **Relay the printed-search-mode cost matrix and confirm the user's choice before continuing**, as-required by [Step 3.5](../../INSTALL_FOR_AGENTS.md#step-35-confirm-search-mode-with-the-user-do-not-skip).+PGLite runs locally without a database server or Docker. **Tell the user the+search mode in effect and the printed cost matrix** when you report the install, as+described in [Step 3.5](../../INSTALL_FOR_AGENTS.md#step-35-tell-the-user-which-search-mode-is-in-effect-do-not-skip).The matrix illustrates model API costs, not the price of a Codex or Claudesubscription. Choosing a mode does not enable paid APIs or automatic capture.diff --git a/llms-full.txt b/llms-full.txtindex ce24b3d89c..e714ca4049 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -975,25 +975,21 @@ start here.Reason `wedged` means one migration failed three or more times in a row: relay its `fix` (ask the user)instead of reinstalling; they fix the cause, then `gbrain apply-migrations --force-retry <version>`.-Bun blocks gbrain's postinstall on `bun install -g` (`Blocked 1 postinstall`); a new install can skip it: the script only repeats the refusal every gbrain command prints on a Bun below the floor and runs `gbrain apply-migrations --yes --non-interactive`, which has nothing to migrate before a brain exists, and `gbrain setup` creates the brain and applies its setup migrations.-2. Set up keyless memory for the harness: `gbrain setup claude-code` (on Codex, `gbrain setup codex`)creates the brain if none exists, wires MCP and verifies it. Otherwise, or for any other harness, init keylessmemory: `gbrain init --pglite --no-embedding` (zero-config). For 1000+ files ormulti-machine sync, init suggests Postgres + pgvector via Supabase.-3. **STOP — ask the user about search mode.** `gbrain init` auto-applied a- default but printed a 9-cell cost matrix (mode × downstream model)- preceded by `[AGENT]` markers. You MUST relay the matrix to the operator- and confirm their choice before continuing. Cost spread between corners- is about 200x — silent acceptance is the wrong default. After- `gbrain setup <harness>` the harness is already wired when the matrix- appears in setup's one first-run settings block, so there is nothing left- to continue: relay the matrix and the other settings in the reply that- reports the install, as the settings in effect and how to change them,- and apply the user's choice when they give it. Don't end the install on a- question that needs another turn before memory works. See- [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) Step 3.5 for the- exact ask-the-user protocol. The same banner fires on `gbrain post-upgrade`+3. **Connect, then tell the user the search mode in effect.** `gbrain init`+ auto-applied a default and printed a 9-cell cost matrix (mode × downstream+ model) preceded by `[AGENT]` markers. Cost spread between corners is about+ 200x, so the user must see it, but don't stop the install to ask: on every+ harness, connect memory first (`gbrain setup <harness>` does it on Claude+ Code and Codex; elsewhere, do the `harness_wiring` step init printed), then+ relay the matrix and the other settings in the reply that reports the+ install, as the settings in effect and how to change them, and apply the+ user's choice when they give it. Nothing paid turns on without a key the+ user supplied. See [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md)+ Step 3.5 for the wording. The same banner fires on `gbrain post-upgrade`for a brain created before v0.32.3, when search modes arrived.4. Read [`./INSTALL_FOR_AGENTS.md`](./INSTALL_FOR_AGENTS.md) for the full step-by-stepflow (keyless memory, optional API capabilities, maintenance, verification).@@ -1889,7 +1885,7 @@ GBrain is MIT-licensed and free to self-host; the rest of this guide installs it> **Choose the installation path first.** Inside **[Grok Bot](docs/guides/grok-bot.md)** or **[Muse](docs/guides/muse.md)**, use their dedicated guide: the recommended shape keeps the brain on the user's own computer, published with `gbrain mcp expose --funnel` ([remote MCP](docs/guides/remote-mcp.md)), and installs the thin CLI inside the agent; `scripts/setup-in-agent.sh` is the in-agent alternative, and its receipt tracks repair and native enablement. To make a brain on this computer reachable from the user's other devices, apps, or cloud agents over MCP, follow the **[remote MCP guide](docs/guides/remote-mcp.md)** (`gbrain mcp expose`; confirm the plan before installing Tailscale or a service; `--funnel` only for cloud agents). For an **[existing hosted brain](docs/guides/hosted-harness-access.md)**, choose the harness's native OAuth/PKCE flow or a private machine handoff. Owner login, client management, permissions, and revocation use the separate [MCP administration](docs/mcp/ADMIN.md) path. This guide covers a local brain for other existing agents.>-> **Memory-only path:** install → initialize → relay and confirm the Step 3.5 search-mode choice → connect the harness → verify memory (with `gbrain setup <harness>`, initialize and connect are one command and the search-mode choice is relayed in the reply that reports the install). Skip identity replacement, private-repo bootstrap, automatic capture, cron installation, and paid enrichment unless requested. A keyword-only brain needs no API key. The required search-mode choice still applies; published API cost examples are not prices for the user’s harness subscription.+> **Memory-only path:** install → initialize → connect the harness → verify memory → report the install with the Step 3.5 search mode and settings in effect (with `gbrain setup <harness>`, initialize and connect are one command). Never end the install on a question. Skip identity replacement, private-repo bootstrap, automatic capture, cron installation, and paid enrichment unless requested. A keyword-only brain needs no API key. The user still sees the search-mode matrix; published API cost examples are not prices for the user’s harness subscription.>> Only if the user asks for a **new persistent personal agent** with identity and a private repo, follow `BOOTSTRAP_FOR_AGENTS.md`.@@ -1951,8 +1947,6 @@ key ([Step 3](#step-3-create-the-brain)). On any other harness, `gbrain init --p> bun install && bun link> ```-Bun blocks gbrain's postinstall on `bun install -g` (`Blocked 1 postinstall`); a new install can skip it: the script only repeats the refusal every gbrain command prints on a Bun below the floor and runs `gbrain apply-migrations --yes --non-interactive`, which has nothing to migrate before a brain exists, and `gbrain setup` creates the brain and applies its setup migrations.-## Step 2: API KeysConfigured cloud providers receive text: embedding inputs, queries and candidate@@ -2026,21 +2020,23 @@ gbrain init --pglite --no-embedding # keyless memory, no server neededgbrain doctor --json # inspect diagnostics and any warnings```-**The first-run decision bundle.** Init asks every first-run question once, in-one bundle, and does not wait for the answers: it applies defaults and exits 0.-Human output prints it as an `[AGENT]` block; `gbrain init --json` carries it-as a notice of kind `ask` with `decisions[]`:+**The first-run settings.** Init applies its defaults and exits 0; nothing waits+for an answer. When no agent is connected yet it prints a `harness_wiring`+notice: connecting gbrain to the agent you run in is part of the install, so do+it now (Step 5), not after the user replies. It also prints the settings in+effect once, as an `[AGENT]` block (`gbrain init --json`: a notice of kind+`ask` with `decisions[]`):-| Decision | What the user picks | Default |+| Setting | What the user can change | In effect ||---|---|---|| `search_mode` | `conservative`, `balanced` or `tokenmax`, with the cost matrix (Step 3.5) | the mode init applied, with its reason |-| `writeback` | whether you save salient facts from conversations without being asked | recommended `salient`; off until the user agrees |-| `harness_wiring` | registering gbrain in the harness you run in (Step 5) | the exact registration command for the detected harness |+| `writeback` | whether you save salient facts from conversations without being asked | off; gbrain recommends `salient`, which the user opts into || `skills_scaffold` | optional bundled skills in the agent workspace | skip |+| `upkeep` | free upkeep while the agent's session is open | on |-Relay the bundle's one `user_message` to the user ("Reply 'defaults' to accept-…") and apply each answer with the command its option names. One round-trip-covers Step 3.5 and the wiring question. Details:+Connect first, then report the install and relay the bundle's `user_message`+in that reply, as the settings in effect and how to change them. Apply an+answer with the command its option names whenever the user gives one. Details:[first run](docs/protocol/AGENT_OPERATOR_v1.md#first-run).The user's markdown files and canonical skills are SEPARATE from this tool repo.@@ -2142,20 +2138,18 @@ The bundled skills `skills/db-repair/` (triggers on the marker) and`skills/postgres-adopt/` (detect / prefer / install / migrate-wrap) drive thisloop; full reference in `docs/ENGINES.md` ("Engine detection and access repair").-## Step 3.5: Confirm search mode with the user (DO NOT SKIP)+## Step 3.5: Tell the user which search mode is in effect (DO NOT SKIP)-This is the `search_mode` decision from the first-run bundle.+This is the `search_mode` setting from the first-run settings.`gbrain init` auto-applied a default search mode: `tokenmax` with a chat key(Anthropic, OpenAI or Google), `balanced` with a ready reranker but no chat key,and `conservative` when your subagent tier is Haiku-class or neither exists. The init output-included the cost matrix below preceded by `[AGENT]` markers. You must NOT-silently accept the default. Stop and ask the operator.--After `gbrain setup <harness>` the harness is already wired when the matrix-appears, so there is nothing to stop before: show the matrix and the applied-mode in the reply that reports the install, as a choice the user can make at-any time, and run `gbrain config set search.mode <mode>` when they pick one.-Don't hold the install open for the answer.+included the cost matrix below preceded by `[AGENT]` markers. Don't accept it+silently, and don't stop the install to ask either: on every harness, connect+gbrain first (with `gbrain setup <harness>` or the `harness_wiring` step), then+show the matrix and the applied mode in the reply that reports the install, as+a choice the user can make at any time, and run+`gbrain config set search.mode <mode>` when they pick one.If you already know the operator's choice, record it at install time instead:`gbrain init --search-mode <conservative|balanced|tokenmax>` stores it as the@@ -2182,9 +2176,9 @@ Estimated downstream input cost of the retrieved payload @ 10K queries/mo:**Ask the operator (paraphrase if needed):**-> Your gbrain just installed with search mode `<auto-applied default>`. This is-> a one-time setup decision that controls retrieval payload size. Which mode-> do you want?+> Your gbrain is installed and connected, with search mode+> `<auto-applied default>`. It controls retrieval payload size, and you can+> change it any time. The modes:>> 1) conservative — tight 4K budget, 10 chunks max, no reranker.> Best for Haiku subagents, cost-sensitive setups, high-volume loops.@@ -2691,9 +2685,8 @@ again. Pass `--no-bun-floor-check` only after checking the target yourselfwhen the floor cannot be read (offline). See[Bun floor](docs/guides/upgrades-auto-update.md#bun-floor).-The autopilot opt-out skips installation and service rewrites, including package-postinstall hooks; it does not skip other migrations. Keep the environment form-on the package-manager command because hooks run before `post-upgrade`.+The autopilot opt-out skips installation and service rewrites; it does not skip+other migrations.`GBRAIN_NO_REEMBED=1` separately skips the potentially paid reindex step.For an existing service deployment, review its migration guide instead ofassuming memory-only options are the desired maintenance policy. Verify a known@@ -3061,11 +3054,28 @@ stdout (`--json`):"root_identity": "(device and inode of the content root)"},"notices": [+ {+ "code": "harness_wiring",+ "kind": "info",+ "why": "gbrain is not connected to an agent here, and this step is not a command the agent runs by itself; say so in the reply that reports the install, without waiting on it. Which agent app should get gbrain memory? The install guide has a one-line command for each. For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "fix": {+ "consent": [+ "persistent_install"+ ],+ "actor": "user",+ "next": "report",+ "why": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "user_message": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",+ "docs": "https://github.com/garrytan/gbrain/blob/master/docs/protocol/MEMORY_VERBS_v1.md#install-the-4-command-quickstart",+ "requires_exclusive": false+ },+ "contract_version": 1+ },{"code": "first_run_decisions","kind": "ask",- "why": "The brain is ready. These settings were applied with defaults or need the user's choice; none blocks using the brain.",- "user_message": "gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: conservative; writeback: salient; harness_wiring: skip; upkeep: on), or tell me what to change.",+ "why": "The brain is ready and these first-run settings are in effect as listed; none blocks memory. Relay them once, in the reply that reports the install, as the current settings and how to change them; do not hold the install open or end it waiting on an answer. When the user picks an option, run its command. Nothing paid turns on from these settings without a key the user supplied.",+ "user_message": "gbrain is installed. In effect: search mode conservative; agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). Upkeep: free upkeep runs on its own while your agent's gbrain session is open. Nothing is deleted or paid for without you. Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule. Estimated downstream input cost of the retrieved payload at 10K queries/month (Haiku 5.5 / Sonnet 5.5 / Opus 5.5): conservative $4 / $80 / $160, balanced $10 / $200 / $400, tokenmax $20 / $400 / $800 per month. Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.","decisions": [{"id": "search_mode",@@ -3146,24 +3156,8 @@ stdout (`--json`):]}],- "default": "salient",- "default_reason": "Recommended for a personal brain: the brain learns what the user tells their agents. It is opt-in, so it applies only when the user accepts the defaults or picks it."- },- {- "id": "harness_wiring",- "question": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",- "options": [- {- "id": "wire",- "label": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw)."- },- {- "id": "skip",- "label": "Do not register gbrain with an agent harness now."- }- ],- "default": "skip",- "default_reason": "No agent harness was detected."+ "default": "off",+ "default_reason": "In effect now: agents save only what the user asks them to remember. salient is recommended for a personal brain; it is opt-in, so it turns on only when the user picks it."},{"id": "upkeep",@@ -3196,7 +3190,7 @@ stdout (`--json`):}```-stdout is one document; the brain is ready and nothing blocks using it. The `first_run_decisions` notice is `kind: ask`, so the agent relays its `user_message` ("gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: conservative; writeback: salient; harness_wiring: skip; upkeep: on), or tell me what to change.") once and stops. The decisions are `search_mode` (default `conservative`), `writeback` (default `salient`), `harness_wiring` (default `skip`), `upkeep` (default `on`); each option carries the exact argv to apply it, so a reply of "defaults" needs no command at all.+stdout is one document; the brain is ready and nothing blocks using it. The agent first does the `harness_wiring` step: connecting gbrain to itself is part of the install, not a setting. It then reports the install and relays the `first_run_decisions` `user_message` ("gbrain is installed. In effect: search mode conservative; agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). Upkeep: free upkeep runs on its own while your agent's gbrain session is open. Nothing is deleted or paid for without you. Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule. Estimated downstream input cost of the retrieved payload at 10K queries/month (Haiku 5.5 / Sonnet 5.5 / Opus 5.5): conservative $4 / $80 / $160, balanced $10 / $200 / $400, tokenmax $20 / $400 / $800 per month. Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.") once in that reply, without waiting for an answer. The settings in effect are `search_mode` (default `conservative`), `writeback` (default `off`), `upkeep` (default `on`); each option carries the exact argv to apply it when the user picks one.### 5. A caller mistake over stdio MCP, recorded: `run` (journey)@@ -4066,19 +4060,23 @@ stays up on its port in status-only mode instead of exiting:## First run-`gbrain init` emits one decision bundle instead of scattered prompts: an-`[AGENT]` block in human output, and a notice of kind `ask` in `init --json`.-Init does not wait for the answers; it exits 0 with defaults applied.+`gbrain init` applies its defaults and exits 0. It emits a `harness_wiring`+notice when no agent is connected yet, and one bundle of the settings in+effect: an `[AGENT]` block in human output, and a notice of kind `ask` in+`init --json`. Nothing in the bundle waits for an answer.-| Decision | Options | Default |+| Setting | Options | In effect ||---|---|---|| `search_mode` | `conservative`, `balanced`, `tokenmax`, with the cost matrix | applied at init, with the reason |-| `writeback` | `off`, `salient`, `all` | recommended `salient` (the user opts in) |-| `harness_wiring` | the registration command for the detected harness | the readiness `harness_wiring` fix |+| `writeback` | `off`, `salient`, `all` | `off`; gbrain recommends `salient` (the user opts in) || `skills_scaffold` | optional | skip |+| `upkeep` | `on`, `off` | `on` (free tier only without a key) |-Relay the bundle's one `user_message` ("Reply 'defaults' to accept …"); apply-each answer with the decision's `argv`. Then:+Connect first, then report the install and relay the bundle's `user_message`+in that reply: the settings in effect, the cost matrix and how to change each.+Don't end the install on a question. Apply an answer with the option's `argv`+whenever the user gives one. Nothing paid turns on from these settings without+a key the user supplied. The steps:1. Register gbrain with the harness using the `harness_wiring` fix. Theregistration always uses the absolute gbrain path and `--surface starter`,diff --git a/package.json b/package.jsonindex c3929c00d3..6665d53b90 100644--- a/package.json+++ b/package.json@@ -149,7 +149,6 @@"check:source-scope-onboard": "bash scripts/check-source-scope-onboard.sh","check:getpage-scope": "node scripts/check-getpage-scoped-write.mjs","check:origin-assignment": "node scripts/check-origin-assignment.mjs",- "postinstall": "bun run scripts/postinstall.ts","prepublish:clawhub": "bun run build:all","publish:clawhub": "clawhub package publish . --family bundle-plugin","check:skill-refs": "bun scripts/check-skill-refs.mjs",diff --git a/plugin-variants/gbrain-coding/skills/conventions/agent-operator-protocol.md b/plugin-variants/gbrain-coding/skills/conventions/agent-operator-protocol.mdindex 8ea5d45dc8..8245825bba 100644--- a/plugin-variants/gbrain-coding/skills/conventions/agent-operator-protocol.md+++ b/plugin-variants/gbrain-coding/skills/conventions/agent-operator-protocol.md@@ -269,11 +269,28 @@ stdout (`--json`):"root_identity": "(device and inode of the content root)"},"notices": [+ {+ "code": "harness_wiring",+ "kind": "info",+ "why": "gbrain is not connected to an agent here, and this step is not a command the agent runs by itself; say so in the reply that reports the install, without waiting on it. Which agent app should get gbrain memory? The install guide has a one-line command for each. For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "fix": {+ "consent": [+ "persistent_install"+ ],+ "actor": "user",+ "next": "report",+ "why": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "user_message": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",+ "docs": "https://github.com/garrytan/gbrain/blob/master/docs/protocol/MEMORY_VERBS_v1.md#install-the-4-command-quickstart",+ "requires_exclusive": false+ },+ "contract_version": 1+ },{"code": "first_run_decisions","kind": "ask",- "why": "The brain is ready. These settings were applied with defaults or need the user's choice; none blocks using the brain.",- "user_message": "gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: conservative; writeback: salient; harness_wiring: skip; upkeep: on), or tell me what to change.",+ "why": "The brain is ready and these first-run settings are in effect as listed; none blocks memory. Relay them once, in the reply that reports the install, as the current settings and how to change them; do not hold the install open or end it waiting on an answer. When the user picks an option, run its command. Nothing paid turns on from these settings without a key the user supplied.",+ "user_message": "gbrain is installed. In effect: search mode conservative; agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). Upkeep: free upkeep runs on its own while your agent's gbrain session is open. Nothing is deleted or paid for without you. Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule. Estimated downstream input cost of the retrieved payload at 10K queries/month (Haiku 5.5 / Sonnet 5.5 / Opus 5.5): conservative $4 / $80 / $160, balanced $10 / $200 / $400, tokenmax $20 / $400 / $800 per month. Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.","decisions": [{"id": "search_mode",@@ -354,24 +371,8 @@ stdout (`--json`):]}],- "default": "salient",- "default_reason": "Recommended for a personal brain: the brain learns what the user tells their agents. It is opt-in, so it applies only when the user accepts the defaults or picks it."- },- {- "id": "harness_wiring",- "question": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",- "options": [- {- "id": "wire",- "label": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw)."- },- {- "id": "skip",- "label": "Do not register gbrain with an agent harness now."- }- ],- "default": "skip",- "default_reason": "No agent harness was detected."+ "default": "off",+ "default_reason": "In effect now: agents save only what the user asks them to remember. salient is recommended for a personal brain; it is opt-in, so it turns on only when the user picks it."},{"id": "upkeep",@@ -404,7 +405,7 @@ stdout (`--json`):}```-stdout is one document; the brain is ready and nothing blocks using it. The `first_run_decisions` notice is `kind: ask`, so the agent relays its `user_message` ("gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: conservative; writeback: salient; harness_wiring: skip; upkeep: on), or tell me what to change.") once and stops. The decisions are `search_mode` (default `conservative`), `writeback` (default `salient`), `harness_wiring` (default `skip`), `upkeep` (default `on`); each option carries the exact argv to apply it, so a reply of "defaults" needs no command at all.+stdout is one document; the brain is ready and nothing blocks using it. The agent first does the `harness_wiring` step: connecting gbrain to itself is part of the install, not a setting. It then reports the install and relays the `first_run_decisions` `user_message` ("gbrain is installed. In effect: search mode conservative; agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). Upkeep: free upkeep runs on its own while your agent's gbrain session is open. Nothing is deleted or paid for without you. Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule. Estimated downstream input cost of the retrieved payload at 10K queries/month (Haiku 5.5 / Sonnet 5.5 / Opus 5.5): conservative $4 / $80 / $160, balanced $10 / $200 / $400, tokenmax $20 / $400 / $800 per month. Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.") once in that reply, without waiting for an answer. The settings in effect are `search_mode` (default `conservative`), `writeback` (default `off`), `upkeep` (default `on`); each option carries the exact argv to apply it when the user picks one.### 5. A caller mistake over stdio MCP, recorded: `run` (journey)@@ -1274,19 +1275,23 @@ stays up on its port in status-only mode instead of exiting:## First run-`gbrain init` emits one decision bundle instead of scattered prompts: an-`[AGENT]` block in human output, and a notice of kind `ask` in `init --json`.-Init does not wait for the answers; it exits 0 with defaults applied.+`gbrain init` applies its defaults and exits 0. It emits a `harness_wiring`+notice when no agent is connected yet, and one bundle of the settings in+effect: an `[AGENT]` block in human output, and a notice of kind `ask` in+`init --json`. Nothing in the bundle waits for an answer.-| Decision | Options | Default |+| Setting | Options | In effect ||---|---|---|| `search_mode` | `conservative`, `balanced`, `tokenmax`, with the cost matrix | applied at init, with the reason |-| `writeback` | `off`, `salient`, `all` | recommended `salient` (the user opts in) |-| `harness_wiring` | the registration command for the detected harness | the readiness `harness_wiring` fix |+| `writeback` | `off`, `salient`, `all` | `off`; gbrain recommends `salient` (the user opts in) || `skills_scaffold` | optional | skip |+| `upkeep` | `on`, `off` | `on` (free tier only without a key) |-Relay the bundle's one `user_message` ("Reply 'defaults' to accept …"); apply-each answer with the decision's `argv`. Then:+Connect first, then report the install and relay the bundle's `user_message`+in that reply: the settings in effect, the cost matrix and how to change each.+Don't end the install on a question. Apply an answer with the option's `argv`+whenever the user gives one. Nothing paid turns on from these settings without+a key the user supplied. The steps:1. Register gbrain with the harness using the `harness_wiring` fix. Theregistration always uses the absolute gbrain path and `--surface starter`,diff --git a/plugin-variants/gbrain-daily/skills/conventions/agent-operator-protocol.md b/plugin-variants/gbrain-daily/skills/conventions/agent-operator-protocol.mdindex 8ea5d45dc8..8245825bba 100644--- a/plugin-variants/gbrain-daily/skills/conventions/agent-operator-protocol.md+++ b/plugin-variants/gbrain-daily/skills/conventions/agent-operator-protocol.md@@ -269,11 +269,28 @@ stdout (`--json`):"root_identity": "(device and inode of the content root)"},"notices": [+ {+ "code": "harness_wiring",+ "kind": "info",+ "why": "gbrain is not connected to an agent here, and this step is not a command the agent runs by itself; say so in the reply that reports the install, without waiting on it. Which agent app should get gbrain memory? The install guide has a one-line command for each. For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "fix": {+ "consent": [+ "persistent_install"+ ],+ "actor": "user",+ "next": "report",+ "why": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "user_message": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",+ "docs": "https://github.com/garrytan/gbrain/blob/master/docs/protocol/MEMORY_VERBS_v1.md#install-the-4-command-quickstart",+ "requires_exclusive": false+ },+ "contract_version": 1+ },{"code": "first_run_decisions","kind": "ask",- "why": "The brain is ready. These settings were applied with defaults or need the user's choice; none blocks using the brain.",- "user_message": "gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: conservative; writeback: salient; harness_wiring: skip; upkeep: on), or tell me what to change.",+ "why": "The brain is ready and these first-run settings are in effect as listed; none blocks memory. Relay them once, in the reply that reports the install, as the current settings and how to change them; do not hold the install open or end it waiting on an answer. When the user picks an option, run its command. Nothing paid turns on from these settings without a key the user supplied.",+ "user_message": "gbrain is installed. In effect: search mode conservative; agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). Upkeep: free upkeep runs on its own while your agent's gbrain session is open. Nothing is deleted or paid for without you. Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule. Estimated downstream input cost of the retrieved payload at 10K queries/month (Haiku 5.5 / Sonnet 5.5 / Opus 5.5): conservative $4 / $80 / $160, balanced $10 / $200 / $400, tokenmax $20 / $400 / $800 per month. Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.","decisions": [{"id": "search_mode",@@ -354,24 +371,8 @@ stdout (`--json`):]}],- "default": "salient",- "default_reason": "Recommended for a personal brain: the brain learns what the user tells their agents. It is opt-in, so it applies only when the user accepts the defaults or picks it."- },- {- "id": "harness_wiring",- "question": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",- "options": [- {- "id": "wire",- "label": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw)."- },- {- "id": "skip",- "label": "Do not register gbrain with an agent harness now."- }- ],- "default": "skip",- "default_reason": "No agent harness was detected."+ "default": "off",+ "default_reason": "In effect now: agents save only what the user asks them to remember. salient is recommended for a personal brain; it is opt-in, so it turns on only when the user picks it."},{"id": "upkeep",@@ -404,7 +405,7 @@ stdout (`--json`):}```-stdout is one document; the brain is ready and nothing blocks using it. The `first_run_decisions` notice is `kind: ask`, so the agent relays its `user_message` ("gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: conservative; writeback: salient; harness_wiring: skip; upkeep: on), or tell me what to change.") once and stops. The decisions are `search_mode` (default `conservative`), `writeback` (default `salient`), `harness_wiring` (default `skip`), `upkeep` (default `on`); each option carries the exact argv to apply it, so a reply of "defaults" needs no command at all.+stdout is one document; the brain is ready and nothing blocks using it. The agent first does the `harness_wiring` step: connecting gbrain to itself is part of the install, not a setting. It then reports the install and relays the `first_run_decisions` `user_message` ("gbrain is installed. In effect: search mode conservative; agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). Upkeep: free upkeep runs on its own while your agent's gbrain session is open. Nothing is deleted or paid for without you. Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule. Estimated downstream input cost of the retrieved payload at 10K queries/month (Haiku 5.5 / Sonnet 5.5 / Opus 5.5): conservative $4 / $80 / $160, balanced $10 / $200 / $400, tokenmax $20 / $400 / $800 per month. Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.") once in that reply, without waiting for an answer. The settings in effect are `search_mode` (default `conservative`), `writeback` (default `off`), `upkeep` (default `on`); each option carries the exact argv to apply it when the user picks one.### 5. A caller mistake over stdio MCP, recorded: `run` (journey)@@ -1274,19 +1275,23 @@ stays up on its port in status-only mode instead of exiting:## First run-`gbrain init` emits one decision bundle instead of scattered prompts: an-`[AGENT]` block in human output, and a notice of kind `ask` in `init --json`.-Init does not wait for the answers; it exits 0 with defaults applied.+`gbrain init` applies its defaults and exits 0. It emits a `harness_wiring`+notice when no agent is connected yet, and one bundle of the settings in+effect: an `[AGENT]` block in human output, and a notice of kind `ask` in+`init --json`. Nothing in the bundle waits for an answer.-| Decision | Options | Default |+| Setting | Options | In effect ||---|---|---|| `search_mode` | `conservative`, `balanced`, `tokenmax`, with the cost matrix | applied at init, with the reason |-| `writeback` | `off`, `salient`, `all` | recommended `salient` (the user opts in) |-| `harness_wiring` | the registration command for the detected harness | the readiness `harness_wiring` fix |+| `writeback` | `off`, `salient`, `all` | `off`; gbrain recommends `salient` (the user opts in) || `skills_scaffold` | optional | skip |+| `upkeep` | `on`, `off` | `on` (free tier only without a key) |-Relay the bundle's one `user_message` ("Reply 'defaults' to accept …"); apply-each answer with the decision's `argv`. Then:+Connect first, then report the install and relay the bundle's `user_message`+in that reply: the settings in effect, the cost matrix and how to change each.+Don't end the install on a question. Apply an answer with the option's `argv`+whenever the user gives one. Nothing paid turns on from these settings without+a key the user supplied. The steps:1. Register gbrain with the harness using the `harness_wiring` fix. Theregistration always uses the absolute gbrain path and `--surface starter`,diff --git a/plugin/skills/conventions/agent-operator-protocol.md b/plugin/skills/conventions/agent-operator-protocol.mdindex 8ea5d45dc8..8245825bba 100644--- a/plugin/skills/conventions/agent-operator-protocol.md+++ b/plugin/skills/conventions/agent-operator-protocol.md@@ -269,11 +269,28 @@ stdout (`--json`):"root_identity": "(device and inode of the content root)"},"notices": [+ {+ "code": "harness_wiring",+ "kind": "info",+ "why": "gbrain is not connected to an agent here, and this step is not a command the agent runs by itself; say so in the reply that reports the install, without waiting on it. Which agent app should get gbrain memory? The install guide has a one-line command for each. For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "fix": {+ "consent": [+ "persistent_install"+ ],+ "actor": "user",+ "next": "report",+ "why": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "user_message": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",+ "docs": "https://github.com/garrytan/gbrain/blob/master/docs/protocol/MEMORY_VERBS_v1.md#install-the-4-command-quickstart",+ "requires_exclusive": false+ },+ "contract_version": 1+ },{"code": "first_run_decisions","kind": "ask",- "why": "The brain is ready. These settings were applied with defaults or need the user's choice; none blocks using the brain.",- "user_message": "gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: conservative; writeback: salient; harness_wiring: skip; upkeep: on), or tell me what to change.",+ "why": "The brain is ready and these first-run settings are in effect as listed; none blocks memory. Relay them once, in the reply that reports the install, as the current settings and how to change them; do not hold the install open or end it waiting on an answer. When the user picks an option, run its command. Nothing paid turns on from these settings without a key the user supplied.",+ "user_message": "gbrain is installed. In effect: search mode conservative; agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). Upkeep: free upkeep runs on its own while your agent's gbrain session is open. Nothing is deleted or paid for without you. Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule. Estimated downstream input cost of the retrieved payload at 10K queries/month (Haiku 5.5 / Sonnet 5.5 / Opus 5.5): conservative $4 / $80 / $160, balanced $10 / $200 / $400, tokenmax $20 / $400 / $800 per month. Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.","decisions": [{"id": "search_mode",@@ -354,24 +371,8 @@ stdout (`--json`):]}],- "default": "salient",- "default_reason": "Recommended for a personal brain: the brain learns what the user tells their agents. It is opt-in, so it applies only when the user accepts the defaults or picks it."- },- {- "id": "harness_wiring",- "question": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",- "options": [- {- "id": "wire",- "label": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw)."- },- {- "id": "skip",- "label": "Do not register gbrain with an agent harness now."- }- ],- "default": "skip",- "default_reason": "No agent harness was detected."+ "default": "off",+ "default_reason": "In effect now: agents save only what the user asks them to remember. salient is recommended for a personal brain; it is opt-in, so it turns on only when the user picks it."},{"id": "upkeep",@@ -404,7 +405,7 @@ stdout (`--json`):}```-stdout is one document; the brain is ready and nothing blocks using it. The `first_run_decisions` notice is `kind: ask`, so the agent relays its `user_message` ("gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: conservative; writeback: salient; harness_wiring: skip; upkeep: on), or tell me what to change.") once and stops. The decisions are `search_mode` (default `conservative`), `writeback` (default `salient`), `harness_wiring` (default `skip`), `upkeep` (default `on`); each option carries the exact argv to apply it, so a reply of "defaults" needs no command at all.+stdout is one document; the brain is ready and nothing blocks using it. The agent first does the `harness_wiring` step: connecting gbrain to itself is part of the install, not a setting. It then reports the install and relays the `first_run_decisions` `user_message` ("gbrain is installed. In effect: search mode conservative; agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). Upkeep: free upkeep runs on its own while your agent's gbrain session is open. Nothing is deleted or paid for without you. Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule. Estimated downstream input cost of the retrieved payload at 10K queries/month (Haiku 5.5 / Sonnet 5.5 / Opus 5.5): conservative $4 / $80 / $160, balanced $10 / $200 / $400, tokenmax $20 / $400 / $800 per month. Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.") once in that reply, without waiting for an answer. The settings in effect are `search_mode` (default `conservative`), `writeback` (default `off`), `upkeep` (default `on`); each option carries the exact argv to apply it when the user picks one.### 5. A caller mistake over stdio MCP, recorded: `run` (journey)@@ -1274,19 +1275,23 @@ stays up on its port in status-only mode instead of exiting:## First run-`gbrain init` emits one decision bundle instead of scattered prompts: an-`[AGENT]` block in human output, and a notice of kind `ask` in `init --json`.-Init does not wait for the answers; it exits 0 with defaults applied.+`gbrain init` applies its defaults and exits 0. It emits a `harness_wiring`+notice when no agent is connected yet, and one bundle of the settings in+effect: an `[AGENT]` block in human output, and a notice of kind `ask` in+`init --json`. Nothing in the bundle waits for an answer.-| Decision | Options | Default |+| Setting | Options | In effect ||---|---|---|| `search_mode` | `conservative`, `balanced`, `tokenmax`, with the cost matrix | applied at init, with the reason |-| `writeback` | `off`, `salient`, `all` | recommended `salient` (the user opts in) |-| `harness_wiring` | the registration command for the detected harness | the readiness `harness_wiring` fix |+| `writeback` | `off`, `salient`, `all` | `off`; gbrain recommends `salient` (the user opts in) || `skills_scaffold` | optional | skip |+| `upkeep` | `on`, `off` | `on` (free tier only without a key) |-Relay the bundle's one `user_message` ("Reply 'defaults' to accept …"); apply-each answer with the decision's `argv`. Then:+Connect first, then report the install and relay the bundle's `user_message`+in that reply: the settings in effect, the cost matrix and how to change each.+Don't end the install on a question. Apply an answer with the option's `argv`+whenever the user gives one. Nothing paid turns on from these settings without+a key the user supplied. The steps:1. Register gbrain with the harness using the `harness_wiring` fix. Theregistration always uses the absolute gbrain path and `--surface starter`,diff --git a/plugin/skills/setup/SKILL.md b/plugin/skills/setup/SKILL.mdindex 14a725da75..42b72f0ed4 100644--- a/plugin/skills/setup/SKILL.md+++ b/plugin/skills/setup/SKILL.md@@ -85,9 +85,10 @@ npm package named `gbrain`, or `bun add` in the user's current project.Local/thin-client conversion requires explicit intent and preservation of theprevious configuration.-**Required search-mode choice:** initialization may select a noninteractive-default and print a nine-cell cost matrix with `[AGENT]` markers. Relay that-matrix and confirm the operator's choice before continuing. Follow Step 3.5 of+**Search mode in effect:** initialization selects a noninteractive default and+prints a nine-cell cost matrix with `[AGENT]` markers. Connect memory first,+then relay that matrix and the mode in effect in the reply that reports the+install; apply the operator's choice when they give it. Follow Step 3.5 of[INSTALL_FOR_AGENTS.md](https://github.com/garrytan/gbrain/blob/master/INSTALL_FOR_AGENTS.md); use the printed matrix,not remembered prices. Illustrative model API costs are separate from aharness subscription. This choice does not enable paid APIs or capture.diff --git a/scripts/build-agent-protocol.ts b/scripts/build-agent-protocol.tsindex 84a6ab4d88..d3df5a5163 100644--- a/scripts/build-agent-protocol.ts+++ b/scripts/build-agent-protocol.ts@@ -67,7 +67,7 @@ function withNext(fix: Json, ctx: RenderContext): Json {const next = deriveNext(fix as unknown as Action, ctx);const out: Json = {};for (const [k, v] of Object.entries(fix)) {- out[k] = k === 'then' && v && typeof v === 'object' ? withNext(v as Json, ctx) : v;+ out[k] = k === 'then' && v && typeof v === 'object' ? withNext(v as Json, ctx) : typeof v === 'string' ? hydrate(v, ctx) : v;if (k === 'actor') out.next = next;}return out;@@ -182,9 +182,9 @@ export const TRANSCRIPTS: readonly Transcript[] = [after: (doc) => {const bundle = (doc.notices as Json[]).find(n => n.code === 'first_run_decisions') as Json;const ids = (bundle.decisions as Json[]).map(d => `\`${d.id}\` (default \`${d.default}\`)`).join(', ');- return `stdout is one document; the brain is ready and nothing blocks using it. The \`first_run_decisions\` notice is \`kind: ask\`, `- + `so the agent relays its \`user_message\` ("${bundle.user_message}") once and stops. The decisions are ${ids}; `- + 'each option carries the exact argv to apply it, so a reply of "defaults" needs no command at all.';+ return `stdout is one document; the brain is ready and nothing blocks using it. The agent first does the \`harness_wiring\` step: connecting gbrain to itself is part of the install, not a setting. `+ + `It then reports the install and relays the \`first_run_decisions\` \`user_message\` ("${bundle.user_message}") once in that reply, without waiting for an answer. `+ + `The settings in effect are ${ids}; each option carries the exact argv to apply it when the user picks one.`;},},{diff --git a/scripts/postinstall.ts b/scripts/postinstall.tsdeleted file mode 100644index 870cf8cb11..0000000000--- a/scripts/postinstall.ts+++ /dev/null@@ -1,78 +0,0 @@-#!/usr/bin/env bun-// scripts/postinstall.ts-//-// Postinstall hook: after `bun install`, apply any pending schema migrations so-// a freshly-installed gbrain is immediately usable. Wired via package.json-// ("postinstall": "bun run scripts/postinstall.ts") as a real Bun script rather-// than an inline `node -e` one-liner.-//-// Why a script file and not an inline command:-// Embedding a program inside the package.json postinstall string lets the-// lifecycle shell mangle it. Bun's Windows script-runner expands `\n` in the-// hint string into a REAL newline before node sees it, producing-// `SyntaxError: Invalid or unexpected token` and aborting the whole install.-// `node` is also not guaranteed present under a Bun install (bun is the-// guaranteed runtime), and `shell: win32` re-opens a quoting surface. A-// checked-in .ts run by `bun run` sidesteps all three.-//-// Uses Bun APIs only — `which()` for Windows-aware PATH resolution (finds-// gbrain.exe / gbrain.cmd) and an argv-array `Bun.spawnSync` (no shell, nothing-// to quote). It NEVER fails the install: every path exits 0.--import { which } from 'bun';--// Repo modules load dynamically inside try/catch: a static import of a file-// that is not on disk (a Docker dependency layer, a partial checkout) would-// exit 1 before any line here runs and fail the whole install.-async function runtimeRefusalMessage(): Promise<string | null> {- try {- const { unsupportedBunMessage } = await import('../src/core/runtime-version.ts');- return unsupportedBunMessage();- } catch {- return null;- }-}--// The install itself runs on the user's Bun, so this is the first place an-// upgrade onto a newer Bun floor can say so. Nothing else here would work:-// every gbrain command refuses until Bun is upgraded.-const runtimeRefusal = await runtimeRefusalMessage();-if (runtimeRefusal) {- console.error(`[gbrain] Installed, but gbrain will not start on this Bun.\n${runtimeRefusal}`);- process.exit(0);-}--const HINT =- '[gbrain] postinstall skipped. If installed via bun install -g github:...: ' +- 'run `gbrain doctor` and `gbrain apply-migrations --yes` manually. ' +- 'See https://github.com/garrytan/gbrain/issues/218';--// #5693: under `gbrain upgrade`, post-upgrade owns migrations. Running them-// here too would run them twice, and a slow run here outlives the install-// timeout that `gbrain upgrade` reads as a failed upgrade.-if (process.env.GBRAIN_UPGRADE_OWNS_MIGRATIONS === '1') {- console.error('[gbrain] postinstall: migrations deferred to `gbrain post-upgrade`.');- process.exit(0);-}--// Windows-aware PATH resolution — finds gbrain, gbrain.exe or gbrain.cmd.-const bin = which('gbrain');--if (!bin) {- // Fresh clone / global install where gbrain isn't on PATH yet: skip cleanly.- console.error(HINT);- process.exit(0);-}--try {- const r = Bun.spawnSync({- cmd: [bin, 'apply-migrations', '--yes', '--non-interactive'],- stdout: 'inherit',- stderr: 'inherit',- });- if (r.exitCode !== 0) console.error(HINT);-} catch {- console.error(HINT);-}--process.exit(0); // never abort the installdiff --git a/scripts/structural-suites.tsv b/scripts/structural-suites.tsvindex 487b37b8bc..4c2e09991a 100644--- a/scripts/structural-suites.tsv+++ b/scripts/structural-suites.tsv@@ -217,6 +217,7 @@ test/hook-push-spawn-env.test.ts spawnDetachedPush env handoff 2 readFileSynctest/hook-push-spawn-env.test.ts tryExecAsync env handoff 1 readFileSynctest/import-private-hold-callers-7897.test.ts import entry points hold a non-canonical private request (#7897) 2 readFileSynctest/init-mode-picker.test.ts cost matrix: newest models, priced from model-pricing 6 readFileSync+test/install-no-postinstall.test.ts GST-2732: installing gbrain runs no lifecycle script 2 readFileSynctest/integrations-install.test.ts installRecipeIntoHostRepo — happy path 6 readFileSynctest/integrations.test.ts CLI integration 3 source-surface-helpertest/jobs-embed-background-parity.serial.test.ts embed job background parity (D7) 2 readFileSync,source-surface-helperdiff --git a/scripts/test-weights.json b/scripts/test-weights.jsonindex b5e413ce98..84a85bf118 100644--- a/scripts/test-weights.json+++ b/scripts/test-weights.json@@ -3723,7 +3723,6 @@"test/scripts/order-hunt.test.ts": 2,"test/scripts/postgres-lane-coverage.test.ts": 7144,"test/scripts/postgres-unit-arms.test.ts": 4720,- "test/scripts/postinstall-standalone.test.ts": 5,"test/scripts/pregate-remote-gate.test.ts": 2446,"test/scripts/production-soak-ubicloud.test.ts": 487,"test/scripts/promote-stable.test.ts": 351,diff --git a/scripts/test-weights.metadata.json b/scripts/test-weights.metadata.jsonindex 60ab20a8fc..8ba3d75f74 100644--- a/scripts/test-weights.metadata.json+++ b/scripts/test-weights.metadata.json@@ -18,7 +18,7 @@"503e7b65f4e5c6542eb447fef56b186a69c182cf","5dc712b93742ac9ebb82983917659ce8ef493e7c"],- "measuredFiles": 4889,- "totalFiles": 4889,+ "measuredFiles": 4888,+ "totalFiles": 4888,"mergeExisting": false}diff --git a/scripts/ubicloud/weights.json b/scripts/ubicloud/weights.jsonindex b0bdd521d0..6ff668cd67 100644--- a/scripts/ubicloud/weights.json+++ b/scripts/ubicloud/weights.json@@ -2983,7 +2983,6 @@"unit:test/scripts/normalize-tokens.test.ts": 417,"unit:test/scripts/postgres-lane-coverage.test.ts": 5373,"unit:test/scripts/postgres-unit-arms.test.ts": 230,- "unit:test/scripts/postinstall-standalone.test.ts": 213,"unit:test/scripts/regen-all.test.ts": 180,"unit:test/scripts/release-gate.test.ts": 205,"unit:test/scripts/release-restamp.test.ts": 20891,diff --git a/skills/conventions/agent-operator-protocol.md b/skills/conventions/agent-operator-protocol.mdindex 8ea5d45dc8..8245825bba 100644--- a/skills/conventions/agent-operator-protocol.md+++ b/skills/conventions/agent-operator-protocol.md@@ -269,11 +269,28 @@ stdout (`--json`):"root_identity": "(device and inode of the content root)"},"notices": [+ {+ "code": "harness_wiring",+ "kind": "info",+ "why": "gbrain is not connected to an agent here, and this step is not a command the agent runs by itself; say so in the reply that reports the install, without waiting on it. Which agent app should get gbrain memory? The install guide has a one-line command for each. For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "fix": {+ "consent": [+ "persistent_install"+ ],+ "actor": "user",+ "next": "report",+ "why": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "user_message": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",+ "docs": "https://github.com/garrytan/gbrain/blob/master/docs/protocol/MEMORY_VERBS_v1.md#install-the-4-command-quickstart",+ "requires_exclusive": false+ },+ "contract_version": 1+ },{"code": "first_run_decisions","kind": "ask",- "why": "The brain is ready. These settings were applied with defaults or need the user's choice; none blocks using the brain.",- "user_message": "gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: conservative; writeback: salient; harness_wiring: skip; upkeep: on), or tell me what to change.",+ "why": "The brain is ready and these first-run settings are in effect as listed; none blocks memory. Relay them once, in the reply that reports the install, as the current settings and how to change them; do not hold the install open or end it waiting on an answer. When the user picks an option, run its command. Nothing paid turns on from these settings without a key the user supplied.",+ "user_message": "gbrain is installed. In effect: search mode conservative; agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). Upkeep: free upkeep runs on its own while your agent's gbrain session is open. Nothing is deleted or paid for without you. Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule. Estimated downstream input cost of the retrieved payload at 10K queries/month (Haiku 5.5 / Sonnet 5.5 / Opus 5.5): conservative $4 / $80 / $160, balanced $10 / $200 / $400, tokenmax $20 / $400 / $800 per month. Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.","decisions": [{"id": "search_mode",@@ -354,24 +371,8 @@ stdout (`--json`):]}],- "default": "salient",- "default_reason": "Recommended for a personal brain: the brain learns what the user tells their agents. It is opt-in, so it applies only when the user accepts the defaults or picks it."- },- {- "id": "harness_wiring",- "question": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",- "options": [- {- "id": "wire",- "label": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw)."- },- {- "id": "skip",- "label": "Do not register gbrain with an agent harness now."- }- ],- "default": "skip",- "default_reason": "No agent harness was detected."+ "default": "off",+ "default_reason": "In effect now: agents save only what the user asks them to remember. salient is recommended for a personal brain; it is opt-in, so it turns on only when the user picks it."},{"id": "upkeep",@@ -404,7 +405,7 @@ stdout (`--json`):}```-stdout is one document; the brain is ready and nothing blocks using it. The `first_run_decisions` notice is `kind: ask`, so the agent relays its `user_message` ("gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: conservative; writeback: salient; harness_wiring: skip; upkeep: on), or tell me what to change.") once and stops. The decisions are `search_mode` (default `conservative`), `writeback` (default `salient`), `harness_wiring` (default `skip`), `upkeep` (default `on`); each option carries the exact argv to apply it, so a reply of "defaults" needs no command at all.+stdout is one document; the brain is ready and nothing blocks using it. The agent first does the `harness_wiring` step: connecting gbrain to itself is part of the install, not a setting. It then reports the install and relays the `first_run_decisions` `user_message` ("gbrain is installed. In effect: search mode conservative; agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). Upkeep: free upkeep runs on its own while your agent's gbrain session is open. Nothing is deleted or paid for without you. Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule. Estimated downstream input cost of the retrieved payload at 10K queries/month (Haiku 5.5 / Sonnet 5.5 / Opus 5.5): conservative $4 / $80 / $160, balanced $10 / $200 / $400, tokenmax $20 / $400 / $800 per month. Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.") once in that reply, without waiting for an answer. The settings in effect are `search_mode` (default `conservative`), `writeback` (default `off`), `upkeep` (default `on`); each option carries the exact argv to apply it when the user picks one.### 5. A caller mistake over stdio MCP, recorded: `run` (journey)@@ -1274,19 +1275,23 @@ stays up on its port in status-only mode instead of exiting:## First run-`gbrain init` emits one decision bundle instead of scattered prompts: an-`[AGENT]` block in human output, and a notice of kind `ask` in `init --json`.-Init does not wait for the answers; it exits 0 with defaults applied.+`gbrain init` applies its defaults and exits 0. It emits a `harness_wiring`+notice when no agent is connected yet, and one bundle of the settings in+effect: an `[AGENT]` block in human output, and a notice of kind `ask` in+`init --json`. Nothing in the bundle waits for an answer.-| Decision | Options | Default |+| Setting | Options | In effect ||---|---|---|| `search_mode` | `conservative`, `balanced`, `tokenmax`, with the cost matrix | applied at init, with the reason |-| `writeback` | `off`, `salient`, `all` | recommended `salient` (the user opts in) |-| `harness_wiring` | the registration command for the detected harness | the readiness `harness_wiring` fix |+| `writeback` | `off`, `salient`, `all` | `off`; gbrain recommends `salient` (the user opts in) || `skills_scaffold` | optional | skip |+| `upkeep` | `on`, `off` | `on` (free tier only without a key) |-Relay the bundle's one `user_message` ("Reply 'defaults' to accept …"); apply-each answer with the decision's `argv`. Then:+Connect first, then report the install and relay the bundle's `user_message`+in that reply: the settings in effect, the cost matrix and how to change each.+Don't end the install on a question. Apply an answer with the option's `argv`+whenever the user gives one. Nothing paid turns on from these settings without+a key the user supplied. The steps:1. Register gbrain with the harness using the `harness_wiring` fix. Theregistration always uses the absolute gbrain path and `--surface starter`,diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.mdindex 158a055976..77dc1dfa6c 100644--- a/skills/setup/SKILL.md+++ b/skills/setup/SKILL.md@@ -84,9 +84,10 @@ npm package named `gbrain`, or `bun add` in the user's current project.Local/thin-client conversion requires explicit intent and preservation of theprevious configuration.-**Required search-mode choice:** initialization may select a noninteractive-default and print a nine-cell cost matrix with `[AGENT]` markers. Relay that-matrix and confirm the operator's choice before continuing. Follow Step 3.5 of+**Search mode in effect:** initialization selects a noninteractive default and+prints a nine-cell cost matrix with `[AGENT]` markers. Connect memory first,+then relay that matrix and the mode in effect in the reply that reports the+install; apply the operator's choice when they give it. Follow Step 3.5 of[INSTALL_FOR_AGENTS.md](https://github.com/garrytan/gbrain/blob/master/INSTALL_FOR_AGENTS.md); use the printed matrix,not remembered prices. Illustrative model API costs are separate from aharness subscription. This choice does not enable paid APIs or capture.diff --git a/skills/skills.lock.history.json b/skills/skills.lock.history.jsonindex 11446137e4..cae18a5b26 100644--- a/skills/skills.lock.history.json+++ b/skills/skills.lock.history.json@@ -270,7 +270,10 @@"12c7b876994b96babdffa903326f7e23253d54ad9023248820337f56f8770512","28b1a2e422e1886a32199c67047bfed544216852268731b0f79d3c77f2a7b0f6","2ef1e6ec2cdacfd6d666bf93b5f06c6d0d8bb7112a5cde49cc83ff43ff6b7a9a",+ "3d573138ee60d7c22c87717f4157b7e67db08add5d68c3e4a9fd2c06e5dc9e0b","4331a4ec8d3d58c54a1dd0c50f1b15e4e1d1fdf3273849ac1694df61d6bc0f2b",+ "48cb4d8df027ebf0516e4a0df35c5d8f6998ea35a4f4404d78a50c8a1d082c81",+ "54e3ae4874cffbd7d05bbd41f297c728848904c5993160aa60c4e478194c94d9","57b71aac90727684d3f66ed9d252c2fe357f6bb469549e3eb4480b0bf31cdd45","7e00066bda562585055f7989129eb9716dd22a2a04a7c8d4c76a368dc031f5a6","86ed21dfdd5e4b34cb7d5eb88532966c4e64a07d0401123421a9b33bd643c0a2",@@ -280,9 +283,11 @@"c9865fa1b903edfdf445c0723c2f9c62d91aa9d0f9b21264788f02ae6b42967c","d22b616c90d84d7035cf2c56ed2c59d361b06a0499f548ae21e81bd23823efce","d7cfc7e4c84f61392658cbe969058b1e8237b7d44c3ebdeec352569ffddbe001",+ "da3321a0d1464c1742afd10f3365082ad324782bcb2c2842fdba7b41fd248fa5","e268fd66b4bb18e6d91115f4869b58f60468ff446931a3a00ee3d784ed022d53","e54e9d63da45c852b2897303a97e37a5e67ecba749c45311703059e51524331a","eb87070d4ab1492b94f9e85b59aaa3dbf9ee0f484686d06b548c1a0ef14c845e",+ "efc6359d24c8d7017d941b65dd79f38ca4e323c7247c0c49054f194fbdf26df2","feefde8f9b02060747c63e5a97bde4f5f1e868d5cfe54746f94bc598e3aa65b6"],"conventions/brain-first.md": [@@ -1081,6 +1086,7 @@"7f11b70ed89d4bff87096aa7e7bb0d41191eb46682066f3b2cffa7a326b56330","90494ad4128b975867e33b419fe3d512eef775bfbb011590b55b20106372aba4","987ed3621d335ea8aef704e24e2f2eb4d9558802aff2c8216a230d3ac82aaddd",+ "a0c49b3b1f6ff4eaadd64d57bfd54e7c0a090dc33e7b490d95d913441c5821ea","a0f9d72565b489c4a60f6546b89218ea9efc307b397ac5ea22f3ed4c737f73f1","b73d9f9c93d419d812b39e47160790f8510bcd8564910b9f02aee51e673ad41f","c82b1e1b97e058991bc52287c24a26628d7d66bed409642023a20457e7f15f05",diff --git a/skills/skills.lock.json b/skills/skills.lock.jsonindex cc4e0a9759..4f65a10c0c 100644--- a/skills/skills.lock.json+++ b/skills/skills.lock.json@@ -44,7 +44,7 @@"concept-synthesis/routing-eval.jsonl": "96dbd7d9c1b606e9e06262d0c06282399741e2bccb8eeb7b9ca88c20f44cda0e","context-audit/SKILL.md": "6d786629d40544ddaab4f4e6e333569d270bcb8b581589dc16fb9f8bcb4f6207","context-audit/routing-eval.jsonl": "fb1832e24cc1b04163a74c5cde72bca53050a66246ca902e1a5f40303f52b5ab",- "conventions/agent-operator-protocol.md": "e268fd66b4bb18e6d91115f4869b58f60468ff446931a3a00ee3d784ed022d53",+ "conventions/agent-operator-protocol.md": "3d573138ee60d7c22c87717f4157b7e67db08add5d68c3e4a9fd2c06e5dc9e0b","conventions/brain-first.md": "bc9b5ea553570a711e7f081a41860e1cebffd6de1a10a04ca5e42ccaa8ecb2b2","conventions/brain-routing.md": "57ec4791bcd51ecb778766ab6c007f01776fde6e606e7022096a6b2d81ea4aa1","conventions/calibration.md": "500dc26bd7c8400f50dc4c16fd83f1a588f3e7e68c59050a21fd8a0f69e4d198",@@ -212,7 +212,7 @@"resolve-before-asking/routing-eval.jsonl": "bac1bcf30337f5255ef4ce1a2a8a2b38d58ebcd576503c483190c79ec6e69489","schema-author/SKILL.md": "38efb8b48399a2dc526d7084579aa265b2ab232882605bc2f86f6ba2869619f5","schema-unify/SKILL.md": "36259f1510fd693253535bd203e32db1bfa24aaae7278c7a2e8b7d6859022708",- "setup/SKILL.md": "d5250abf65d7fb822646232ed6a27a09ac4443377065b58182292023c6b3606a",+ "setup/SKILL.md": "a0c49b3b1f6ff4eaadd64d57bfd54e7c0a090dc33e7b490d95d913441c5821ea","signal-detector/SKILL.md": "426a8a3b01a007dd25638e61adef510c18c3d9ce6f1c18ba3d77fdfcd3281d60","skill-autobench/SKILL.md": "29f5760dcfd823c5f7d4fb50a3cf4e36601b1b8125e57d6bf83645a41f97f613","skill-autobench/routing-eval.jsonl": "8d961ed6403b7e2f690948e4c18529d40f26f6f21064befc56d465966b1a9ec0",@@ -226,7 +226,7 @@"skillpack-check/SKILL.md": "0d2d2d201ed72e19b47d7e3743b5bbdfb5c2655d1f34d29447c601fca3908f9e","skillpack-harvest/SKILL.md": "0f86314b58d25b5511809f567c04aedc3fba6fe35ed642ac52d8216ae365b6eb","skillpack-harvest/routing-eval.jsonl": "cb4783288e95af3132b32ecb40a54cffc095f57b36240f96a25c2d2adf5e68c6",- "skills.lock.history.json": "ec17d5a33fe97b37cc436cabe5284082c1ea12ce93bd485da1eaf7c3b4109f12",+ "skills.lock.history.json": "781fc8f8e22bfcf36a173788953f108df91f04aac186700df58cf2b82acdc3a0","smoke-test/SKILL.md": "f5099e1d2ab9dc6827096249e68414f7ae357c29b39fb069a54bb7fb74f414a5","soul-audit/SKILL.md": "7a48e180849f7502d332878c443397f90a3756f45caa94f76bcfcc7c997469c8","storage-manifest/SKILL.md": "1debbefba61007a17cda1525496875d1edfde90642adf3ec031f25a71724807e",diff --git a/src/cli/main.ts b/src/cli/main.tsindex 82c8f12854..59842be0d7 100755--- a/src/cli/main.ts+++ b/src/cli/main.ts@@ -52,6 +52,7 @@ import { printHelp } from './top-help.ts';import { curatedFlagError } from './help/validate.ts';import { cliCommandOf, exitCliError, exitOnRepairFailed, reportInBandFailure, unknownFlagError, usageError, writeCliError, writeCliNotice, writeFatalCliError } from './cli-error.ts';import type { Notice } from '../core/agent-output.ts';+import { migrationsNotice, pendingUpgradeMigrationsNotice } from './migrations-notice.ts';import { opError, opOwnsSource } from '../core/ops/contract.ts';import { PAGE_MAX_BYTES } from '../core/page-size-policy.ts';import { opFlagValue, opParamValue, opStructuredValue } from './op-param-values.ts';@@ -2738,12 +2739,6 @@ async function connectEngine(opts?: EngineConnectOptions): Promise<BrainEngine>return exitOnRepairFailed(() => connectEngineForServe(ENGINE_CONNECT_HOOKS, opts));}-/** A6/D1: the pending-migrations warning as a notice whose fix applies them (stderr; stdout stays the command's). */-function migrationsNotice(why: string): Notice {- return { code: 'migrations_pending', kind: 'safety', why, fix: { argv: ['gbrain', 'apply-migrations', '--yes'], consent: [], actor: 'agent',- requires_exclusive: true, why: 'Applies the pending schema migrations (the same ones every command applies on connect).', verify: { argv: ['gbrain', 'doctor', '--json'] } } };-}-/** Startup after the probe-only connect: migrations, retired-marker cleanup, DB-plane config merge. Mounts: none. */async function completeEngineStartup(engine: BrainEngine, opts: EngineConnectOptions = {}): Promise<void> {const config = SELECTED_CONFIG_BY_ENGINE.get(engine);@@ -2775,6 +2770,9 @@ async function completeEngineStartup(engine: BrainEngine, opts: EngineConnectOptwriteCliNotice(migrationsNotice(`Schema probe failed (unexpected): ${(err as Error).message}`));}+ const pendingUpgrade = await pendingUpgradeMigrationsNotice(engine, dispatchedCommand, VERSION);+ if (pendingUpgrade) writeCliNotice(pendingUpgrade);+// #5628: drop this host's markers of a retired managed epoch before any filesystem guard check. A one-shot read runs no guard check.if (!opts.oneShotRead) try { await (await import('../core/persistence/deactivation.ts')).cleanupRetiredManagedMarkers(engine); } catch { /* status reports pending markers */ }diff --git a/src/cli/migrations-notice.ts b/src/cli/migrations-notice.tsnew file mode 100644index 0000000000..dc65f12f66--- /dev/null+++ b/src/cli/migrations-notice.ts@@ -0,0 +1,30 @@+import type { BrainEngine } from '../core/engine.ts';+import type { Notice } from '../core/agent-output.ts';++/** Commands that run or report the upgrade migrations themselves, so connect adds no pending-migrations notice to them. */+const ORCHESTRATOR_MIGRATION_OWNERS: ReadonlySet<string> = new Set(['apply-migrations', 'post-upgrade', 'upgrade', 'doctor', 'init', 'setup', 'serve']);++/** A6/D1: the pending-migrations warning as a notice whose fix applies them (stderr; stdout stays the command's). */+export function migrationsNotice(why: string): Notice {+ return { code: 'migrations_pending', kind: 'safety', why, fix: { argv: ['gbrain', 'apply-migrations', '--yes'], consent: [], actor: 'agent',+ requires_exclusive: true, why: 'Applies the pending schema migrations (the same ones every command applies on connect).', verify: { argv: ['gbrain', 'doctor', '--json'] } } };+}++/**+ * Upgrade migrations (the orchestrators in src/commands/migrations/) run only from apply-migrations, post-upgrade and+ * setup, never on connect. A reinstall over an older brain (`bun install -g` again) runs neither, so connect says so.+ * Returns null when nothing is pending, the command owns the migrations, or the ledger can't be read.+ */+export async function pendingUpgradeMigrationsNotice(engine: BrainEngine, command: string, version: string): Promise<Notice | null> {+ if (ORCHESTRATOR_MIGRATION_OWNERS.has(command)) return null;+ try {+ const { declinedMigrations, migrationLedgerSummary } = await import('../core/migration-ledger.ts');+ const { loadCompletedMigrations } = await import('../core/preferences.ts');+ if (loadCompletedMigrations().length === 0) return null;+ const summary = migrationLedgerSummary(version, await declinedMigrations(engine));+ const pending = [...summary.pending, ...summary.partial];+ if (pending.length === 0) return null;+ const notice = migrationsNotice(`${pending.length} upgrade migration(s) have not finished on this brain yet (${pending.join(', ')}); the command ran, and gbrain apply-migrations --yes --no-autopilot-install finishes the upgrade.`);+ return { ...notice, fix: { ...notice.fix!, argv: ['gbrain', 'apply-migrations', '--yes', '--no-autopilot-install'] } };+ } catch { return null; }+}diff --git a/src/commands/apply-migrations.ts b/src/commands/apply-migrations.tsindex 866d27d6ce..19793cb5b2 100644--- a/src/commands/apply-migrations.ts+++ b/src/commands/apply-migrations.ts@@ -8,7 +8,7 @@** Invoked from:* - `gbrain upgrade` → runPostUpgrade() tail (Lane A-5)- * - package.json `postinstall` (Lane A-5)+ * - `gbrain setup <harness>` on the brain it just created* - explicit user / host-agent after registering new handlers (Lane C-1)*/@@ -558,7 +558,7 @@ async function applyParsed(cli: ApplyMigrationsArgs, args: string[]): Promise<{const installed = VERSION.replace(/^v/, '').trim() || '0.0.0';const report: RunReport = { doc: { status: 'ok', installed } };- // First-install guard (postinstall hook calls us even on `bun add gbrain`+ // First-install guard (an older release's postinstall calls us even on `bun add gbrain`// before the user has run `gbrain init`). No config = no brain = nothing// to migrate. Exit silently for --yes / --non-interactive so postinstall// stays quiet; mention the init step when invoked interactively.diff --git a/src/commands/doctor/checks/schema-health.ts b/src/commands/doctor/checks/schema-health.tsindex eb4be20f67..546bfe4c6d 100644--- a/src/commands/doctor/checks/schema-health.ts+++ b/src/commands/doctor/checks/schema-health.ts@@ -207,11 +207,10 @@ async function runSchemaVersion(ctx: DoctorContext): Promise<Check[]> {const engine = connectedEngine(ctx);const checks: Check[] = [];- // 6. Schema version — also surfaces the #218 "postinstall silently failed"- // state: if schema_version is 0/missing but the DB connected, migrations- // never ran. That's the same class as a half-migrated install, just from a- // different root cause (Bun blocked our top-level postinstall on global- // install). Message is actionable either way.+ // 6. Schema version — also surfaces the #218 state: if schema_version is+ // 0/missing but the DB connected, migrations never ran. That's the same+ // class as a half-migrated install, just from a different root cause (an+ // interrupted install). Message is actionable either way.progress.heartbeat('schema_version');let schemaVersion = 0;try {diff --git a/src/commands/init-first-run.ts b/src/commands/init-first-run.tsindex f2e9e9aa4c..89921ef776 100644--- a/src/commands/init-first-run.ts+++ b/src/commands/init-first-run.ts@@ -6,15 +6,16 @@* options' argv.** Decisions: `search_mode` (the picker's recommendation and cost matrix),- * `writeback` (recommended `salient`, offered on a personal brain whose- * operator has not answered), `harness_wiring` (the A7 readiness fix) and the+ * `writeback` (in effect `off`, recommended `salient`, offered on a personal brain whose+ * operator has not answered) and the* optional `skills_scaffold` (recommended skills missing from the detected* agent workspace; default skip), then `upkeep` (GBRA-438: the free upkeep* line, a setting in effect whose default `on` needs no answer; it rides a* bundle that has another entry and never opens one alone). Human output renders the same bundle* (`[AGENT]` block without a terminal, `Note` lines on one); it replaces* init's separate writeback ask and skills pointer. Extend- * `buildInitFirstRunNotices` rather than adding a second notice.+ * `buildInitFirstRunNotices` rather than adding another settings notice; the+ * one separate notice is `harness_wiring`, an install step the agent does.*/import { cliRenderContext, renderNotice, shellQuote, type Decision, type Notice } from '../core/agent-output.ts';import { loadConfig, type GBrainConfig } from '../core/config.ts';@@ -73,18 +74,29 @@ function searchModeDecision(applied: { mode: SearchMode; reason: string }): Deci};}-function harnessWiringDecision(config: GBrainConfig, surface?: McpSurface): Decision | null {+/**+ * Connecting gbrain to the agent is an install step, never a setting waiting+ * for the user's OK (Garry's G, GST-2719): its own notice, so an agent that+ * relays the settings has already connected memory.+ */+function harnessWiringNotice(config: GBrainConfig, surface?: McpSurface): Notice | null {const entry = configReadiness(config, { transport: 'cli', ...(surface ? { surface } : {}) }).entries.find(e => e.capability === 'harness_wiring');if (!entry?.fix || entry.state === 'ok') return null;+ const fix = entry.fix;+ const registration = !!fix.argv && fix.actor === 'agent' && fix.consent.length === 1 && fix.consent[0] === 'persistent_install';+ if (!registration) {+ return {+ code: 'harness_wiring',+ kind: 'info',+ why: `gbrain is not connected to an agent here, and this step is not a command the agent runs by itself; say so in the reply that reports the install, without waiting on it. ${fix.user_message ?? ''} ${fix.why ?? ''}`.trim(),+ fix,+ };+ }return {- id: 'harness_wiring',- question: entry.fix.user_message ?? entry.why,- options: [- { id: 'wire', label: entry.fix.why, ...(entry.fix.argv ? { argv: entry.fix.argv } : {}) },- { id: 'skip', label: 'Do not register gbrain with an agent harness now.' },- ],- default: entry.fix.argv ? 'wire' : 'skip',- default_reason: entry.why,+ code: 'harness_wiring',+ kind: 'info',+ why: 'Connect gbrain to the agent now, as part of this install: it is an install step, not a setting, so do it before reporting the install. The fix names the command for this host.',+ fix: { ...fix, actor: 'agent', consent: [], user_message: undefined },};}@@ -99,8 +111,8 @@ function writebackDecision(): Decision {{ id: 'all', label: 'Every direct factual statement (more low-value facts, more extraction spend)', argv: set('all') },{ id: 'off', label: 'Save only what the user explicitly asks to remember (records the answer)', argv: set('off') },],- default: 'salient',- default_reason: 'Recommended for a personal brain: the brain learns what the user tells their agents. It is opt-in, so it applies only when the user accepts the defaults or picks it.',+ default: 'off',+ default_reason: 'In effect now: agents save only what the user asks them to remember. salient is recommended for a personal brain; it is opt-in, so it turns on only when the user picks it.',};}@@ -123,23 +135,29 @@ export function buildInitFirstRunNotices(inputs: InitFirstRunInputs): Notice[] {const decisions: Decision[] = [];if (inputs.searchMode) decisions.push(searchModeDecision(inputs.searchMode));if (inputs.writeback) decisions.push(writebackDecision());- if (inputs.config) {- const wiring = harnessWiringDecision(inputs.config, inputs.surface);- if (wiring) decisions.push(wiring);- }if (inputs.skillsScaffold?.missing.length) decisions.push(skillsScaffoldDecision(inputs.skillsScaffold));- if (decisions.length === 0) return [];+ const wiring = inputs.config ? harnessWiringNotice(inputs.config, inputs.surface) : null;+ if (decisions.length === 0 && !(wiring && inputs.upkeep)) return wiring ? [wiring] : [];if (inputs.upkeep) decisions.push(upkeepDecision(inputs.upkeep.embedding));- const defaults = decisions.map(d => `${d.id}: ${d.default}`).join('; ');- return [{+ const searchMode = decisions.find(d => d.id === 'search_mode');+ const upkeep = decisions.find(d => d.id === 'upkeep');+ const inEffect = [+ ...(searchMode ? [`search mode ${searchMode.default}`] : []),+ ...(decisions.some(d => d.id === 'writeback') ? [WRITEBACK_IN_EFFECT] : []),+ ];+ return [...(wiring ? [wiring] : []), {code: 'first_run_decisions',kind: 'ask',- why: 'The brain is ready. These settings were applied with defaults or need the user\'s choice; none blocks using the brain.',- user_message: `gbrain is installed. Reply 'defaults' to keep the recommended settings (${defaults}), or tell me what to change.`,+ why: 'The brain is ready and these first-run settings are in effect as listed; none blocks memory. '+ + 'Relay them once, in the reply that reports the install, as the current settings and how to change them; do not hold the install open or end it waiting on an answer. '+ + 'When the user picks an option, run its command. Nothing paid turns on from these settings without a key the user supplied.',+ user_message: `gbrain is installed.${inEffect.length ? ` In effect: ${inEffect.join('; ')}.` : ''}${upkeep ? ` ${upkeep.question}` : ''}${searchMode ? ` ${costMatrixSentence()}` : ''} Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.`,decisions,}];}+const WRITEBACK_IN_EFFECT = 'agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance)';+/*** `gbrain setup <harness>`'s form of init's bundle (read from `init --json`).* Setup has already wired the harness, so `harness_wiring` is dropped, and@@ -159,7 +177,7 @@ export function setupFirstRunNotices(initNotices: readonly unknown[], harness: sconst upkeep = decisions.find(d => d.id === 'upkeep');const inEffect = [...(searchMode ? [`search mode ${searchMode.default}`] : []),- ...(decisions.some(d => d.id === 'writeback') ? ['agents save only what you ask them to remember, until you turn on automatic saving (gbrain recommends salient: durable facts you state, saved with provenance)'] : []),+ ...(decisions.some(d => d.id === 'writeback') ? [WRITEBACK_IN_EFFECT] : []),];if (inEffect.length === 0 && !upkeep) return [];const reportBack = opts.reportBackdiff --git a/src/commands/init.ts b/src/commands/init.tsindex 347078c793..e78a32922e 100644--- a/src/commands/init.ts+++ b/src/commands/init.ts@@ -108,7 +108,7 @@ async function runInitBranches(args: string[]) {// Schema-only path: apply initSchema against the already-configured engine// without ever calling saveConfig. Used by apply-migrations, the stopgap- // script, and the postinstall hook. Bare `gbrain init` defaults to PGLite+ // script, and older releases' postinstall hook. Bare `gbrain init` defaults to PGLite// and overwrites any existing Postgres config — we must never take that// branch from a migration orchestrator.//diff --git a/src/commands/upgrade.ts b/src/commands/upgrade.tsindex 5057d6ea1b..6221a521b6 100644--- a/src/commands/upgrade.ts+++ b/src/commands/upgrade.ts@@ -59,7 +59,7 @@ export async function runUpgrade(args: string[], opts: { targetVersion?: stringconst swapOnly = args.includes('--swap-only');const noAutopilotInstall = args.includes('--no-autopilot-install') || process.env.GBRAIN_NO_AUTOPILOT_INSTALL === '1';const checkBunFloor = !args.includes('--no-bun-floor-check');- // #5693: post-upgrade owns migrations, so package postinstall skips them.+ // #5693: post-upgrade owns migrations. gbrain ships no postinstall now; the flag still tells an older release's postinstall to skip them.const upgradeEnv = { ...process.env, GBRAIN_UPGRADE_OWNS_MIGRATIONS: '1', ...(noAutopilotInstall ? { GBRAIN_NO_AUTOPILOT_INSTALL: '1' } : {}) };const json = jsonRequested(args);diff --git a/src/core/cli-flag-registry.generated.ts b/src/core/cli-flag-registry.generated.tsindex a0c04c75fb..7d26c4c169 100644--- a/src/core/cli-flag-registry.generated.ts+++ b/src/core/cli-flag-registry.generated.ts@@ -98,7 +98,7 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {'orphans': ['--accept-pending', '--all', '--as', '--background', '--brain', '--count', '--cursor', '--explain', '--follow', '--force', '--help', '--include-pseudo', '--json', '--limit', '--mode', '--no-accept-pending', '--progress-interval', '--progress-json', '--quiet', '--room', '--source', '--timeout', '--timings', '--wait'],'pages': ['--brain', '--dry-run', '--force', '--help', '--json', '--limit', '--name-only', '--older-than', '--quiet', '--retry-parked', '--show-toplevel', '--source', '--source-id', '--state', '--verify', '--yes'],'pglite-repair': ['--brain', '--break-lock', '--dry-run', '--expect', '--help', '--http', '--json', '--legacy-lock', '--path', '--probe', '--source', '--vectors', '--yes'],- 'post-upgrade': ['--accept-reviewed-inventory', '--acknowledge-no-backup', '--admin-intent', '--all', '--all-applied', '--apply', '--apply-clean-hunks', '--backend', '--backup-confirmed', '--brain', '--catch-up', '--changed', '--channel', '--check', '--check-only', '--client', '--concurrency', '--confirm-quiesced', '--confirm-relocated-root', '--content-root', '--cost-estimate', '--embedding-dimensions', '--embedding-model', '--exit-code', '--expand', '--expect', '--expected-epoch', '--expected-state', '--explain', '--export-db-only', '--export-source', '--ff-only', '--force', '--force-all', '--force-orchestrator', '--force-retry', '--force-schema', '--format', '--held', '--help', '--host-dir', '--id', '--images', '--inject-bootstrap', '--inline', '--install', '--instructions-only', '--interval', '--is-ancestor', '--json', '--limit', '--list', '--manifest', '--markdown', '--max-rss', '--max-usd', '--may-act-for', '--member', '--migrate-only', '--migration', '--mode', '--multimodal', '--name', '--name-only', '--no-autopilot-install', '--no-bun-floor-check', '--no-embed', '--no-expand', '--no-inject', '--no-restart', '--no-worker', '--non-interactive', '--now', '--once', '--only', '--oversized', '--path', '--pause', '--phase', '--prefix', '--quiet', '--readers', '--reads-unscoped', '--reason', '--refs', '--remediation-plan', '--repo', '--require-db', '--restart-only', '--resume', '--retry-global', '--scope', '--search-mode', '--segmented', '--self-transfer', '--skills-dir', '--skip-verify', '--slug', '--slugs-file', '--source', '--stale', '--statement-timeout', '--status', '--stop-mcp', '--swap-only', '--synopsis', '--tags', '--target', '--token', '--uninstall', '--user', '--vectors', '--verify', '--version', '--workers', '--yes'],+ 'post-upgrade': ['--accept-reviewed-inventory', '--acknowledge-no-backup', '--admin-intent', '--all', '--all-applied', '--apply', '--apply-clean-hunks', '--backend', '--backup-confirmed', '--brain', '--catch-up', '--changed', '--channel', '--check', '--check-only', '--client', '--concurrency', '--confirm-quiesced', '--confirm-relocated-root', '--content-root', '--cost-estimate', '--embedding-dimensions', '--embedding-model', '--exit-code', '--expand', '--expect', '--expected-epoch', '--expected-state', '--explain', '--export-db-only', '--export-source', '--ff-only', '--force', '--force-all', '--force-orchestrator', '--force-retry', '--force-schema', '--format', '--held', '--help', '--host-dir', '--id', '--images', '--inject-bootstrap', '--inline', '--install', '--instructions-only', '--interval', '--is-ancestor', '--json', '--limit', '--list', '--manifest', '--markdown', '--max-rss', '--max-usd', '--may-act-for', '--member', '--migrate-only', '--migration', '--mode', '--multimodal', '--name', '--name-only', '--no-autopilot-install', '--no-bun-floor-check', '--no-embed', '--no-expand', '--no-inject', '--no-restart', '--no-worker', '--non-interactive', '--now', '--once', '--only', '--oversized', '--path', '--pause', '--phase', '--prefix', '--quiet', '--readers', '--reads-unscoped', '--reason', '--refs', '--remediation-plan', '--repo', '--require-db', '--restart-only', '--resume', '--retry-global', '--scope', '--segmented', '--self-transfer', '--skills-dir', '--skip-verify', '--slug', '--slugs-file', '--source', '--stale', '--statement-timeout', '--status', '--stop-mcp', '--swap-only', '--synopsis', '--tags', '--target', '--token', '--uninstall', '--user', '--vectors', '--verify', '--version', '--workers', '--yes'],'pricing': ['--brain', '--help', '--input', '--json', '--max-cost', '--max-runtime', '--output', '--rate', '--source'],'projections': ['--advertise', '--brain', '--dry-run', '--enable-dcr', '--help', '--http', '--images', '--install', '--json', '--limit', '--now', '--only', '--port', '--public-url', '--remove', '--source', '--stale', '--status', '--surface', '--user'],'protocol': ['--access', '--add', '--all', '--allowed-operations', '--as', '--asof', '--body', '--bound-slug-prefixes', '--brain', '--card', '--client', '--cursor', '--date', '--dated-since', '--days', '--entities', '--expected-revision', '--federated-read', '--follow', '--from-index', '--full', '--fuzzy', '--group-by', '--help', '--http', '--id', '--include', '--include-deleted', '--json', '--kind', '--limit', '--max-usd', '--model', '--multimodal', '--no-autopilot-install', '--of', '--only', '--page', '--params', '--patch', '--path', '--phase', '--prefer', '--privacy-url', '--provenance', '--purge', '--recent', '--refresh-operations', '--row', '--scopes', '--session', '--since', '--slugs', '--source', '--sources', '--stale', '--surface', '--synthesize', '--target', '--terms-url', '--to', '--token', '--updated-after', '--url', '--yes'],@@ -141,7 +141,7 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {'think': ['--anchor', '--brain', '--calibration-holder', '--help', '--images', '--json', '--mcp-only', '--model', '--only', '--reference-date', '--request-id', '--rounds', '--save', '--since', '--source', '--source-id', '--stale', '--take', '--until', '--with-calibration'],'transcripts': ['--accept-pending', '--all', '--all-discovery', '--apply', '--as', '--background', '--brain', '--days', '--dry-run', '--embed', '--explain', '--facts', '--follow', '--format', '--full', '--help', '--include-self', '--json', '--limit', '--max-bytes', '--max-cost-usd', '--no-accept-pending', '--only', '--progress-interval', '--progress-json', '--purge', '--quiet', '--room', '--since', '--source', '--source-id', '--timeout', '--timings', '--wait'],'trust': ['--accept-all', '--accept-pending', '--all', '--as', '--background', '--batch-size', '--brain', '--break-lock', '--db-url', '--dry-run', '--expect', '--explain', '--follow', '--from', '--help', '--http', '--json', '--kind', '--label-lowerings', '--legacy-lock', '--no-accept-pending', '--only', '--path', '--probe', '--progress-interval', '--progress-json', '--quiet', '--reason', '--reason-family', '--relower', '--remove', '--repair-unknown-markers', '--resume', '--room', '--since', '--slug', '--source', '--source-id', '--timeout', '--timings', '--undo', '--uri-prefix', '--version', '--wait', '--yes'],- 'upgrade': ['--accept-reviewed-inventory', '--acknowledge-no-backup', '--admin-intent', '--all', '--all-applied', '--apply', '--apply-clean-hunks', '--backend', '--backup-confirmed', '--brain', '--catch-up', '--changed', '--channel', '--check', '--check-downgrade', '--check-only', '--client', '--concurrency', '--confirm-quiesced', '--confirm-relocated-root', '--content-root', '--cost-estimate', '--dry-run', '--embedding-dimensions', '--embedding-model', '--exit-code', '--expand', '--expect', '--expected-epoch', '--expected-state', '--explain', '--export-db-only', '--export-source', '--ff-only', '--force', '--force-all', '--force-orchestrator', '--force-retry', '--force-schema', '--format', '--held', '--help', '--host-dir', '--id', '--images', '--inject-bootstrap', '--inline', '--install', '--instructions-only', '--interval', '--is-ancestor', '--json', '--limit', '--list', '--manifest', '--markdown', '--max-rss', '--max-usd', '--may-act-for', '--member', '--migrate-only', '--migration', '--mode', '--multimodal', '--name', '--name-only', '--no-autopilot-install', '--no-bun-floor-check', '--no-embed', '--no-expand', '--no-inject', '--no-restart', '--no-worker', '--non-interactive', '--now', '--once', '--only', '--oversized', '--path', '--pause', '--phase', '--prefix', '--quiet', '--readers', '--reads-unscoped', '--reason', '--refs', '--remediation-plan', '--repo', '--require-db', '--restart-only', '--resume', '--retry-global', '--scope', '--search-mode', '--segmented', '--self-transfer', '--skills-dir', '--skip-verify', '--slug', '--slugs-file', '--source', '--stale', '--statement-timeout', '--status', '--stop-mcp', '--swap-only', '--synopsis', '--tags', '--target', '--token', '--uninstall', '--user', '--vectors', '--verify', '--version', '--workers', '--yes'],+ 'upgrade': ['--accept-reviewed-inventory', '--acknowledge-no-backup', '--admin-intent', '--all', '--all-applied', '--apply', '--apply-clean-hunks', '--backend', '--backup-confirmed', '--brain', '--catch-up', '--changed', '--channel', '--check', '--check-downgrade', '--check-only', '--client', '--concurrency', '--confirm-quiesced', '--confirm-relocated-root', '--content-root', '--cost-estimate', '--dry-run', '--embedding-dimensions', '--embedding-model', '--exit-code', '--expand', '--expect', '--expected-epoch', '--expected-state', '--explain', '--export-db-only', '--export-source', '--ff-only', '--force', '--force-all', '--force-orchestrator', '--force-retry', '--force-schema', '--format', '--held', '--help', '--host-dir', '--id', '--images', '--inject-bootstrap', '--inline', '--install', '--instructions-only', '--interval', '--is-ancestor', '--json', '--limit', '--list', '--manifest', '--markdown', '--max-rss', '--max-usd', '--may-act-for', '--member', '--migrate-only', '--migration', '--mode', '--multimodal', '--name', '--name-only', '--no-autopilot-install', '--no-bun-floor-check', '--no-embed', '--no-expand', '--no-inject', '--no-restart', '--no-worker', '--non-interactive', '--now', '--once', '--only', '--oversized', '--path', '--pause', '--phase', '--prefix', '--quiet', '--readers', '--reads-unscoped', '--reason', '--refs', '--remediation-plan', '--repo', '--require-db', '--restart-only', '--resume', '--retry-global', '--scope', '--segmented', '--self-transfer', '--skills-dir', '--skip-verify', '--slug', '--slugs-file', '--source', '--stale', '--statement-timeout', '--status', '--stop-mcp', '--swap-only', '--synopsis', '--tags', '--target', '--token', '--uninstall', '--user', '--vectors', '--verify', '--version', '--workers', '--yes'],'waiting': ['--all', '--as-of', '--brain', '--dry-run', '--fail-fast', '--help', '--json', '--note', '--source', '--stale-ok', '--status', '--tools-json', '--top', '--type'],'wakeshift': ['--apply', '--brain', '--conversation-id', '--db-url', '--expect', '--harness', '--help', '--json', '--key-stdin', '--max-cost', '--max-usd', '--name', '--non-interactive', '--path', '--privacy-url', '--probe', '--session-key', '--source', '--status', '--terms-url', '--trust', '--url', '--yes'],'watch': ['--brain', '--help', '--json', '--max-pages', '--min-confidence', '--source', '--window-turns'],diff --git a/src/core/error-registry.ts b/src/core/error-registry.tsindex 0d9f5aa566..8f34550999 100644--- a/src/core/error-registry.ts+++ b/src/core/error-registry.ts@@ -1046,7 +1046,8 @@ export const NOTICE_CODES = {room_above_level: { kind: 'safety', summary: 'The answer goes into a shared room (a harness declared it with X-Gbrain-Room, _meta.room or a room argument) and some items carry room_access readable false or unknown: the room could not have read them itself. Use them to do the work, keep them out of the reply unless the ask needs them, offer the rest in a private chat; never refuse the work. docs/guides/rooms.md' },room_hints_unavailable: { kind: 'degraded', summary: 'A room was declared but its marks could not be computed (reason: invalid, not_permitted, unknown_principal, unbound, mark_failed, deadline, op_not_covered): the answer is complete and every item is marked unknown, so treat all of it as above the room. docs/guides/rooms.md#when-marks-are-unavailable' },room_conflict: { kind: 'safety', summary: 'The room argument named a different room than the harness declared (X-Gbrain-Room or _meta.room); the answer was marked for everyone either names, because an argument can only add people. docs/guides/rooms.md#channels' },- first_run_decisions: { kind: 'ask', summary: 'init finished (or a stdio MCP session started on a brain with open decisions); the first-run decisions (search mode, writeback, harness wiring, skills) carry defaults the user may change. The one muteable ask.' },+ first_run_decisions: { kind: 'ask', summary: 'init finished (or a stdio MCP session started on a brain with open decisions); the first-run settings (search mode, writeback, skills, upkeep) are in effect as listed and the user may change them later: relay them once in the reply that reports the install, never hold the install open on them. The one muteable ask.' },+ harness_wiring: { kind: 'info', summary: 'init finished and no agent harness is registered yet: connecting gbrain to the agent is an install step the agent does now (`gbrain setup claude-code|codex`, or registering the stdio serve command in another host), not a setting that waits for the user.' },first_run_decisions_muted: { kind: 'info', summary: 'First-run decisions are still open, but the user muted them; the fix shows them again (`gbrain notices unmute first_run_decisions`).' },migrations_pending: { kind: 'safety', summary: 'Schema migrations are pending or failed to apply on this brain.' },unscoped_multi_user_token: { kind: 'safety', summary: 'An install route (gbrain setup openclaw|hermes|grok-bot|muse, setup claude-code with a chat-channel plugin, mcp grant, connect, skillpack scaffold for a bot harness, auth create, auth register-client) set up access that reads the same pages whoever talks to a likely multi-user agent: a bot harness, or a grant that reads chat from 2+ channels. Several people talking to that agent may get each other\'s messages. The notice names the fixes (a one-source grant, gbrain sources unfederate, visibility: private, a credential bound to each person, or one shared agent with may_act_for and a per-request audience); a credential holding may_act_for is not flagged; doctor `unscoped_multi_user_token` reports the same detection. docs/mcp/ADMIN.md#one-token-several-people' },diff --git a/src/core/npm-squat-check.ts b/src/core/npm-squat-check.tsindex 0208f72c64..640ce52cbf 100644--- a/src/core/npm-squat-check.ts+++ b/src/core/npm-squat-check.ts@@ -62,7 +62,7 @@ const REAL_REPO_MARKER = 'garrytan/gbrain';/** The documented install command (INSTALL_PIN, the one install ref in core/install-ref.ts). */const INSTALL_ARGV = ['bun', 'install', '-g', INSTALL_PIN];-/** #218 recovery: a Bun global install can skip the postinstall that applies schema migrations. */+/** #218 recovery: a fresh install runs no migrations; this applies them. */const SCHEMA_RECOVERY_ARGV = ['gbrain', 'apply-migrations', '--yes', '--no-autopilot-install'];/** The documented install/remediation path, reused in doctor output. */@@ -246,7 +246,7 @@ function squatFix(foreign: ClassifiedGbrainBinary, realElsewhere: boolean, opts:then: {argv: SCHEMA_RECOVERY_ARGV, consent: [], actor: 'agent', requires_exclusive: false,verify: { argv: ['gbrain', 'doctor', '--json'] }, docs: 'README.md#install',- why: 'A Bun global install can skip the postinstall that applies schema migrations (#218). This applies them and exits 0 only when the schema is at head; exit 1 with migrations_pending means run gbrain doctor --json and relay what it reports.',+ why: 'The install itself runs no migrations (#218). This applies them and exits 0 only when the schema is at head; exit 1 with migrations_pending means run gbrain doctor --json and relay what it reports.',},};return {diff --git a/src/core/search/mode-advice.ts b/src/core/search/mode-advice.tsindex 036c8fd1b6..852e4ce599 100644--- a/src/core/search/mode-advice.ts+++ b/src/core/search/mode-advice.ts@@ -109,9 +109,8 @@ export function agentBannerLines(applied: SearchMode, reason: string): string[]'═══════════════════════════════════════════════════════════════','',...agentBlock({- ask: 'Which search mode should this brain use: conservative, balanced or tokenmax?',- why: `The default above (${applied}) was auto-selected from the Reason line. Before continuing, show this matrix to your operator and ask which mode they want; INSTALL_FOR_AGENTS.md Step 3.5 has the full protocol.`,- next: 'ask_user: if the operator picks differently, run `gbrain config set search.mode <conservative|balanced|tokenmax>` (or `gbrain init --search-mode <mode>` at install time).',+ why: `Search mode ${applied} is in effect, auto-selected from the Reason line. Tell the operator the mode in effect and this matrix in the reply that reports the install; nothing waits on an answer (INSTALL_FOR_AGENTS.md Step 3.5).`,+ next: 'If the operator picks another mode, run `gbrain config set search.mode <conservative|balanced|tokenmax>`.',verify: 'gbrain search modes',}).trimEnd().split('\n'),'',diff --git a/test/agent-journey.serial.test.ts b/test/agent-journey.serial.test.tsindex 3b6f0945bf..8ff3fc8917 100644--- a/test/agent-journey.serial.test.ts+++ b/test/agent-journey.serial.test.ts@@ -112,8 +112,10 @@ for (const stdin of ['devnull', 'silent'] as StdinMode[]) {expect(bundles).toHaveLength(1);const bundle = bundles[0]!;expect(bundle).toMatchObject({ kind: 'ask', contract_version: 1 });- expect(bundle.user_message).toContain("Reply 'defaults'");- expect(bundle.decisions.map((d: { id: string }) => d.id)).toEqual(expect.arrayContaining(['search_mode', 'harness_wiring']));+ expect(bundle.user_message).toContain('Nothing needs an answer now');+ expect(bundle.decisions.map((d: { id: string }) => d.id)).toContain('search_mode');+ expect(bundle.decisions.map((d: { id: string }) => d.id)).not.toContain('harness_wiring');+ expect((doc.notices as Array<Record<string, any>>).find(n => n.code === 'harness_wiring')).toMatchObject({ kind: 'info', fix: { actor: 'user', next: 'report' } });for (const d of bundle.decisions) {expect(d.options.map((o: { id: string }) => o.id), `${d.id}: default is an option`).toContain(d.default);expect(d.default_reason, `${d.id}: default_reason`).toBeTruthy();diff --git a/test/ambient-writeback-lifecycle.serial.test.ts b/test/ambient-writeback-lifecycle.serial.test.tsindex 53c298519d..2091cdbc31 100644--- a/test/ambient-writeback-lifecycle.serial.test.ts+++ b/test/ambient-writeback-lifecycle.serial.test.ts@@ -142,7 +142,7 @@ describe('ambient writeback — hermetic 5-step lifecycle', () => {// G5: the ask is the `writeback` decision in init's one first-run bundle ([AGENT] block).expect(initOut).toContain('(id: writeback)');expect(initOut).toContain('(run: gbrain config set memory.auto_writeback salient)');- expect(initOut).toContain('default: salient');+ expect(initOut).toContain('default: off');// The ask fires ONCE: a second init pass over the same brain stays quiet// (sentinel stamped) — checked implicitly by step 2's config set insteaddiff --git a/test/apply-migrations-schema-exit.test.ts b/test/apply-migrations-schema-exit.test.tsindex 597298ad6b..8ddad12b33 100644--- a/test/apply-migrations-schema-exit.test.ts+++ b/test/apply-migrations-schema-exit.test.ts@@ -2,7 +2,7 @@* #6089 exit matrix off Postgres. PGLite keeps skipping the pre-flight (#1100)* and checks the schema version in-process after the orchestrators released* the datastore; an unreachable Postgres stays non-fatal (apply-migrations,- * in-process `gbrain post-upgrade`, package postinstall) and says so with the+ * in-process `gbrain post-upgrade`) and says so with the* GBRAIN_DB_ACCESS marker. The Postgres cases live in* test/e2e/apply-migrations-schema-exit.test.ts.*/@@ -129,21 +129,4 @@ describe('apply-migrations with Postgres unreachable stays non-fatal and says soexpect(parseDocument(r.stdout).apply_migrations).toEqual({ exit_code: 0 });}, 180_000);- test('package postinstall runs apply-migrations, which exits 0, so no recovery hint is printed', async () => {- const home = postgresHome();- const driver = writeSchemaDriver(home, { migrations: ['noop'], args: [], entry: 'argv' });- const bin = join(home, 'bin');- mkdirSync(bin);- writeFileSync(join(bin, 'gbrain'), `#!/bin/sh\nexec ${JSON.stringify(process.execPath)} --no-env-file ${JSON.stringify(driver)} "$@"\n`, { mode: 0o755 });- const r = spawnSync(process.execPath, ['--no-env-file', join(REPO, 'scripts/postinstall.ts')], {- cwd: home,- env: { HOME: home, GBRAIN_HOME: home, PATH: `${bin}:/usr/bin:/bin`, GBRAIN_SKIP_REFERENCE_SWEEP: '1' },- encoding: 'utf8', timeout: 120_000,- });- const out = r.stdout + r.stderr;- expect(r.status, out).toBe(0);- expect(readFileSync(join(home, 'orchestrator.log'), 'utf8')).toBe('ran noop\n');- expect(r.stderr).toMatch(/^GBRAIN_DB_ACCESS \w+$/m);- expect(out).not.toContain('postinstall skipped');- }, 120_000);});diff --git a/test/cli-json-guard.test.ts b/test/cli-json-guard.test.tsindex f86d5846ed..2244d33f03 100644--- a/test/cli-json-guard.test.ts+++ b/test/cli-json-guard.test.ts@@ -148,7 +148,7 @@ describe('D2 command migrations: init', () => {expect(doc).toMatchObject({ status: 'success', engine: 'pglite', contract_version: 1 });const bundle = (doc.notices as Array<Record<string, any>>).find(n => n.code === 'first_run_decisions')!;expect(bundle).toMatchObject({ kind: 'ask', contract_version: 1 });- expect(bundle.user_message).toContain("Reply 'defaults'");+ expect(bundle.user_message).toContain('Nothing needs an answer now');const searchMode = bundle.decisions.find((d: { id: string }) => d.id === 'search_mode');expect(searchMode.options.map((o: { id: string }) => o.id)).toEqual(['conservative', 'balanced', 'tokenmax']);expect(searchMode.options[0].argv).toEqual(['gbrain', 'config', 'set', 'search.mode', 'conservative']);diff --git a/test/fixtures/agent-contract/v1/journey/init-first-run.json b/test/fixtures/agent-contract/v1/journey/init-first-run.jsonindex bf4260d88a..f7ee0037ce 100644--- a/test/fixtures/agent-contract/v1/journey/init-first-run.json+++ b/test/fixtures/agent-contract/v1/journey/init-first-run.json@@ -25,11 +25,27 @@"root_identity": "{{ROOT_IDENTITY}}"},"notices": [+ {+ "code": "harness_wiring",+ "kind": "info",+ "why": "gbrain is not connected to an agent here, and this step is not a command the agent runs by itself; say so in the reply that reports the install, without waiting on it. Which agent app should get gbrain memory? The install guide has a one-line command for each. For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "fix": {+ "consent": [+ "persistent_install"+ ],+ "actor": "user",+ "why": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw).",+ "user_message": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",+ "docs": "{{DOCS_BASE}}/docs/protocol/MEMORY_VERBS_v1.md#install-the-4-command-quickstart",+ "requires_exclusive": false+ },+ "contract_version": 1+ },{"code": "first_run_decisions","kind": "ask",- "why": "The brain is ready. These settings were applied with defaults or need the user's choice; none blocks using the brain.",- "user_message": "gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: conservative; writeback: salient; harness_wiring: skip; upkeep: on), or tell me what to change.",+ "why": "The brain is ready and these first-run settings are in effect as listed; none blocks memory. Relay them once, in the reply that reports the install, as the current settings and how to change them; do not hold the install open or end it waiting on an answer. When the user picks an option, run its command. Nothing paid turns on from these settings without a key the user supplied.",+ "user_message": "gbrain is installed. In effect: search mode conservative; agents save only what you ask them to remember, until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). Upkeep: free upkeep runs on its own while your agent's gbrain session is open. Nothing is deleted or paid for without you. Turn off: gbrain config set maintenance.auto false. Optional schedule: gbrain maintain --schedule. Estimated downstream input cost of the retrieved payload at 10K queries/month (Haiku 5.5 / Sonnet 5.5 / Opus 5.5): conservative $4 / $80 / $160, balanced $10 / $200 / $400, tokenmax $20 / $400 / $800 per month. Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.","decisions": [{"id": "search_mode",@@ -110,24 +126,8 @@]}],- "default": "salient",- "default_reason": "Recommended for a personal brain: the brain learns what the user tells their agents. It is opt-in, so it applies only when the user accepts the defaults or picks it."- },- {- "id": "harness_wiring",- "question": "Which agent app should get gbrain memory? The install guide has a one-line command for each.",- "options": [- {- "id": "wire",- "label": "For Claude Code or Codex, run `gbrain setup claude-code` or `gbrain setup codex` (it registers serve behind gbrain's launcher, so the session directory's bunfig.toml and .env never load). For any other host, register `<absolute path to gbrain> serve --surface starter --advertise verbs` as a stdio MCP server in your agent host; the install section lists the exact command per harness (Claude Code, Codex, Grok Build, opencode, OpenClaw)."- },- {- "id": "skip",- "label": "Do not register gbrain with an agent harness now."- }- ],- "default": "skip",- "default_reason": "No agent harness was detected."+ "default": "off",+ "default_reason": "In effect now: agents save only what the user asks them to remember. salient is recommended for a personal brain; it is opt-in, so it turns on only when the user picks it."},{"id": "upkeep",diff --git a/test/init-first-run.test.ts b/test/init-first-run.test.tsindex dc34ed9687..b01c5dd3f5 100644--- a/test/init-first-run.test.ts+++ b/test/init-first-run.test.ts@@ -1,31 +1,70 @@/*** init's first-run decision bundle (agent operator wave G5): ONE `kind: ask`- * notice whose decisions carry search mode, writeback (recommended salient),- * harness wiring and the optional skills scaffold, with one user_message- * offering 'defaults'. Pure: no engine, no filesystem.+ * notice whose decisions carry search mode, writeback (in effect off,+ * recommended salient) and the optional skills scaffold as settings in+ * effect, plus a separate `harness_wiring` install step. Pure: no engine, no+ * filesystem.*/import { describe, expect, test } from 'bun:test';import { buildInitFirstRunNotices, setupFirstRunNotices, upkeepLine } from '../src/commands/init-first-run.ts';import { costMatrixSentence } from '../src/core/search/mode-advice.ts';+import { withEnv } from './helpers/with-env.ts';const searchMode = { mode: 'balanced' as const, reason: 'Balanced default for a new brain.' };const scaffold = { missing: ['cold-start', 'book-mirror'], argv: ['gbrain', 'skillpack', 'scaffold', 'cold-start', 'book-mirror'] };describe('buildInitFirstRunNotices', () => {- test('one ask notice: search_mode, writeback, skills_scaffold in order, one defaults relay', () => {+ test('one notice of settings in effect: search_mode, writeback, skills_scaffold in order, relayed without waiting for an answer', () => {const notices = buildInitFirstRunNotices({ searchMode, writeback: true, skillsScaffold: scaffold });expect(notices).toHaveLength(1);const [bundle] = notices;expect(bundle).toMatchObject({ code: 'first_run_decisions', kind: 'ask' });expect(bundle.decisions!.map(d => d.id)).toEqual(['search_mode', 'writeback', 'skills_scaffold']);expect(bundle.user_message).toBe(- "gbrain is installed. Reply 'defaults' to keep the recommended settings (search_mode: balanced; writeback: salient; skills_scaffold: skip), or tell me what to change.",+ 'gbrain is installed. In effect: search mode balanced; agents save only what you ask them to remember, until you turn on automatic saving '+ + '(salient is recommended: durable facts you state, saved with provenance). '+ + `${costMatrixSentence()} Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.`,);+ expect(bundle.user_message).not.toContain("Reply 'defaults'");+ expect(bundle.why).toContain('do not hold the install open');+ });++ test('connecting the agent is its own install step, never a setting in the ask (Garry G, GST-2719)', () => {+ const config = { engine: 'pglite', database_path: '/tmp/gbrain-example.pglite' } as never;+ const notices = buildInitFirstRunNotices({ searchMode, writeback: true, config });+ expect(notices.map(n => n.code)).toEqual(['harness_wiring', 'first_run_decisions']);+ expect(notices[1].decisions!.map(d => d.id)).not.toContain('harness_wiring');+ const [wiring] = notices;+ expect(wiring.kind).toBe('info');+ });++ test('with no agent detected, the wiring fix stays the user step readiness gave, and the why does not promise a command', async () => {+ const markers = { CLAUDECODE: undefined, CLAUDE_CODE_ENTRYPOINT: undefined, CODEX_SANDBOX: undefined, CODEX_CI: undefined, OPENCODE: undefined, OPENCODE_PID: undefined };+ await withEnv(markers, async () => {+ const config = { engine: 'pglite', database_path: '/tmp/gbrain-example.pglite' } as never;+ const [wiring] = buildInitFirstRunNotices({ searchMode, writeback: true, config });+ expect(wiring.code).toBe('harness_wiring');+ expect(wiring.fix!.argv).toBeUndefined();+ expect(wiring.fix!.actor).toBe('user');+ expect(wiring.fix!.consent).toEqual(['persistent_install']);+ expect(wiring.fix!.user_message).toBeTruthy();+ expect(wiring.why).not.toContain('The fix names the command');+ expect(wiring.why).toContain(wiring.fix!.user_message!);+ });+ });++ test('nothing paid turns on from the first-run settings: writeback in effect off, keyless upkeep pays for nothing', () => {+ const [bundle] = buildInitFirstRunNotices({ searchMode: { mode: 'conservative', reason: 'No chat key.' }, writeback: true, upkeep: { embedding: false } });+ expect(bundle.decisions!.find(d => d.id === 'writeback')!.default).toBe('off');+ expect(bundle.decisions!.find(d => d.id === 'search_mode')!.default).toBe('conservative');+ expect(bundle.user_message).toContain('Nothing is deleted or paid for without you');+ expect(bundle.why).toContain('Nothing paid turns on from these settings without a key the user supplied');});- test('writeback recommends salient; every option applies through config set', () => {+ test('writeback is in effect off and recommends salient; every option applies through config set', () => {const writeback = buildInitFirstRunNotices({ writeback: true })[0].decisions!.find(d => d.id === 'writeback')!;- expect(writeback.default).toBe('salient');+ expect(writeback.default).toBe('off');+ expect(writeback.default_reason).toContain('salient is recommended');expect(writeback.options.map(o => o.id)).toEqual(['salient', 'all', 'off']);for (const o of writeback.options) expect(o.argv).toEqual(['gbrain', 'config', 'set', 'memory.auto_writeback', o.id]);});@@ -64,7 +103,7 @@ describe('the upkeep line (GBRA-438)', () => {expect(upkeep.default).toBe('on');expect(upkeep.options.find(o => o.id === 'on')!.argv).toBeUndefined();expect(upkeep.options.find(o => o.id === 'off')!.argv).toEqual(['gbrain', 'config', 'set', 'maintenance.auto', 'false']);- expect(bundle.user_message).toContain('upkeep: on');+ expect(bundle.user_message).toContain(upkeepLine(false));});test('a keyed brain\'s line names the one capped paid step', () => {@@ -103,7 +142,7 @@ describe('setupFirstRunNotices (gbrain setup <harness>)', () => {const [n] = setupFirstRunNotices(fromInit({ searchMode, writeback: true }), 'Claude Code');expect(n.user_message).toBe('gbrain is set up and Claude Code is wired, so memory works now. In effect: search mode balanced; agents save only what you ask them to remember, '- + 'until you turn on automatic saving (gbrain recommends salient: durable facts you state, saved with provenance). '+ + 'until you turn on automatic saving (salient is recommended: durable facts you state, saved with provenance). '+ 'Report back (Wakeshift): off. gbrain wakeshift enable turns it on. '+ `${costMatrixSentence()} Nothing needs an answer now; tell me any time if you want to change any of these, and I'll apply it.`,);diff --git a/test/init-fresh-pglite.slow.test.ts b/test/init-fresh-pglite.slow.test.tsindex 71011c8bb2..de3dd9a827 100644--- a/test/init-fresh-pglite.slow.test.ts+++ b/test/init-fresh-pglite.slow.test.ts@@ -299,8 +299,8 @@ describe('v0.37 T12 — D9 --no-embedding deferred-setup mode', () => {expect(out.match(/\[first_run_decisions\]/g)).toHaveLength(1);expect(bundle).toContain('(id: writeback)');expect(bundle).toContain('(run: gbrain config set memory.auto_writeback salient)');- expect(bundle).toContain('default: salient');- expect(out.match(/Reply 'defaults'/g)).toHaveLength(1);+ expect(bundle).toContain('default: off');+ expect(out.match(/Nothing needs an answer now/g)).toHaveLength(1);// The old separate writeback banner/[AGENT] ask and the skills pointer are gone.expect(out).not.toContain('Ambient memory writeback is available');expect(out + r.stderr).not.toContain('Ask me to run');diff --git a/test/init-mode-picker.test.ts b/test/init-mode-picker.test.tsindex aae8c5ed04..0624bcea28 100644--- a/test/init-mode-picker.test.ts+++ b/test/init-mode-picker.test.ts@@ -246,9 +246,10 @@ describe('runModePicker: non-TTY and --json', () => {expect(await engine.getConfig('search.mode_source')).toBe('auto');expect(decision).toEqual({ mode: 'tokenmax', reason: MODE_REASONS.default });expect(out).toContain('[gbrain] search mode tentatively set to: tokenmax');- expect(out.toLowerCase()).toContain('show this matrix');+ expect(out).toContain('nothing waits on an answer');+ expect(out).not.toContain('ask_user');expect(out).toContain('INSTALL_FOR_AGENTS.md');- expect(out).toContain('gbrain init --search-mode <mode>');+ expect(out).toContain('gbrain config set search.mode <conservative|balanced|tokenmax>');expect(out).toContain('Opus 5.5');});});diff --git a/test/install-no-postinstall.test.ts b/test/install-no-postinstall.test.tsnew file mode 100644index 0000000000..9bcc23abb1--- /dev/null+++ b/test/install-no-postinstall.test.ts@@ -0,0 +1,16 @@+import { describe, expect, test } from 'bun:test';+import { existsSync, readFileSync } from 'fs';+import { join } from 'path';++const root = join(import.meta.dir, '..');++describe('GST-2732: installing gbrain runs no lifecycle script', () => {+ test('package.json declares no preinstall, install or postinstall script', () => {+ const scripts = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).scripts ?? {};+ expect(Object.keys(scripts).filter(name => ['preinstall', 'install', 'postinstall'].includes(name))).toEqual([]);+ });++ test('scripts/postinstall.ts is gone, so nothing can wire it back in', () => {+ expect(existsSync(join(root, 'scripts/postinstall.ts'))).toBe(false);+ });+});diff --git a/test/migrations-notice.test.ts b/test/migrations-notice.test.tsnew file mode 100644index 0000000000..828c524fac--- /dev/null+++ b/test/migrations-notice.test.ts@@ -0,0 +1,66 @@+/**+ * GST-2732: with no postinstall, a reinstall over an older brain leaves its upgrade migrations to the next command,+ * so connect names them. The notice must fire when an older brain has unrun migrations and stay quiet on a brain+ * with no ledger, a brain that ran them all, and the commands that run or report migrations themselves.+ */+import { afterAll, describe, expect, test } from 'bun:test';+import { mkdtempSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { withEnv } from './helpers/with-env.ts';+import { pendingUpgradeMigrationsNotice } from '../src/cli/migrations-notice.ts';+import { MIGRATION_VERSIONS } from '../src/core/migration-ledger.ts';+import { appendCompletedMigration } from '../src/core/preferences.ts';++const engine = { getConfig: async () => null } as never;+const homes: string[] = [];+const latest = MIGRATION_VERSIONS[MIGRATION_VERSIONS.length - 1]!;++async function inHome<T>(fn: () => Promise<T>): Promise<T> {+ const home = mkdtempSync(join(tmpdir(), 'gbrain-migrations-notice-'));+ homes.push(home);+ return withEnv({ GBRAIN_HOME: home }, fn);+}++afterAll(() => { for (const h of homes) rmSync(h, { recursive: true, force: true }); });++describe('pendingUpgradeMigrationsNotice', () => {+ test('an older brain with unrun upgrade migrations gets a migrations_pending notice whose fix applies them', async () => {+ const notice = await inHome(async () => {+ appendCompletedMigration({ version: MIGRATION_VERSIONS[0]!, status: 'complete' } as never);+ return pendingUpgradeMigrationsNotice(engine, 'query', latest);+ });+ expect(notice).toMatchObject({ code: 'migrations_pending', fix: { argv: ['gbrain', 'apply-migrations', '--yes', '--no-autopilot-install'] } });+ expect(notice!.why).toContain(latest);+ });++ test('a migration whose last run was partial still gets the notice', async () => {+ const notice = await inHome(async () => {+ for (const version of MIGRATION_VERSIONS) appendCompletedMigration({ version, status: version === latest ? 'partial' : 'complete' } as never);+ return pendingUpgradeMigrationsNotice(engine, 'query', latest);+ });+ expect(notice?.why).toContain(latest);+ });++ test('no ledger yet (a fresh brain) means no notice', async () => {+ expect(await inHome(() => pendingUpgradeMigrationsNotice(engine, 'query', latest))).toBeNull();+ });++ test('a brain that ran every migration gets no notice', async () => {+ const notice = await inHome(async () => {+ for (const version of MIGRATION_VERSIONS) appendCompletedMigration({ version, status: 'complete' } as never);+ return pendingUpgradeMigrationsNotice(engine, 'query', latest);+ });+ expect(notice).toBeNull();+ });++ test('commands that run or report the migrations themselves get no notice', async () => {+ for (const command of ['apply-migrations', 'post-upgrade', 'upgrade', 'doctor', 'init', 'setup', 'serve']) {+ const notice = await inHome(async () => {+ appendCompletedMigration({ version: MIGRATION_VERSIONS[0]!, status: 'complete' } as never);+ return pendingUpgradeMigrationsNotice(engine, command, latest);+ });+ expect(notice).toBeNull();+ }+ });+});diff --git a/test/scripts/postinstall-standalone.test.ts b/test/scripts/postinstall-standalone.test.tsdeleted file mode 100644index b2fe6c494d..0000000000--- a/test/scripts/postinstall-standalone.test.ts+++ /dev/null@@ -1,28 +0,0 @@-import { describe, expect, test } from 'bun:test';-import { spawnSync } from 'node:child_process';-import { copyFileSync, mkdirSync, mkdtempSync, rmSync } from 'node:fs';-import { tmpdir } from 'node:os';-import { join, resolve } from 'node:path';--const REPO = resolve(import.meta.dir, '..', '..');--describe('scripts/postinstall.ts exits 0 on every path', () => {- test('runs from a directory holding only package.json and the script (Docker dependency layer)', () => {- const dir = mkdtempSync(join(tmpdir(), 'gbrain-postinstall-standalone-'));- try {- mkdirSync(join(dir, 'scripts'));- copyFileSync(join(REPO, 'package.json'), join(dir, 'package.json'));- copyFileSync(join(REPO, 'scripts', 'postinstall.ts'), join(dir, 'scripts', 'postinstall.ts'));- const result = spawnSync(process.execPath, ['--no-env-file', join(dir, 'scripts', 'postinstall.ts')], {- cwd: dir,- env: { HOME: dir, GBRAIN_HOME: dir, PATH: '/usr/bin:/bin' },- encoding: 'utf8',- timeout: 30_000,- });- expect(result.status, result.stderr + result.stdout).toBe(0);- expect(result.stderr).toContain('postinstall skipped');- } finally {- rmSync(dir, { recursive: true, force: true });- }- });-});diff --git a/test/upgrade-migration-outcome.test.ts b/test/upgrade-migration-outcome.test.tsindex 96cc39b2f9..e2f43c25dc 100644--- a/test/upgrade-migration-outcome.test.ts+++ b/test/upgrade-migration-outcome.test.ts@@ -1,6 +1,6 @@/**- * #5693: `gbrain upgrade` owns migrations through post-upgrade, so package- * postinstall defers them; an install that failed after the version swapped+ * #5693: `gbrain upgrade` owns migrations through post-upgrade (the install+ * step runs none); an install that failed after the version swapped* is reported as installed; and the run ends with separate binary and* migration lines (complete, running with the holder, or failed with the* recovery command).@@ -28,7 +28,7 @@ function runUpgradeHarness(opts: { bunExit?: number; postUpgradeExit?: number; cwriteFileSync(join(pkg, 'package.json'), JSON.stringify({ name: 'gbrain', repository: { url: 'https://github.com/garrytan/gbrain' } }));const driver = join(pkg, 'src', 'cli.ts');writeFileSync(driver, `const { runUpgrade } = await import(${JSON.stringify(join(REPO, 'src/commands/upgrade.ts'))});\nawait runUpgrade(['--no-bun-floor-check']);\n`);- writeFileSync(join(bin, 'bun'), `#!/bin/sh\nprintf 'bun:%s:owns=%s\\n' "$*" "$GBRAIN_UPGRADE_OWNS_MIGRATIONS" >> "$HOME/calls.log"\n${JSON.stringify(process.execPath)} ${JSON.stringify(join(REPO, 'scripts/postinstall.ts'))}\nexit ${opts.bunExit ?? 0}\n`, { mode: 0o755 });+ writeFileSync(join(bin, 'bun'), `#!/bin/sh\nprintf 'bun:%s:owns=%s\\n' "$*" "$GBRAIN_UPGRADE_OWNS_MIGRATIONS" >> "$HOME/calls.log"\nexit ${opts.bunExit ?? 0}\n`, { mode: 0o755 });writeFileSync(join(bin, 'gbrain'), `#!/bin/sh\nprintf 'gbrain:%s\\n' "$*" >> "$HOME/calls.log"\nif [ "$1" = '--version' ]; then echo 'gbrain ${NEWER}'; fi\nif [ "$1" = 'post-upgrade' ]; then exit ${opts.postUpgradeExit ?? 0}; fi\nexit 0\n`, { mode: 0o755 });const result = spawnSync(process.execPath, ['--no-env-file', driver], {cwd: home,@@ -41,7 +41,7 @@ function runUpgradeHarness(opts: { bunExit?: number; postUpgradeExit?: number; c}describe('gbrain upgrade migration ownership and outcome (#5693)', () => {- test('package postinstall under upgrade defers migrations to post-upgrade', () => {+ test('upgrade runs migrations once, in post-upgrade, never during the install step', () => {const r = runUpgradeHarness({});expect(r.status, r.out).toBe(0);expect(r.calls).toContain('bun:update --backend=copyfile gbrain:owns=1');diff --git a/test/upgrade-no-autopilot.serial.test.ts b/test/upgrade-no-autopilot.serial.test.tsindex 495c584125..ac2d99a1c4 100644--- a/test/upgrade-no-autopilot.serial.test.ts+++ b/test/upgrade-no-autopilot.serial.test.ts@@ -19,7 +19,7 @@ describe('upgrade autopilot opt-out propagation', () => {writeFileSync(join(pkg, 'package.json'), JSON.stringify({ name: 'gbrain', repository: { url: 'https://github.com/garrytan/gbrain' } }));const driver = join(pkg, 'src', 'cli.ts');writeFileSync(driver, `const { runUpgrade } = await import(${JSON.stringify(join(REPO, 'src/commands/upgrade.ts'))});\nawait runUpgrade(['--no-autopilot-install', '--no-bun-floor-check']);\n`);- writeFileSync(join(bin, 'bun'), `#!/bin/sh\nprintf 'bun:%s:no-autopilot=%s\\n' "$*" "$GBRAIN_NO_AUTOPILOT_INSTALL" >> "$HOME/calls.log"\nexec ${JSON.stringify(process.execPath)} ${JSON.stringify(join(REPO, 'scripts/postinstall.ts'))}\n`, { mode: 0o755 });+ writeFileSync(join(bin, 'bun'), `#!/bin/sh\nprintf 'bun:%s:no-autopilot=%s\\n' "$*" "$GBRAIN_NO_AUTOPILOT_INSTALL" >> "$HOME/calls.log"\n`, { mode: 0o755 });writeFileSync(join(bin, 'gbrain'), `#!/bin/sh\nprintf 'gbrain:%s:no-autopilot=%s\\n' "$*" "$GBRAIN_NO_AUTOPILOT_INSTALL" >> "$HOME/calls.log"\nif [ "$1" = '--version' ]; then echo 'gbrain ${VERSION}'; fi\n`, { mode: 0o755 });const result = spawnSync(process.execPath, ['--no-env-file', driver], {cwd: home,diff --git a/tests/docker/Dockerfile b/tests/docker/Dockerfileindex a5574580aa..9f77de95f3 100644--- a/tests/docker/Dockerfile+++ b/tests/docker/Dockerfile@@ -18,13 +18,11 @@ RUN apt-get update \WORKDIR /app# Dependency layer first for build caching. Lifecycle scripts stay on-# (@electric-sql/pglite is a trustedDependency), so postinstall.ts must be-# present before `bun install`; it loads every repo module dynamically and-# exits 0 on every path, so it needs nothing else from src/. patches/ is-# copied so a future `patchedDependencies` entry cannot break this layer.+# (@electric-sql/pglite is a trustedDependency); gbrain itself ships none, so+# the layer needs nothing from scripts/ or src/. patches/ is copied so a+# future `patchedDependencies` entry cannot break this layer.COPY package.json bun.lock bunfig.toml ./COPY patches/ patches/-COPY scripts/postinstall.ts scripts/postinstall.tsRUN bun install --frozen-lockfile# The repo itself. node_modules/.git/bin are excluded via