Skip to content

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.yml
index 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.md
index 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 keyless
memory: `gbrain init --pglite --no-embedding` (zero-config). For 1000+ files or
multi-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-step
flow (keyless memory, optional API capabilities, maintenance, verification).
diff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.md
index 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 Keys
Configured cloud providers receive text: embedding inputs, queries and candidate
@@ -162,21 +160,23 @@ gbrain init --pglite --no-embedding # keyless memory, no server needed
gbrain 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 this
loop; 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 yourself
when 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 of
assuming memory-only options are the desired maintenance policy. Verify a known
diff --git a/behavior-changes.d/first_run_connects_then_reports_gst2732.md b/behavior-changes.d/first_run_connects_then_reports_gst2732.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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 migration
orchestrators, and skips existing service-unit rewrites. Other migrations still
run. `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#stable
gbrain 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.md
index 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.md
index 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.md
index 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 the
diff --git a/docs/guides/authorization-upgrade.md b/docs/guides/authorization-upgrade.md
index 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 release
through 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 pending
setup phases that start autopilot or perform other maintenance.
diff --git a/docs/guides/minions-fix.md b/docs/guides/minions-fix.md
index 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.
## Context
The 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 present
but the migration never completed: no `~/.gbrain/preferences.json`,
autopilot still runs inline, cron jobs still call `agentTurn`. This guide
covers detecting that state and finishing the migration.
diff --git a/docs/guides/shared-brain-skills.md b/docs/guides/shared-brain-skills.md
index 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`) skips
v0.53.0 entirely: no inventory, no `shared_skills.migration.v1*` config
writes, and the applied-migration re-check does not run. `gbrain
apply-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.md
index 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. The
registration always uses the absolute gbrain path and `--surface starter`,
diff --git a/docs/tutorials/connect-coding-agent.md b/docs/tutorials/connect-coding-agent.md
index 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 Claude
subscription. Choosing a mode does not enable paid APIs or automatic capture.
diff --git a/llms-full.txt b/llms-full.txt
index 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 keyless
memory: `gbrain init --pglite --no-embedding` (zero-config). For 1000+ files or
multi-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-step
flow (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 Keys
Configured cloud providers receive text: embedding inputs, queries and candidate
@@ -2026,21 +2020,23 @@ gbrain init --pglite --no-embedding # keyless memory, no server needed
gbrain 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 this
loop; 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 yourself
when 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 of
assuming 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. The
registration always uses the absolute gbrain path and `--surface starter`,
diff --git a/package.json b/package.json
index 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.md
index 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. The
registration 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.md
index 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. The
registration 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.md
index 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. The
registration always uses the absolute gbrain path and `--surface starter`,
diff --git a/plugin/skills/setup/SKILL.md b/plugin/skills/setup/SKILL.md
index 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 the
previous 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 a
harness subscription. This choice does not enable paid APIs or capture.
diff --git a/scripts/build-agent-protocol.ts b/scripts/build-agent-protocol.ts
index 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.ts
deleted file mode 100644
index 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 install
diff --git a/scripts/structural-suites.tsv b/scripts/structural-suites.tsv
index 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 readFileSync
test/hook-push-spawn-env.test.ts tryExecAsync env handoff 1 readFileSync
test/import-private-hold-callers-7897.test.ts import entry points hold a non-canonical private request (#7897) 2 readFileSync
test/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 readFileSync
test/integrations-install.test.ts installRecipeIntoHostRepo — happy path 6 readFileSync
test/integrations.test.ts CLI integration 3 source-surface-helper
test/jobs-embed-background-parity.serial.test.ts embed job background parity (D7) 2 readFileSync,source-surface-helper
diff --git a/scripts/test-weights.json b/scripts/test-weights.json
index 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.json
index 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.json
index 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.md
index 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. The
registration always uses the absolute gbrain path and `--surface starter`,
diff --git a/skills/setup/SKILL.md b/skills/setup/SKILL.md
index 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 the
previous 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 a
harness subscription. This choice does not enable paid APIs or capture.
diff --git a/skills/skills.lock.history.json b/skills/skills.lock.history.json
index 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.json
index 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.ts
index 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: EngineConnectOpt
writeCliNotice(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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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: s
const 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.reportBack
diff --git a/src/commands/init.ts b/src/commands/init.ts
index 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.ts
index 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?: string
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 instead
diff --git a/test/apply-migrations-schema-exit.test.ts b/test/apply-migrations-schema-exit.test.ts
index 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 so
expect(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.ts
index 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.json
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
deleted file mode 100644
index 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.ts
index 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; c
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-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.ts
index 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/Dockerfile
index 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.ts
RUN bun install --frozen-lockfile
# The repo itself. node_modules/.git/bin are excluded via