Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Doctor, init, call import and gbrain serve report and record the right thing in seven small cases (#9458)
Garry Tan3fb21af79061
diff --git a/changelog.d/fix-small-fix-wave-3.md b/changelog.d/fix-small-fix-wave-3.mdnew file mode 100644index 0000000000..86ea1627b3--- /dev/null+++ b/changelog.d/fix-small-fix-wave-3.md@@ -0,0 +1,14 @@+**Doctor, init, call import and gbrain serve report and record the right thing in seven small cases.**++### Fixed+- `gbrain doctor`'s grant check is ok when the only operations a grant misses are ones the owner adds by name, and its message names them with the command that adds them.+- `gbrain import --calls` finds a call already imported from any folder above the one you import, and reports a call whose page is still being written as pending instead of writing a second copy; with `--accept-pending` it still exits 10 when that write waits on a stale owner host.+- A folder whose `.git` is an empty file is no longer taken as a git checkout.+- Release notes drop a trailing internal issue code, like `(ABC-12)`, from each line of the change list.+- `gbrain init --force --embedding-model <model>` records the new model and width in the database as well as the config file, so the two agree (#9451).+- `gbrain serve` names upgrade migrations that haven't run, once at startup on stderr, and `gbrain doctor` reports them too, also on a brain an older release last opened whose local upgrade ledger is empty.++### For contributors+- The key-files page `google-and-loops.md` was at its 60,000-byte cap, so its harness and MCP entries moved unchanged to `google-and-loops-more.md`; the Google source entry now says what an unmanaged `--dry-run` returns.++Reported by @Loprz (#9451).diff --git a/docs/architecture/key-files/commands-2.md b/docs/architecture/key-files/commands-2.mdindex 26513de6fb..ab0914decd 100644--- a/docs/architecture/key-files/commands-2.md+++ b/docs/architecture/key-files/commands-2.md@@ -41,7 +41,7 @@ Doctor's embedding-dimension warning treats existing chunks as existing data eveSize ceiling: `scripts/module-size-limits.tsv` (per-change raise history: `git log -p` on that file). The ceiling covers the façade: re-exports, `Check`/`DoctorReport` and report scoring, the `buildChecks` flag parse, `runDoctor`, output rendering and `--locks`; every check block lives in a registry entry under `doctor/checks/*` (refactor wave 1 W4 doctor), remediation in `doctor/remediate.ts`, wave checks in `doctor/wave-checks.ts`.- `src/commands/doctor/check-fix.ts` (+ `heartbeat.ts`, `checks/harness-wiring.ts`, `checks/agent-contract.ts`) — doctor speaks agent contract v1. `Check` carries optional `fix` (stored `Action`; `computeDoctorReport` renders it for the report's transport via `finalizeCheckFixes`, redacted on http), `fix_unavailable_reason` (`check_errored`, `operator_judgement`, `no_safe_automatic_fix`, `unstructured` for legacy prose-only warns), `severity: 'info'` and `readiness_state`; `schema_version` stays 2 and status stays `ok | warn | fail`. Capabilities that are off by choice or not applicable yet (keyless embeddings and their staleness/vector checks, opt-in takes, no serve running, 0 pages, never-cycled empty or <24 h sources, backup before 25 pages+facts or 7 days via `backupCoachingDue`) report `ok` + `info` with the enable command as `fix`; the report adds `capped_by: ['embeddings_disabled']` and, when the `connection` check is present and not ok, `unknown_scores: ['brain']`. `top_issues[]` gain `action` (the rendered fix) beside the legacy `fix` string. `checkError(name, what, err)` is the one "Could not …" shape (a `gbrain db-repair` fix when the error classifies as DB access). `gbrain doctor --only <check>[,…] [--json]` (`parseOnlyChecks`, `onlyNeedsEngine`, CLI `runDoctorOnly`) runs only the entries that emit those names plus the connection lane, engine-free when every name is a filesystem check, else `connectEngine({ probeOnly: true })`; unknown names exit 2 with the valid list; a requested check that produced nothing reports `info`/`not_applicable` (or `check_errored` after an early stop). It is every doctor fix's `verify`. `harness_wiring` reads the gbrain registration from `~/.claude.json` (+ receipt `.mcp.json`), Codex `config.toml` (the user config, then the receipt workspace's `.codex/config.toml`) and `opencode.json`; under `--only harness_wiring` it smoke-tests it (live serve lock owner → `wired_running`; else spawn the registered argv, 15 s, initialize + tools/list + `recall`; `gbrain_status` replies reported with their reason/fix); it writes nothing. #6453: with no PGLite lock, an HTTP registration gets a credential-free 3 s GET of `/health` (`probeHttpRegistration`): gbrain `ok` → `wired_running` + `mcp_access: 'unverified'`; refused loopback `http:` → `http_serve_missing` + fix; else `http_serve_unreachable`/`http_serve_unhealthy`, no fix. `redactRegistrationUrl` strips userinfo, query and fragment from every printed URL (`test/harness-wiring-redaction-6453.test.ts`). `agent_contract` reads the whole size-bounded log (`readAgentContractEvents(Infinity)`, 7-day window) and warns on `internal_error`/suggestion-less envelopes, consent refusals, `derived_cap_exhausted` and `json_document_missing`, with the user-only `consent.preapprove.*` command as fix. `throttleDoctorHeartbeat`: piped doctor progress emits at most one heartbeat per 5 s. Tests: `test/doctor-status-set.test.ts`, `test/doctor-harness-smoke.test.ts`, `test/doctor-day-zero.test.ts` (keyless init then doctor: 0 WARN, health ≥ 90), `test/doctor-remote-parity.test.ts` (run_doctor and CLI agree per shared check; run_doctor renders fixes for its transport). `harness_wiring` with no registration drops each detected harness a plugin lane covers (`enabledPluginLanes`; all → `ok` `plugin_lane_enabled`, not smoke-tested) or whose receipt-recorded config it cannot read (#7422; all → `info` `registration_recorded`); the warning names the rest. Claude Code detection also honors `CLAUDE_CONFIG_DIR`.-- `src/commands/doctor/registry.ts` + `src/commands/doctor/context.ts` — the doctor check registry (refactor wave 1, W4 doctor). `DOCTOR_CHECK_REGISTRY` lists 126 `DoctorEntry` records `{ name, emits, run(ctx) -> Promise<Check[] | STOP_DOCTOR> }` in output order; `runDoctorRegistry(ctx)` runs them, returns the checks gathered so far on `STOP_DOCTOR`, and otherwise finishes the DB-checks progress phase. The run is one `withGitListingCache` scope (`src/core/git-visible-files.ts`), so entries that list the same source checkout (frontmatter scan, fence census, slug collisions) share one `git ls-files` per listing and one "not a git repository" verdict per directory (`ls-files`, `discoverGitRoot`, the census HEAD probe; any repository-changing `sync-git.ts` command or `invalidateGitListingCache()` drops the scope's memo: `test/git-listing-memo.serial.test.ts`). Execution groups: filesystem-first entries (the resolver-health entry applies `--fix` before it scans), the no-engine connection lane plus a STOP when `--fast` or no engine, the live connection entry plus a STOP when `getStats` failed, then the DB entries, which take the engine via `connectedEngine(ctx)`. GBRA-541: the entries that emit `LOST_WRITE_CHECKS` (`git_index_lag`, `db_ahead_of_git`, `strict_facts_outside_git`, `owner_host_stale`, `uncommitted_sync_deletions`) sit right after the privacy check, before the full scans, so slow scans on a large brain cannot use up the budget first (`test/doctor-entry-deadline-6803.test.ts`). `DoctorContext` carries the parsed flags (`jsonOutput`, `fastMode`, `doFix`, `dryRun`, `scope`, `orphanRatioSourceId`, `args`), `engine`, `dbSource`, `connectError`, `progress`, the skills-dir resolution and the cross-entry values `autoFixReport`, `schemaVersion`, `connectionFailed`, each written by the entry that computes it. Entry modules (one `run*` function per former `buildChecks` block, moved verbatim): `checks/skill-group.ts`, `local-runtime.ts`, `supervisor-health.ts`, `local-audits.ts`, `db-connection.ts` (also `pgbouncerPrepareCheck`, `classifiedConnectionCheck` — a live serve owner warns with the exclusive two-step fix, a `pglite_busy` reason `legacy_owner_unverified` fails with details.reason and the refusal's ask_user preview fix, anything else is classified for `db-repair` — and the two STOP gates), `schema-health.ts`, `embedding-health.ts`, `graph-health.ts`, `data-integrity.ts`, `content-quality.ts`, `knowledge-health.ts`, `queue-assets.ts`, `sync-search.ts`; `checks/legacy-token-grants.ts` (F3) emits `legacy_token_grant_shape` (info: active tokens still on the JSONB-only grant shape, fix `gbrain auth rescope --migrate-legacy`) and `legacy_token_grant_drift` (warn: per-token drifted axes with the two adopt commands); `checks/grant-new-ops.ts` (D4) emits `grant_new_ops_available` (warn: active clients and tokens whose operation snapshot or stored surface keeps operations their scopes allow out of reach, with proven blockers apart from inferred grant age, per-grant names in details, and an ask_user fix whose rescope argv differs for tokens and clients; `--operations all` is a disclosed choice, never the fix); `checks/upgrade-health.ts` holds `checkUpgradeErrors` / `checkSelfUpgradeHealth` / `upgradeErrorResolved` (re-exported by the façade). A pre-gate entry declares the names it only emits with a connected engine in `engineChecks` (#6303), so `onlyNeedsEngine` connects for `--only` of them; `test/doctor-only-engine-checks.test.ts` is the drift guard. To add a check: add an entry in the topic module, place it in `DOCTOR_CHECK_REGISTRY` where its output belongs, and categorize every emitted name in `src/core/doctor-categories.ts`. Tests: `test/doctor-registry.test.ts` (category contract with FAIL/Why/Fix/See, `emits[]` equals the AST walk, STOP positions), `test/doctor-mode-matrix.serial.test.ts` (entries run, STOP point, engine calls and `--fix` mutations per mode), and the W0 goldens `test/doctor-registry-golden.test.ts` (the AST walker follows `runDoctorRegistry` into the registry), `test/doctor-early-stop-golden.serial.test.ts`, `test/doctor-json-golden.test.ts`.+- `src/commands/doctor/registry.ts` + `src/commands/doctor/context.ts` — the doctor check registry (refactor wave 1, W4 doctor). `DOCTOR_CHECK_REGISTRY` lists 126 `DoctorEntry` records `{ name, emits, run(ctx) -> Promise<Check[] | STOP_DOCTOR> }` in output order; `runDoctorRegistry(ctx)` runs them, returns the checks gathered so far on `STOP_DOCTOR`, and otherwise finishes the DB-checks progress phase. The run is one `withGitListingCache` scope (`src/core/git-visible-files.ts`), so entries that list the same source checkout (frontmatter scan, fence census, slug collisions) share one `git ls-files` per listing and one "not a git repository" verdict per directory (`ls-files`, `discoverGitRoot`, the census HEAD probe; any repository-changing `sync-git.ts` command or `invalidateGitListingCache()` drops the scope's memo: `test/git-listing-memo.serial.test.ts`). Execution groups: filesystem-first entries (the resolver-health entry applies `--fix` before it scans), the no-engine connection lane plus a STOP when `--fast` or no engine, the live connection entry plus a STOP when `getStats` failed, then the DB entries, which take the engine via `connectedEngine(ctx)`. GBRA-541: the entries that emit `LOST_WRITE_CHECKS` (`git_index_lag`, `db_ahead_of_git`, `strict_facts_outside_git`, `owner_host_stale`, `uncommitted_sync_deletions`) sit right after the privacy check, before the full scans, so slow scans on a large brain cannot use up the budget first (`test/doctor-entry-deadline-6803.test.ts`). `DoctorContext` carries the parsed flags (`jsonOutput`, `fastMode`, `doFix`, `dryRun`, `scope`, `orphanRatioSourceId`, `args`), `engine`, `dbSource`, `connectError`, `progress`, the skills-dir resolution and the cross-entry values `autoFixReport`, `schemaVersion`, `connectionFailed`, each written by the entry that computes it. Entry modules (one `run*` function per former `buildChecks` block, moved verbatim): `checks/skill-group.ts`, `local-runtime.ts`, `supervisor-health.ts`, `local-audits.ts`, `db-connection.ts` (also `pgbouncerPrepareCheck`, `classifiedConnectionCheck` — a live serve owner warns with the exclusive two-step fix, a `pglite_busy` reason `legacy_owner_unverified` fails with details.reason and the refusal's ask_user preview fix, anything else is classified for `db-repair` — and the two STOP gates), `schema-health.ts`, `embedding-health.ts`, `graph-health.ts`, `data-integrity.ts`, `content-quality.ts`, `knowledge-health.ts`, `queue-assets.ts`, `sync-search.ts`; `checks/legacy-token-grants.ts` (F3) emits `legacy_token_grant_shape` (info: active tokens still on the JSONB-only grant shape, fix `gbrain auth rescope --migrate-legacy`) and `legacy_token_grant_drift` (warn: per-token drifted axes with the two adopt commands); `checks/grant-new-ops.ts` (D4) emits `grant_new_ops_available` (warn: active clients and tokens whose operation snapshot or stored surface keeps operations their scopes allow out of reach, with proven blockers apart from inferred grant age, per-grant names in details, and an ask_user fix whose rescope argv differs for tokens and clients; `--operations all` is a disclosed choice, never the fix; a grant missing only operations the owner approves by name stays `ok`, its message naming them with the by-name command); `checks/upgrade-health.ts` holds `checkUpgradeErrors` / `checkSelfUpgradeHealth` / `upgradeErrorResolved` (re-exported by the façade). A pre-gate entry declares the names it only emits with a connected engine in `engineChecks` (#6303), so `onlyNeedsEngine` connects for `--only` of them; `test/doctor-only-engine-checks.test.ts` is the drift guard. To add a check: add an entry in the topic module, place it in `DOCTOR_CHECK_REGISTRY` where its output belongs, and categorize every emitted name in `src/core/doctor-categories.ts`. Tests: `test/doctor-registry.test.ts` (category contract with FAIL/Why/Fix/See, `emits[]` equals the AST walk, STOP positions), `test/doctor-mode-matrix.serial.test.ts` (entries run, STOP point, engine calls and `--fix` mutations per mode), and the W0 goldens `test/doctor-registry-golden.test.ts` (the AST walker follows `runDoctorRegistry` into the registry), `test/doctor-early-stop-golden.serial.test.ts`, `test/doctor-json-golden.test.ts`.- `src/commands/doctor/` — the doctor module directory behind the `doctor.ts` façade. `checks/` holds the check functions, grouped by concern (`core-health.ts`, `queue-jobs.ts`, `extraction-sync.ts` (its `sync_freshness` check excludes sources disabled by `isSyncDisabledConfig` and adds `--no-pull` to its sync hint on a managed brain; `content_hash_duplicates` prescribes `GBRAIN_SOURCE=<id> gbrain delete <bare-slug> --force` per wrong-root pair, naming each source when pairs span several, and never a hard purge; `cycle_freshness` in `consolidation-cycle.ts` still monitors their maintenance; its `atom_provenance_drift` check scopes drift to page-bound atoms and splits it into `source_changed` / `source_gone`; atoms with no `source_slug` — transcript-origin `source_path`-only rows, hashed over a file, with page liveness unresolvable by slug — count as their own `slug_unbound`, outside the drift total and the WARN ratio), `graph-embedding.ts`, `search-eval.ts`, `calibration.ts`, `consolidation-cycle.ts`, `pglite-worker.ts`, `routing-federation.ts` (`source_routing_health` exempts zero-page skill-pack sources), `verbs-reflex.ts`, `stale-mentions.ts`, `timeline-history.ts` (`timeline_history`: database-only timeline rows, bounded to 2,000 pages / 10 s per run, cursor in config `doctor.timeline_history.scan:<sources>` so runs finish a pass (a clean pass stays `ok` until a newer row; `doctor-timeline-history-cursor-5821.test.ts`), exact-or-lower-bound counts (lower bound past 10,000 found pages), non-round-trippable rows informational, repair `gbrain repair timeline`; segmented pages counted apart (`segmented_*`), no repair advice), `derived-visibility.ts` (`derived_visibility`: atoms and synthesized concepts without explicit visibility or looser than their origin (an origin a rename moved counts through `slug_rename_history`, GST-2687), one exact aggregate, repair `gbrain repair visibility`), `engine-fit.ts` — the last carrying `pglite_scale` + the engine-free `db_repair_recurrence` over the db-repair receipts); `schema-pack-checks.ts`, `report-remote.ts`, `bootstrap-checks.ts`, and `skill-checks.ts` are the four tail-cluster modules (schema-pack checks, the remote/thin-client doctor report, bootstrap checks, skill checks). `harness-hook-checks.ts` (`harnessHookCarrierChecks`, called from `bootstrap_harness_health`) reads each receipt-named Claude Code hook carrier read-only: an event wired more than once by this install warns `harness_hook_duplicates` with a consented re-run carrying the install's `--project`/`--no-capture` choices, a lookalike it did not write warns `harness_hook_unowned` (operator judgement), an unparseable carrier warns naming the file, and entries the host stripped of their marker are an `ok` info row; `plugin_lane_collision` iterates `enabledPluginLanes`. `multiSourceDriftCheck` is the one local/remote `multi_source_drift` verdict: on a managed brain (`managedPersistenceEnabled`) its sync advice names `--no-pull` and drops `--include-gitignored`, unmanaged wording is unchanged, and any skipped source keeps it warn/not_verified. `src/core/multi-source-drift.ts` derives a `git-root`-pinned source's slug prefix from its git toplevel (realpaths, empty at the repo root) and skips only a source whose toplevel cannot be resolved (`git_root_skipped`). It drops every walked path sync would refuse (`unsyncableReason(prefix + relPath)`: metafiles such as root `AGENTS.md`/`CLAUDE.md`, pruned dirs, malformed names) before probing, so a same-slug page on `default` is not reported for a file sync never imports (#6681). `graph-health.ts` `graph_coverage`, like onboard's link and timeline coverage, is `ok` (not applicable, with the count) below `MIN_ENTITY_PAGES_FOR_COVERAGE` (5) eligible entity pages. `graph_coverage` and `orphan_ratio` count the entity types the active schema pack declares (#4772, `src/core/schema-pack/entity-types.ts`, resolved per source: brain-wide for `graph_coverage`, the asked source for `orphan_ratio --source`); a pack that does not load makes `graph_coverage` a warn naming the pack (never the old hardcoded list) and `orphan_ratio` answers with an "entity count unknown" caveat instead of a vacuous ok. All are re-exported by the façade. Structural guards that pin doctor source text load it through `test/helpers/doctor-source.ts`: `doctorSource()` concatenates the façade plus every `src/commands/doctor/**/*.ts` (façade first, then sorted) so a module move can never take a pinned string out of a guard's sight; `doctorFileSource(rel)` reads one named file for positional/ordering assertions; the helper also feeds the `doctor-source-helper` detector in `scripts/classify-tests.ts`. `facadeExpansion` in `scripts/generate-flag-registry.ts` keeps this directory on the doctor command's flag-scan surface. Two read-only derived-data checks live beside them: `timeline-orphans.ts` (`timeline_orphans`, samples 500 pages for rows an earlier page version produced that the current text no longer does; fix is `gbrain extract timeline --prune-orphans`) and `slug-collisions.ts` (`slug_collisions`, walks each live source checkout with `collectSyncableFiles` and reports paths that map to one slug plus the indexed one; sources without a checkout are skipped). `checks/graph-embedding.ts` `checkJunkEntityHubs` (#6158) splits connector contact pages (frontmatter `google_contact_id` or a connector source kind) into `details.connector_twins` with their main-brain `canonical_twin`, never calls them extractor-minted or offers `junk_hub_exempt`, and carries `fix_unavailable_reason: 'operator_judgement'` while the defer-to-twin policy is open.diff --git a/docs/architecture/key-files/commands-5.md b/docs/architecture/key-files/commands-5.mdindex e005f8aa94..9ba1f41484 100644--- a/docs/architecture/key-files/commands-5.md+++ b/docs/architecture/key-files/commands-5.md@@ -30,7 +30,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/commands/setup.ts` + `src/cli/commands/setup.ts` — `gbrain setup <harness>` (D8), pre-connect and engine-free (`thinClient: 'none'`, `json: 'document'`): an orchestrator over the existing wiring, not a new installation system. Target first: it resolves the brain (`loadConfig`; none → a `gbrain init --pglite --no-embedding --json` child, `--providers` drops `--no-embedding`; setup prints `Brain ready at <path>` and never init's standalone quickstart or `[AGENT]` banners; on the brain it just created it runs the setup migrations init left pending (`finishFreshSetupMigrations`, `src/commands/setup-migrations.ts`: one `apply-migrations --yes --no-autopilot-install --json` child built by `setupMigrationsArgv` in `migrations/fresh-install.ts`, 60 s bound, offline; v0.11.0 is held back when its host phase would edit an existing `~/.claude/AGENTS.md`, `~/.openclaw/AGENTS.md` or OpenClaw cron manifest (`hostRewriteTargets`)) and replaces init's `[init] Migrations:` line with `[setup] Migrations: …` (a failure keeps init's hand-off plus the error code; an existing brain is not touched), and renders a `Memory:` line naming `remember` (#6606: world facts are pushed, private ones are recall-only, capture writes a page) and then `setupFirstRunNotices` once after `Next:` in human output, or under `notices` in `--json`), the source (`--source` > `GBRAIN_SOURCE` > unpinned), the launcher (`--gbrain-bin` > `resolveGbrainBin`), the surface (`--surface` > `GBRAIN_SURFACE` > the receipt's > `REGISTRATION_SURFACE`) and the registration owner, prints them, then refuses before any write with `setup_hosted_connection` (thin-client config, hosted connection receipt or remote entry: never a second, local brain) or `setup_owner_conflict` (`live_serve` from `peekLock` unless the live stdio serve is this registration's own, `unowned_entry`, `other_install` by receipt `gbrain_home`, `harness_lane` for a bootstrap harness receipt that wired the configuration setup would write (a target in t... (line truncated to 2000 chars)- `src/commands/setup-brain-layout.ts` — `gbrain setup claude-code|codex --shape personal|company|both [--notes DIR] [--docs DIR] [--transcripts DIR] [--team|--solo]` (GST-2731; guide `docs/guides/brain-layout.md`). Every page is written create-only through `gbrain get` then `gbrain put` children, and only when `get` reports `page_not_found` (empty forms, `status: stub`, one "Example (delete me)" line each): `me/facts`, `me/voice`, `me/how-i-decide` in the run's source, and `COMPANY_PAGES` (`company/facts`, `company/decisions`, `company/pricing`, `company/customers`, `company/calls`, `company/playbooks`) in the `company` source. The company source is kept when it exists, else added with `gbrain sources add company --path <dir>` on a gbrain-owned folder beside the default source's content root (never the person's docs folder; a path there that is not an empty folder fails the company part with an `ask_user` `brain_layout_pages_pending` and the block is written without company lines) with no federation flag, so `sources add` federates it only on a one-person brain (#9396); when it reads back unfederated, setup returns `source_not_in_default_search` with `ask_user`. `--notes` and `--docs` import read only with one `gbrain import DIR --no-embed --json` child each (GBRAIN_SOURCE pins the source; over `IMPORT_INLINE_MAX` = 500 markdown files it returns `brain_layout_import_pending` instead), then check keyless search finds the first file's title in the top 5 (company docs through default search when federated). `--team` creates nothing for the company part and returns `brain_layout_team_next`. A `<!-- gbrain:brain-layout:begin/end -->` block (lines per part) goes into the brain-first target only when the brain-first decision is accepted; `--no-instructions` removes it, `--shape none` removes it and keeps pages and source. A brand-new brain set up without `--shape` asks inline only when `isInteractive()`, otherwise `brain_shape` joins the `first_run_decisions` bundle (defa... (line truncated to 2000 chars)-- `src/commands/import-calls.ts` — `gbrain import <dir> --calls [--prefix <slug prefix>] [--source <id>] [--json]` (GST-2731), dispatched from `runImport` once the folder resolves (`--calls` also implies `--no-embed`; a `--prefix` value is never read as the folder). `listCallFiles` walks .txt/.md files (dot entries and symlinks skipped), and a single file argument imports that file as an import of its folder would (any other kind of file is an error); `callPageFor` names each `<prefix>/<date>-<title slug>` (date: dated file name, else first line, else modified day; title: rest of a dated file name, else first line, both read after redaction so a credential in either never reaches the title or slug), redacts the whole text with `redactSession` and the user's patterns (`loadImportRedactionPatterns`), redacts the relative path the same way (`redactCallPath`), neutralizes structure lines (`neutralizeOutsideText`) and writes frontmatter `type: meeting`, `facts_backstop: false` and `call_import: {file (redacted), root, path, hash, redactions, embedding_hold: call_import}` (root, path and hash JSON-quoted so they read back as strings), with no `readable_by`. `root` is `callRootId(dir)` (a hash of the folder path), `path` a hash of the folder and the unredacted relative path (so two names a redaction pattern makes alike stay two files, and neither name is stored), and the hash covers title and body, not the date. `call_import` is one of `ANY_SIZE_HOLD_REASONS` in `src/core/page-embedding-budget.ts`, so embed paths skip the page at any size until the owner approves it. `--prefix` is slugified per segment. Each new page goes through the `put_page` handler (trusted local context); a rerun finds the earlier page by `call_import.root` and `path` under the prefix (by `file` for a page stored before `path` existed, claimed by one file per run) (not the computed slug, which a new modified day can move) and reports it `unchanged` (same hash) or `kept` (never overwritten); a write still in flight (`write_pending`) is reported `pending` with its `gbrain write-request` command, not as an error, and ... (line truncated to 2000 chars)+- `src/commands/import-calls.ts` — `gbrain import <dir> --calls [--prefix <slug prefix>] [--source <id>] [--json]` (GST-2731), dispatched from `runImport` once the folder resolves (`--calls` also implies `--no-embed`; a `--prefix` value is never read as the folder). `listCallFiles` walks .txt/.md files (dot entries and symlinks skipped), and a single file argument imports that file as an import of its folder would (any other kind of file is an error); `callPageFor` names each `<prefix>/<date>-<title slug>` (date: dated file name, else first line, else modified day; title: rest of a dated file name, else first line, both read after redaction so a credential in either never reaches the title or slug), redacts the whole text with `redactSession` and the user's patterns (`loadImportRedactionPatterns`), redacts the relative path the same way (`redactCallPath`), neutralizes structure lines (`neutralizeOutsideText`) and writes frontmatter `type: meeting`, `facts_backstop: false` and `call_import: {file (redacted), root, path, hash, redactions, embedding_hold: call_import}` (root, path and hash JSON-quoted so they read back as strings), with no `readable_by`. `root` is `callRootId(dir)` (a hash of the folder path), `path` a hash of the folder and the unredacted relative path (so two names a redaction pattern makes alike stay two files, and neither name is stored), and the hash covers title and body, not the date. `call_import` is one of `ANY_SIZE_HOLD_REASONS` in `src/core/page-embedding-budget.ts`, so embed paths skip the page at any size until the owner approves it. `--prefix` is slugified per segment. Each new page goes through the `put_page` handler (trusted local context); a rerun finds the earlier page by `call_import.path` under the prefix, matching the path digest from any folder above the file that an import could have started from (`callPathIds`), or by `root` and `file` for a page stored before `path` existed, claimed by one file per run; a queued `put_page` of the same file is reported `pending`, not written again (not the computed slug, which a new modified day can move) and reports it `unchanged` (same hash) or `kept` (never overwritten); a write still in flight (`write_pending`) is reported `pending` with its `gbrain write-request` command, not as an error, and ... (line truncated to 2000 chars)- `src/commands/doctor/checks/facts-pages.ts` — `facts_undated_lines` (GST-2731, brain category): each `type: facts` page with list lines carrying no YYYY-MM-DD date is a warn naming source, slug and line numbers (never the line text); the fix is `gbrain get <slug> --source <id>` with `ask_user` for the dates; segmented pages are skipped and counted. Read-only. Pinned by `test/doctor-facts-undated-lines.test.ts`.- `src/core/setup/brain-first.ts` + `src/core/managed-block.ts` — the brain-first instruction block every harness install writes by default (`<!-- gbrain:brain-first:begin/end -->`, `BRAIN_FIRST_VERSION`). `brainFirstTarget` names each harness's own instruction file (Claude Code `~/.claude/CLAUDE.md` or `./CLAUDE.local.md`, Codex `AGENTS.md` or an existing `AGENTS.override.md`, opencode global `AGENTS.md`, OpenClaw `<workspace>/AGENTS.md` from JSON5 `agents.defaults.workspace` (several agents need `--workspace`), Hermes `SOUL.md` after the identity text, Cursor `.cursor/rules/gbrain-brain-first.mdc`); other clients get the block printed to paste. `syncBrainFirst` splices only between the markers (idempotent, upgrades in place, preserves a damaged block and reports it), and the decision (`--no-instructions` / `GBRAIN_AGENT_INSTRUCTIONS=0`, `--instructions`, prior) is remembered in `<configDir>/agent-instructions.json` with the writer (`underInstructionLedgerLock` holds one lock, `<configDir>/agent-instructions.lock`, shared with `skill-loading.json`, across the ledger read, the file and permission edits and the ledger write, re-reads a recorded decision under it, reports a lock it cannot take within 10 seconds as `preserve`, and a dry run takes none; `test/instruction-ledger-lock.test.ts`, `test/instruction-ledger-lock-timeout.slow.test.ts`), so `--remove` on setup, `connect --install` and `bootstrap harness` (lane in `bootstrap/harness-brain-first.ts`) strips only its own blocks. Text varies by access: MCP search surface, verbs surface, or the thin-client CLI launcher (`GBRAIN-INSTRUCTIONS.md` starts with it). doctor `harness_wiring` reads the ledger plus each registered or plugin-served harness's default file and warns on a missing, stale or damaged block with a fix that rewrites only the block (`instructionBlockViews`, `withInstructionBlocks`); `gbrain post-upgrade` prints the same command (`brain-first-upgrade-notice.ts`, `instructionBlockUpgradeHints`). The Clau... (line truncated to 2000 chars)- `src/core/setup/turn-hook.ts` + `src/core/setup/turn-hook-check.ts` — the per-turn rule hook for installs whose MCP came from a plain `mcp add` or another installer: a `turn-rule-v1` Claude Code UserPromptSubmit entry or a Codex `hooks.json` group plus its `config.toml` trust entry, running `GBRAIN_HOOK_LANE=turn-rule <hook launcher> gbrain hook user-prompt` (rule only, no local context; it yields to setup, bootstrap and plugin lanes). Written by `setup <claude-code|codex> --instructions-only`, `connect --install`, the hosted `harness connect --install` and `bootstrap harness` (not in registrar mode); with no absolute binary the outcome is `print` with the one-line next step. `inspectTurnHook` (files only; it also reads Claude Code's managed `managed-settings.json` and `managed-settings.d/*.json`, and `turnRuleHookYields` counts a managed gbrain hook, #8057) feeds doctor `harness_wiring` (`turnHookViews`, `withTurnHooks`: untrusted, or missing beside a ledger block, warns with code `turn_hook_not_loaded`); `verifyTurnHook` runs the hook (Claude Code, Codex), `openclaw plugins inspect gbrain-turn-rule --runtime --json` or `hermes hooks doctor`, and every install path exits non-zero with `turn_hook_not_loaded` when it fails (`docs/guides/repair.md#turn-hook-not-loaded`). OpenClaw and Hermes rules name the gbrain tools and the `tool_search` route (`renderBrainFirstTurnRule(access, harness)`; `test/brain-first-turn-rule.test.ts`, `test/setup-brain-first.test.ts`).diff --git a/docs/architecture/key-files/google-and-loops-more.md b/docs/architecture/key-files/google-and-loops-more.mdnew file mode 100644index 0000000000..f355409527--- /dev/null+++ b/docs/architecture/key-files/google-and-loops-more.md@@ -0,0 +1,9 @@+# Google connector + open-loop engine (more)++[Subsystem index](../KEY_FILES.md) · [Previous entries](google-and-loops.md).++- `src/core/harness/oauth-setup.ts` + `client-setup.ts` — explicit client metadata projection, flow selection, native OAuth setup/private-file validation, and live-row-locked secret delivery recovery. Public PKCE needs no journal; confidential exports validate the retained secret against current registration, and machine exports discard cached tokens. Unknown/mixed flows refuse until an explicit supported flow is selected.+- `src/core/harness/capabilities.ts` + `src/mcp/capabilities.ts` — Shared effective-grant orientation for OAuth whoami and authenticated `gbrain://capabilities`. A stored client token lifetime outside 60 to 7,776,000 seconds (`AuthInfo.tokenTtlSeconds`) reports `token_ttl_invalid`, and the delegation repair template then includes a `--token-ttl <APPROVED_TTL_SECONDS>` choice, since every grant write validates the merged lifetime. The resource preserves the exact seven-tool surface; source, operation, scope, fence and server-gate restrictions remain enforced at dispatch. `grant_diagnosis` (shared with doctor `grant_new_ops_available` through `grantOperationGaps`, `grantAge` and `grantRescopeArgvs`) counts the operations the grant's scopes allow but its operation snapshot, its client pin or the server ceiling block, names none of them, keeps inferred grant age apart (`intent_unknown` without catalog provenance), and builds host commands only from the verifier's principal. No worker probe or per-tool database query during discovery (one audit read for provenance when a snapshot excludes operations). Shared administration guidance explains separate owner authority, links the MCP admin runbook, and exposes an admin URL only for a configured credential-free HTTP MCP endpoint. Stdio never infers an HTTP address. D4 in band: `grantBlockedNotice(diagnosis, {refused})` builds the `grant_blocked_operations` notice (blocker counts, grant age apart, missing scope only when refused) and `grantRepairAction` the host-owned repair (preview argv, `then` apply, verify = doctor `grant_new_ops_available` or `whoami`; server ceiling alone → the read-only doctor check). Dispatch (`grantBlockedNotices`) delivers it once per (principal, session) or, stateless, per (principal, grant revision).+- `src/commands/mcp.ts` + `mcp-provision.ts` + `harness-connect.ts` — Host-side grant/preview/CAS and recoverable private delivery, followed by installation inside the intended harness. Codex, Claude Code and opencode installs (`src/core/harness/install.ts`) store the bearer token inline in the harness config; `inlineTokenReceipt` adds `token_storage`, `config_path`, `renew_command`, `if_exposed` (invalidate-tokens preview/apply, renew, reload; `renew_command` carries `--fresh-token` for renewable handoffs so it always exchanges a new token) and a `token_warning` when a Git working tree would commit the file, and `harness-connect.ts` repeats them on stderr in human mode without printing the token (#5775; `test/harness-token-receipt.test.ts`). Running PGLite hosts are administered through their authenticated API, never by opening a second database process. CLI status uses the delivery-aware exit verdict. `mcp-admin.ts` and `mcp-admin-http.ts` provide engine-free owner commands with explicit-file/env credential precedence, in-memory sessions, private native exports, versioned lifecycle previews, and safe stage/outcome/remedy receipts. Unknown mutation outcomes require inspection instead of automatic repetition. `runMcp` also dispatches `gbrain mcp expose` to `runMcpExpose` (dynamic import of `./mcp-expose.ts`; HELP carries the expose lines so the flag registry harvests them) and sets the CLI exit verdict from its returned code. `mcpNeedsEngine(args)` is true only for `grant` without an owner credential (`--admin-token-file` or `GBRAIN_ADMIN_BOOTSTRAP_TOKEN`) and outside help; `admin`, `expose`, and `verify` never open the database.+- `src/commands/mcp-expose.ts` — `gbrain mcp expose [--port N] [--funnel] [--surface] [--enable-dcr] [--no-tailscale] [--no-service] [--no-install] [--force] [--dry-run] [--yes] [--json]` / `--status` / `--remove`: publishes `gbrain serve --http` on the user's Tailscale tailnet (Serve by default, Funnel only with the explicit flag) and keeps it running as a user service. `runMcpExpose(args, deps?)` returns the exit code (0 done, 1 failed, 2 needs `--yes`, the prompt was declined, or a step is pending — a tailnet feature to enable, Tailscale login, tailnet certificate). Arg validation via `validateHarnessArguments` (exclusive pairs `--status`/`--remove`, `--funnel`/`--no-tailscale`, `--dry-run`/`--status`); the help text names every flag and the `verify.local` / `verify.tailnet` checks. Ordered named checks — `plan` (platform, execution environment, engine kind from `loadConfig()`; thin clients are refused with "run on the brain host"; `engine === 'unknown'` — no config or an unreadable one — without `--no-service` is refused as `no_brain_config` / exit 1 with next action `gbrain init` BEFORE consent, because a service around a missing brain only crash-loops, while `--dry-run` still prints the plan with the refusal marked and exits 0; on a PGLite engine `deps.pgliteHolder` (default `probeLivePgliteHolder` from `src/core/bootstrap/uninstall.ts`, a read-only lock-file probe) is consulted with `cfg.database_path`, and a live holder that is not our own managed service — receipt present with `service.state` `running`/`loaded` — adds a `Lock` plan line plus a `pglite_lock` check with status `warn` (never a stop); `--no-tailscale` over an existing receipt whose `tailscale.dns_name` is set (a live Serve/Funnel mapping) is refused BEFORE consent as `tailscale_receipt_present` / exit 1 with next actions `gbrain mcp expose --remove --yes` and the re-run without the flag — `--dry-run` marks it `WOULD BE REFUSED`; then probes `127.0.0.1:<port>` with `probeOccupied(d, port, url)` — occupied when EITHER the injectable `deps.tcpProbe` (default `defaultTcpProbe`, one `node:net` connect, socket destroyed on every outcome; true on connect, false on refusal / timeout / throw) accepts a TCP connect OR the `/health` fetch RESOLVES with ANY status (2xx, 404, 500), so a non-HTTP listener counts too; only both rejecting is free — and refuses a foreign listener with no receipt claiming that port as `foreign_listener` BEFORE anything is published unless `--no-service`; the message names the interrupted-run escape hatch `gbrain mcp expose --remove --yes`; `probeHealth` (`res.ok`) stays the bar for `verify.local` / `verify.tailnet` / `--status`), `consent` (shared `confirmOrFinish` for publish and `--remove`: one stderr y/N prompt on a TTY; declining is `pending` / exit 2 / `declined` with "Nothing changed. Re-run with --yes to confirm."; non-interactive without `--yes` prints the plan and exits 2 / `confirmation_required`; every re-run hint is rendered by `rerunCommand(opts)` — the user's publish flags + `--yes`), `tailscale.binary` (install plan: brew cask on macOS — then `open -a Tailscale` and a bounded poll of `tailscale status --json`, up to 20 attempts 1s apart, breaking as soon as the app's daemon answers and otherwise falling through to the login step's daemon-not-running handling — official installer on Linux, `--no-install` → exit 1), `tailscale.login` (Linux `sudo tailscale set --operator=<user>` non-fatal then flagless `sudo tailscale up` — `sudo` is put in front of the binary ONLY when `isSystemTailscaleBinary(binary)` holds (one of `TAILSCALE_BINARY_CANDIDATES`, literally or via `realpathSync`); a user-writable `tailscale` found on PATH stops the step as `pending` / exit 2 / `tailscale_login_manual` with the message "tailscale at <path> is not a system install, so gbrain will not run it with sudo. If you trust that binary, sign in yourself (this runs it as root): `sudo <path> set --operator=$USER && sudo <path> up`, then re-run: <rerun>" — the command is `tailscaleManualLoginCommand(binary)`, naming the discovered path shell-quoted, because a binary outside sudo's `secure_path` is exactly this case — and never spawns `sudo`; macOS `tailscale up`; bounded wait via `GBRAIN_TAILSCALE_LOGIN_TIMEOUT_MS`), `tailscale.identity` (MagicDNS name → `public_url`; pre-checks so `tailscale serve`/`funnel` — which wait interactively instead of failing when a feature is off — are never started blind: empty `CertDomains` → `pending` / exit 2 / `tailscale_https_not_enabled` with `TAILSCALE_ADMIN_DNS_URL`; `--funnel` with `funnelCapable === false` → `tailscale_funnel_not_enabled` with the ACL admin + Funnel KB URLs; `funnelCapable === null` proceeds), `tailscale.publish` (reads the serve config through `readServeView`, which FAILS CLOSED — it returns `{ view: ServeStatusView | null, stderr, status }` with `view: null` when `tailscale serve status --json` exits non-zero / is killed (`status: null`) or when stdout is not a JSON object per `parseServeStatusStrict`; an empty document / `{}` / `null` from exit 0 is the legitimately empty view — a null view before `--bg` is described once by `describeServeReadFailure` (`{ kind, detail, fix }` from one `classifyTailscaleError` call), records `tailscale.publish` = fail and returns exit 1 with reason `tailscale_<kind>` without publishing; a null view after `--bg` is `tailscale_publish_unconfirmed` naming the read failure; refuses a `/` handler proxying a different port, a foreground session or a raw TCP forward without `--force` as `foreign_serve_config` — `next_actions` says `tailscale serve status`, only `message` explains `--force`; `PUBLISH_TIMEOUT_MS` (60s) bounds `--bg`, `SERVE_OFF_TIMEOUT_MS` (30s) every `--https=443 --set-path=/ off` and `STATUS_READ_TIMEOUT_MS` (15s) both status reads; a `status: null` timeout is `unknown` with a run-by-hand hint; stderr classified by `classifyTailscaleError` as the second line of defense; switching our own handler's shape pre-clears ONLY in the funnel → tailnet direction (`funnel --https=443 --set-path=/ off` before `serve --bg`, because `serve --bg` over a Funnel mount keeps `AllowFunnel`; tailnet → funnel is one atomic `funnel --bg`), and when that pre-off was followed by a failed publish (non-zero, timeout, or unconfirmed) `restorePrevious` best-effort re-publishes the previous shape with `tailscaleServeArgv(port, { funnel: true })`, re-reads the view, and appends to the `tailscale.publish` detail whether "the previous funnel handler was restored" or "could NOT be restored"; the existing receipt is never touched on those paths), `admin_token` (ensure the 0600 token file, never printed), `service` (launchd / systemd user unit / `manual` fallback with the exact foreground and `nohup` commands; a `--no-service` re-run carries the existing receipt's service block unchanged and does not rewrite the wrapper; `service_install_failed` still writes the receipt with `service.state: 'stopped'` before exit 1 so `--status`/`--remove` can clean up the published handler; the receipt is ALSO written right after a successful service step — service state as probed at that moment — before verify runs, so a kill during verify always leaves `--status`/`--remove` something to find), `verify.local` (wall-clock `/health` polling up to 20s, timeout → `warn`, exit 2, `verify.tailnet` skipped), `verify.tailnet` (up to 30s, `pending` is exit 2 — EXCEPT when the last probe's rejection was a name-resolution failure per `mcp-expose-probe.ts`: Bun's `fetch` rejects an unresolvable host and a refused connection with the same "Unable to connect. Is the computer able to access the url?" / `ConnectionRefused`, so after a rejected fetch the URL's hostname (never an IP literal or `localhost`) is handed to `deps.lookup` — default `dns.promises.lookup`, bounded by the probe timeout — and a rejection with code `ENOTFOUND` / `EAI_AGAIN` / `EAI_NONAME` / `EAI_NODATA` / `DNS_ENOTFOUND` (or a message naming one) is the verdict, the fetch-message regex staying a secondary hint; a name that resolves but does not answer stays `pending`: then the check is `warn` with `unresolvedDetail(dnsName)` — "this host cannot resolve <name> (MagicDNS may be off here: `tailscale set --accept-dns=true`); devices that do resolve it may already reach the server" — and the run exits 0, since this host's resolver says nothing about the server), `receipt` (rewrites the early receipt with the settled state — the supervisor is re-probed once verify.local ran — keeping `created_at`). The admin-token, service and verify steps run inside one try: a THROW there after this run's `--bg` succeeded but BEFORE the early receipt is rolled back by `rollbackAfterThrow(d, s, opts, published, error, receiptWritten)` — the fresh handler is turned off again with `tailscaleServeOffArgv({ funnel })` only when no `/` handler for our port existed before the run (a pre-existing one is left in place), a `rollback` check records what happened — "turned off again" is claimed only when a re-read of the serve view after an exit-0 `off` no longer shows our port; an exit-0 `off` whose re-read still shows it is a `warn` "NOT turned off (… the handler is still present)", an unreadable re-read is a `warn` "state unknown", and an `off` that exits non-zero or throws is a `warn` whose message says the handler was NOT turned off — no receipt is written, and the error is re-thrown so the outer catch reports `mcp_expose_failed` with a message naming the handler state; once the early receipt is on disk (`receiptWritten`, checked first) a throw tears nothing down (`rollback` = skipped pointing at `--status` / `--remove --yes`), because the receipt makes everything findable (the non-throwing `service_install_failed` path keeps its partial receipt). Success banner and `next_actions` gate the local-agent line on the engine: Postgres → `gbrain bootstrap harness --yes --port N`; PGLite → pre-mint (`gbrain auth create … --scopes read,write` before the service runs) + `--token`, or the scoped `mcp grant … --url http://127.0.0.1:N/mcp --admin-token-file …` + `gbrain connect … --install` path, and "host-side commands fail with `live_serve` — administer through the running server". `--json` emits one stdout document `{ status, receipt, checks[], next_actions, reason?, message? }` with prose on stderr; every `inherit` subprocess redirects its stdout to stderr under `--json`. `--status` and `--remove` read the receipt through `readExposeReceipt`'s shape guard (a partial receipt is `not_exposed` / "nothing to remove", never a crash) and execute the tailscale binary from `resolveReceiptBinary`: the receipt's recorded path is honored only when it still exists AND is either what `findTailscaleBinary` finds now or one of `TAILSCALE_BINARY_CANDIDATES`, otherwise discovery wins — a path in a receipt is data, never a licence to run it. the probes — `probeHealth` (`res.ok`), `probeOccupied` (any response, or an accepted TCP connect), the bounded never-throwing `tryFetch` → `FetchOutcome { res, unresolved }`, `pollHealth` → `{ ok, unresolved }` with the LAST probe's resolution verdict, `unresolvedDetail`, `defaultTcpProbe`, `defaultLookup` — live in `src/commands/mcp-expose-probe.ts` and take the narrow `ProbeDeps` slice of the resolved deps (`fetch`, `tcpProbe`, `lookup`, `now`, `sleep`, `healthIntervalMs`); `defaultTcpProbe` is re-exported here so its import site never moved; `isLiveService(state)` is the one definition of "the supervisor reports our service" (`running` or `loaded`) used by the lock-holder exemption, the service check, `--status` and both `--remove` paths; `serviceLabel` builds on `serviceKindLabel` (`launchd <label>` / `systemd (user) <unit>`). `--status` runs its four independent probes (serve config, supervisor state, local and tailnet `/health`) concurrently with `Promise.all` and still reports the checks in the fixed order `receipt`, `tailscale.publish`, `service`, `verify.local`, `verify.tailnet`; an unreadable serve config (null view) is a FAILED `tailscale.publish` check / exit 1, never "handler present"; a tailnet `/health` rejected for name resolution is `verify.tailnet` = warn (same `unresolvedDetail`), not `pending`, and does not by itself make the exit non-zero. `--status` with NO receipt is `runStatusWithoutReceipt`: it runs the read-only `probeLeftovers(d, opts.port)` (`--port` is honored) and, when the wrapper, the plist / unit or a live service, or a `/` handler on `:443` proxying the port is found, emits one `warn` check per artifact (`receipt`, `service`, `tailscale.publish`, `files`), pushes `recoveryCommand(port, force)` (`gbrain mcp expose --remove --yes`, `--force` only when a handler stands alone with no wrapper / service corroborating it, `--port N` when non-default) to `next_actions`, and finishes `error` / exit 1 / `leftovers_without_receipt` (also under `--json`); an unreadable serve status alone is a caveat warn, not a leftover; nothing found keeps the `not_exposed` answer (exit 0, `--json` exit 2). `--remove` (consent; decline is `pending` / exit 2) probes the supervisor and removes a service that exists even when the receipt says skipped — `recordServiceUninstall` prints the uninstall notes, and when `launchdBootoutFailed(result)` (a `launchctl bootout failed: …` / `unload failed: …` note, i.e. a non-"not loaded" failure) the `service` check is `warn` pointing at `launchctl print gui/$(id -u)/com.gbrain.serve` and "the launchd job (bootout failed)" is added to "Left in place"; it returns the one-line service summary quoted below — then clears only gbrain's own serve/funnel handler through `turnOffOurHandler` (Funnel off first; every `off` is `--https=443 --set-path=/ off`, scoped to our `/` mount; the serve config is re-read only after an `off` command ran, otherwise the view already read is reused; a failed re-read is reported as `unknown` — a warn, never "gone"; a foreign port on `:443` gets "nothing to turn off"). `--remove` never reports success while our handler survives: when `turnOffOurHandler` returns `remaining` as a handler (`tailscale.publish` = fail) or `'unknown'` (= warn), `finishHandlerNotRemoved` keeps the receipt AND the wrapper (mirroring the unreadable-status branch), records `receipt` = skipped "kept: …", pushes `tailscale serve status` + the re-run to `next_actions`, says which service outcome already happened, and exits 1 with reason `handler_not_removed`; `--remove` never runs `tailscale serve reset`, never uninstalls or logs out, keeps the admin token unless `--force` (deleted through the same `unlinkQuietly` as the wrapper and receipt), and unlinks the wrapper / receipt / token ONLY when the path's directory is the serve directory — a receipt path elsewhere is left untouched and named in "Left in place" (also in the plan). The receipt's recorded `plist_path` / `unit_path` are data, never a licence: `uninstallServeService` is always handed the computed `d.plistPath` / `d.unitPath` (home + the fixed label / unit name), and a recorded path that differs is not touched and is named in "Left in place" as "recorded in the receipt but not the expected location". A null serve view during `--remove` fails closed: `tailscale.publish` = fail "could not read tailscale serve status; handler left as is", reason `tailscale_serve_status_unreadable`, exit 1, and the receipt AND wrapper are kept so a re-run finishes the job. With NO receipt, `runRemoveWithoutReceipt` recovers from what is on disk through the same `probeLeftovers` `--status` uses (`wrapperPath(serveDir)`, the launchd plist / systemd unit or a `running`/`loaded` service, a `/` handler on `:443` proxying `opts.port` — `--port` may accompany `--remove`, default 3131); inside it the supervisor chain (`probeServiceTarget` → `serveServiceState`) and the `readServeView` read run concurrently under `Promise.all` (the binary is resolved synchronously first) and the plan / checks are emitted in the fixed order afterwards; the re-run hints come from `recoveryCommand`. The handler is turned off only with corroborating gbrain evidence — the wrapper present, our unit/plist present, or the supervisor reporting our service live — or with `--force`, because another tool may proxy `:443` to the same port: a handler standing alone is reported (`tailscale.publish` = warn naming the proxy target and `--force`, next action `gbrain mcp expose --remove --yes --force`) and left in place on the "not exposed — nothing to remove" exit-0 path; with `--force` the plan line says so. Otherwise it prints a "Recovering without a receipt" plan (`receipt` check = warn), takes consent as usual, removes exactly those artifacts (service via the supervisor — the same `recordServiceUninstall` bootout-failure warn applies — wrapper, the handler — funnel off first when `AllowFunnel` lists the host), leaves the admin token file, and finishes `removed` with reason `recovered_without_receipt`; a handler that survives the `off` is `handler_not_removed` / exit 1 here too, with the wrapper deliberately KEPT as the corroboration the re-run needs (`files` = skipped "kept: the wrapper"; the re-run hint carries `--force` when no wrapper is left); an unreadable serve status on this path (gbrain evidence present, `serveUnreadable` set) fails closed exactly like the receipt path — the service, when found, is still uninstalled, the plan says the handler cannot be checked and the wrapper is kept, `tailscale.publish` = fail "…; handler state unknown", `files` = skipped "kept: the wrapper" (or "nothing (no wrapper was found)"), `next_actions` = `tailscale serve status --json` + the recovery command (`--force` when no wrapper is left), exit 1 with reason `tailscale_serve_status_unreadable` and message "could not read tailscale serve status; handler state unknown"; when nothing of ours is found the answer stays "not exposed — nothing to remove", exit 0 (an unreadable serve status is then only the caveat warn — there is nothing to keep and a handler alone would not be touched anyway). Every filesystem/exec effect goes through injectable deps so tests run against a fake runner in a tmpdir. Success guidance separates owner login, native OAuth registration, and machine grant/install. It uses the expose-managed owner file only when installing or keeping that service; publication with `--no-service` and no managed service instead requires the existing server's independently configured owner credential. Publishing receipts and health checks do not certify client authorization or native activation.+- `src/commands/mcp-expose-probe.ts` — the health / occupancy probes `mcp-expose.ts` runs, peeled out behind a narrow `ProbeDeps` (`fetch`, `tcpProbe`, `lookup`, `now`, `sleep`, `healthIntervalMs`) rather than the whole resolved-deps bag: `tryFetch(d, url, timeoutMs)` (one bounded fetch, `redirect: 'manual'`, never throws → `FetchOutcome { res, unresolved }`), `probeHealth` (`res.ok` — the `verify.*` / `--status` bar), `probeOccupied` (an accepted TCP connect OR any HTTP answer — the foreign-listener bar), `pollHealth` (wall-clock budget from `d.now()`, per-probe timeout `min(1500, remaining)`, attempt cap `ceil(budget / healthIntervalMs)` as the frozen-clock backstop, `unresolved` = the LAST probe's verdict), `unresolvedDetail(dnsName)`, `defaultTcpProbe` (one `node:net` connect, socket destroyed on every outcome) and `defaultLookup` (local RFC 6761 `.invalid` rejection, otherwise `dns.promises.lookup`). The name-resolution verdict is the reason the module exists: Bun's `fetch` rejects an unresolvable host with the SAME error as a refused connection ("Unable to connect. Is the computer able to access the url?", code `ConnectionRefused`), so a message match alone never fires in production. After a rejection `nameUnresolved` takes `new URL(url).hostname`, skips IP literals (`isIP`) and `localhost`, and otherwise awaits `d.lookup(host)` raced against the probe's `timeoutMs` (a lookup that does not answer in time proves nothing; the race keeps a late rejection handled); `isUnresolvedLookupError` classifies the lookup rejection by `code` — `ENOTFOUND`, `EAI_AGAIN`, `EAI_NONAME`, `EAI_NODATA`, `DNS_ENOTFOUND` (a resolver outage counts: the verdict is about THIS host) — or by those tokens in its message, and the fetch-message regex (`ENOTFOUND|getaddrinfo|EAI_AGAIN|failed to resolve|Unable to connect.*resolve`) is OR-ed in afterwards as the secondary hint. Tests inject a fake fetch, TCP probe and resolver (`test/mcp-expose.test.ts`; the fixture's default `lookup` resolves every name, reserved-name and label-boundary cases do not query external DNS, and the real `defaultLookup` resolves localhost). `statusOnlyHealthDetail(port)` reads this host's live status-only marker for the port so `verify.local` reads "status-only (<reason>)" instead of a timeout or "no answer".diff --git a/docs/architecture/key-files/google-and-loops.md b/docs/architecture/key-files/google-and-loops.mdindex fd8140f346..217b19e2e0 100644--- a/docs/architecture/key-files/google-and-loops.md+++ b/docs/architecture/key-files/google-and-loops.md@@ -27,7 +27,7 @@ Historical Gmail repair selects explicit nested MIME metadata fields, excluding- `src/core/google/google-clients.ts` — hand-rolled Gmail/Calendar/People REST clients (house style, no googleapis dependency): auth via any `GoogleAccessProvider` (vault-backed `GoogleTokenProvider` by default), 401 → forceRefresh + single retry, Retry-After honored (delta-seconds AND http-date), 403 disabled API → `GoogleApiDisabledError` and insufficient scope → `scope_missing` ([API access](google-api-access.md)), uniform pageToken pagination with a safety cap, `fetchImpl` injectable for tests. `extractCalendarMethod(part)` walks the MIME tree for a `text/calendar`/`application/ics` part and reads the iCalendar `method=` parameter from the PART's own `Content-Type` header (`headers[]` on nested parts with `format=full` — Gmail's `MessagePart.mimeType` is the BARE media type, so a mimeType-only parse would read '' for every real invite and silently downgrade the structural signal to the subject fallback); a mimeType that still carries params is the fallback parse; a bare `.ics` filename with a non-calendar MIME type claims nothing. `CalendarClient.listEvents({calendarId})` sweeps one calendar (default `DEFAULT_CALENDAR_ID`). A People request with a nonempty `syncToken` maps HTTP 400 to `GoogleCursorExpiredError` only for typed `google.rpc.ErrorInfo` reason `EXPIRED_SYNC_TOKEN` or a message beginning `Sync token [is] expired`; any other 400 on such a request is a `GoogleSyncTokenRejectedError` (a `CredentialError('upstream')` subclass the contacts sweep alone treats as cursor-invalid, #6324); a connections 400 with a `pageToken` is `GoogleCursorExpiredError` (#8906, `listConnectionsPage` reads one page); other initial-list requests and APIs remain plain upstream failures. `CONTACT_PERSON_FIELDS` (`names,emailAddresses,organizations,phoneNumbers,memberships`) is the one People field mask, repeated on every page of a list; `ContactData` carries deduplicated E.164 `phones` and user-group `groups` (`{id, name: null}`, system groups dropped), and `listContactGroups()` walks `contactGroups` for at most ten 1000-row pages and reports `complete: false` past that. The Gmail mapper also captures `precedence` (lower-cased), `listId` (present or not) and `replyTo` for the automated-mail loop rule (#5012). A 403 that is not API-disabled, rate-limit or quota is `GoogleForbiddenError` (still `CredentialError` `upstream`); `calendarUnreadableStatus(e)` maps it and a 404 `GoogleCursorExpiredError` to 403/404, and `CalendarClient.probeCalendar(id)` is one `maxResults=1` read. Pinned by injected-response tests in `test/google-clients.test.ts`, `test/contacts-phone-only-groups-6324.test.ts` and `test/google-source-reconcile.test.ts`, not live-provider validation.- `src/core/google/gmail-categories.ts` — `BULK_CATEGORY_LABELS` (`CATEGORY_PROMOTIONS`/`SOCIAL`/`FORUMS`) and `hasBulkCategory`, the one list both open-loop lanes read (#5103): `loopExtractionEligibility` returns `bulk_category` and `detectThreadLoop` withholds an inbound open, in both cases unless the owner wrote a substantive message in the thread; `CATEGORY_UPDATES` is deliberately not in it. `isNoiseSender` additionally matches `GOOGLE_SYSTEM_SENDERS` (the Meet notes digest address) by equality only.- `src/core/google/google-render.ts` — `isPositivelyAutomated(meta)` (#5012): `Precedence: bulk|list|junk`, a `List-Id`, a noise From or a noise Reply-To. Pure render functions (`{relPath, markdown}` out; no I/O, no engine): thread pages under `emails/YYYY/MM/` (type email), events under `calendar/YYYY/MM/` (type meeting), contacts under `people/` (type person). Gmail deep links are code-generated via the typed `emailCitation` scaffold, never LLM-composed. The noise/signature rules `recipes/email-to-brain.md` specifies as prose for agent-authored collectors are implemented here — keep the recipe and this module in sync. `isCalendarSystemMail({calendarMethod, subject})` gates BOTH loop detectors: the PRIMARY signal is a `calendarMethod` in the `CALENDAR_METHODS` allowlist (RFC 5546 — REQUEST, REPLY, CANCEL, PUBLISH, COUNTER, DECLINECOUNTER, REFRESH, ADD; case-insensitive); an empty or unrecognised method is NOT a stamp and falls to the subject fallback, which is anchored to the start of the subject, refuses any Re:/Fwd: prefix, and matches only Calendar's OWN localised headers (`Invitation:`, `Updated invitation:`, `Accepted:`, `Declined:`, `Tentative:`, `Canceled event:` + localised equivalents) — a generic word like `Notification:` is a human/vendor subject and never matches. `renderThreadPage` stamps `participants:` (every address on the thread) AND `senders:` (sorted unique message AUTHORS only — the list `loops mute sender` gates on, so muting one person cannot silence a whole group thread). `renderPersonPage` (#6324) renders a contact with emails OR phones: `emails:` always, `phones:` and `groups:` (names, or the raw `contactGroups/<id>` when unresolved) only when non-empty, phones never in `aliases`; a contact with neither name nor email lives at `contactIdSlug` = `<dir>/contact-<sha8(resourceName)>`, which `personSlugFromContact` returns for a phone-only nameless contact and the sweep's tombstone path lists as a delete candidate. Pinned by `test/google-render.test.ts` and `test/contacts-phone-only-groups-6324.test.ts`.-- `src/core/google/google-source.ts` — the Google API source sweep. Unmanaged mode materializes Markdown under the source directory and imports through the standard chunks/aliases/links pipeline; managed mode uses journaled connector admission. Sweep order contacts → calendar → gmail: alias rows must exist before the loop detector resolves counterparties. Per-service independent cursors: contacts/calendar syncToken commits only after that service's sweep left no failing item that is not yet held (410 GONE drops the token and re-runs windowed); GBRA-130 A-3: contacts and events go through connector item holds (`contact:`/`event:` keys), so one failing item no longer pins the token or stops Gmail (`test/pathological/a3-google-items.test.ts`); gmail delta rides history.list with an expired-history windowed fallback, and it and the held-thread retries settle a thread older than `cutoffMs` (`now - g_history_days`) without a page unless one exists (`test/google-gmail-delta-window-8482.test.ts`); the INITIAL backfill drains newest→oldest with a batch-committed floor cursor so a killed backfill resumes at the floor, and the historyId anchor is captured BEFORE the backfill so the delta lane takes over with zero gap (overlap re-renders are idempotent). Emits the `sync.google_materialize` progress phase (docs/progress-events.md). Access resolves per source config: the vault (default), a token-printing command (`g_access: command` — gog/gcloud/gateway; identity entry synthesized, scope preflight trusts the configured services, send-as aliases fetched live best-effort), or a named env var (`g_access: env`). Secrets never land in `sources.config` (only the command/env NAME does). Honesty invariants: `last_sync_at` is gated on the GMAIL sweep's success (it feeds `gbrain waiting`'s staleness gate; a gmail sweep with real thread failures must not advance it); contacts/calendar failures mark the run `partial` but do not block the stamp, and a source without gmail in its services stamps unconditionally. A thread whose fetch fails on consecutive sweeps lands in the poison ledger and is skipped (steady-state runs honor the ledger; `--full` retries with a fresh one), so one bad thread can't wedge the sync while a poison-skip alone doesn't count as failure. Contact reconcile resolves by contact resourceName (DB lookup by contact id FIRST): deletion tombstones carry only `resourceName + deleted` (no names — slug derivation yields null) and a renamed contact derives a DIFFERENT slug, so both must land on the existing page by id, never by slug. The calendar sweep binds its sync token to its calendar: `sweepCalendar` compares `state.calendar_id` (legacy state without it is treated as primary's) with the configured `calendarId`; on a mismatch it logs `[google] calendar changed (<old> → <new>)`, discards the token and takes the windowed first-sync path (no `syncToken` on the wire), and a freshly banked token stores the calendar id beside it — pairing a re-pointed source with the previous calendar's cursor would import a foreign delta. Pages from the previous calendar are not reconciled on the switch (logged; a filed follow-up). `enqueueLoopsExtraction` enqueues EVERY eligible thread (newest first) under a waiting-depth budget `LOOPS_EXTRACT_ENQUEUE_CEILING − waiting` that counts only THIS source's waiting `loops_extract` jobs (`data->>'sourceId'`), so one account's stalled backlog cannot pin another source's budget at 0; overflow is a logged deferral (a deferred thread re-candidates when it changes) and a failed probe fails open. The budget probe counts PENDING rows — `status IN ('waiting','delayed','active')` — so a retry backlog parked in `delayed` during a flapping provider cannot stack past the ceiling. With no chat provider (`isAvailable('chat')` false) the enqueue is skipped and one stderr line per sweep names the reason and the count; pages still import and the threads re-candidate on their next touch or a `--full` sweep. Managed Google API sync uses journaled connector checkpoints; an unbound source is explicitly `connector_database`, while a bound source publishes canonical files. Identity-query storage failures do not become successful absence or advance the checkpoint. Unsupported Git/dry-run flags refuse before credentials/network; legacy materialization remains the unmanaged path. FILE MODES (every write, both paths): `writeGoogleState` writes `.google-source.json` through `atomicWriteFileSync(..., { mode: 0o600 })` under `mkdirPrivate(dir)`; a corrupt state file is chmod-ed 0600 and then renamed to `.corrupt`, and if either step fails stderr names the path, the failed step, the exposure and the fix (`chmod 600 <path>` or delete it) while the sync continues with empty cursors. A legacy page goes through `writePrivateTemp`: a stale `<page>.tmp` is removed with `lstat` (never followed; a stale `.tmp` directory fails that item with `Stale temporary path <path> is a directory; remove it and re-run the sync.`), the temp file is created `wx` at 0600 and fchmod-ed past the umask, imported, then renamed over the page; page directories come from `mkdirPrivate(dirname(page), cfg.dir)`. 0600 is reasserted on every rewrite (unchanged pages are not rewritten). Managed pages get the same modes through `publishMode` (see the persistence coordinator). Mode assertions are skipped on win32. Tests: `test/google-file-modes.test.ts` (child process under umask 0000, `test/helpers/google-file-modes-child.ts`). The loops enqueue runs on every non-aborted sweep in both persistence modes (`--no-extract` gates only the inline link/timeline extract), logs every skip reason and reports `loops_enqueue { enqueued, deferred, skipped_reason }` in the sync result; job payloads carry the page revision (`newestMs`). After the delta and item-hold passes the sweep seeds and settles grace holds, and a managed sweep runs the 30-day catch-up (both in `loop-catchup.ts`); a partial managed run publishes that state with its item holds (`publishHolds` extra), never the Gmail cursor.+- `src/core/google/google-source.ts` — the Google API source sweep. Unmanaged mode materializes Markdown under the source directory and imports through the standard chunks/aliases/links pipeline; managed mode uses journaled connector admission. Sweep order contacts → calendar → gmail: alias rows must exist before the loop detector resolves counterparties. Per-service independent cursors: contacts/calendar syncToken commits only after that service's sweep left no failing item that is not yet held (410 GONE drops the token and re-runs windowed); GBRA-130 A-3: contacts and events go through connector item holds (`contact:`/`event:` keys), so one failing item no longer pins the token or stops Gmail (`test/pathological/a3-google-items.test.ts`); gmail delta rides history.list with an expired-history windowed fallback, and it and the held-thread retries settle a thread older than `cutoffMs` (`now - g_history_days`) without a page unless one exists (`test/google-gmail-delta-window-8482.test.ts`); the INITIAL backfill drains newest→oldest with a batch-committed floor cursor so a killed backfill resumes at the floor, and the historyId anchor is captured BEFORE the backfill so the delta lane takes over with zero gap (overlap re-renders are idempotent). Emits the `sync.google_materialize` progress phase (docs/progress-events.md). Access resolves per source config: the vault (default), a token-printing command (`g_access: command` — gog/gcloud/gateway; identity entry synthesized, scope preflight trusts the configured services, send-as aliases fetched live best-effort), or a named env var (`g_access: env`). Secrets never land in `sources.config` (only the command/env NAME does). Honesty invariants: `last_sync_at` is gated on the GMAIL sweep's success (it feeds `gbrain waiting`'s staleness gate; a gmail sweep with real thread failures must not advance it); contacts/calendar failures mark the run `partial` but do not block the stamp, and a source without gmail in its services stamps unconditionally. A thread whose fetch fails on consecutive sweeps lands in the poison ledger and is skipped (steady-state runs honor the ledger; `--full` retries with a fresh one), so one bad thread can't wedge the sync while a poison-skip alone doesn't count as failure. Contact reconcile resolves by contact resourceName (DB lookup by contact id FIRST): deletion tombstones carry only `resourceName + deleted` (no names — slug derivation yields null) and a renamed contact derives a DIFFERENT slug, so both must land on the existing page by id, never by slug. The calendar sweep binds its sync token to its calendar: `sweepCalendar` compares `state.calendar_id` (legacy state without it is treated as primary's) with the configured `calendarId`; on a mismatch it logs `[google] calendar changed (<old> → <new>)`, discards the token and takes the windowed first-sync path (no `syncToken` on the wire), and a freshly banked token stores the calendar id beside it — pairing a re-pointed source with the previous calendar's cursor would import a foreign delta. Pages from the previous calendar are not reconciled on the switch (logged; a filed follow-up). `enqueueLoopsExtraction` enqueues EVERY eligible thread (newest first) under a waiting-depth budget `LOOPS_EXTRACT_ENQUEUE_CEILING − waiting` that counts only THIS source's waiting `loops_extract` jobs (`data->>'sourceId'`), so one account's stalled backlog cannot pin another source's budget at 0; overflow is a logged deferral (a deferred thread re-candidates when it changes) and a failed probe fails open. The budget probe counts PENDING rows — `status IN ('waiting','delayed','active')` — so a retry backlog parked in `delayed` during a flapping provider cannot stack past the ceiling. With no chat provider (`isAvailable('chat')` false) the enqueue is skipped and one stderr line per sweep names the reason and the count; pages still import and the threads re-candidate on their next touch or a `--full` sweep. Managed Google API sync uses journaled connector checkpoints; an unbound source is explicitly `connector_database`, while a bound source publishes canonical files. Identity-query storage failures do not become successful absence or advance the checkpoint. Unsupported Git/dry-run flags refuse before credentials/network; legacy materialization remains the unmanaged path. FILE MODES (every write, both paths): `writeGoogleState` writes `.google-source.json` through `atomicWriteFileSync(..., { mode: 0o600 })` under `mkdirPrivate(dir)`; a corrupt state file is chmod-ed 0600 and then renamed to `.corrupt`, and if either step fails stderr names the path, the failed step, the exposure and the fix (`chmod 600 <path>` or delete it) while the sync continues with empty cursors. A legacy page goes through `writePrivateTemp`: a stale `<page>.tmp` is removed with `lstat` (never followed; a stale `.tmp` directory fails that item with `Stale temporary path <path> is a directory; remove it and re-run the sync.`), the temp file is created `wx` at 0600 and fchmod-ed past the umask, imported, then renamed over the page; page directories come from `mkdirPrivate(dirname(page), cfg.dir)`. 0600 is reasserted on every rewrite (unchanged pages are not rewritten). Managed pages get the same modes through `publishMode` (see the persistence coordinator). Mode assertions are skipped on win32. Tests: `test/google-file-modes.test.ts` (child process under umask 0000, `test/helpers/google-file-modes-child.ts`). The loops enqueue runs on every non-aborted sweep in both persistence modes (`--no-extract` gates only the inline link/timeline extract), logs every skip reason and reports `loops_enqueue { enqueued, deferred, skipped_reason }` in the sync result; job payloads carry the page revision (`newestMs`). After the delta and item-hold passes the sweep seeds and settles grace holds, and a managed sweep runs the 30-day catch-up (both in `loop-catchup.ts`); a partial managed run publishes that state with its item holds (`publishHolds` extra), never the Gmail cursor. An unmanaged `--dry-run` returns `connectorDryRunResult` before any credential read or provider call, and `runGitHubSync` does the same; a managed brain refuses `--dry-run`.- `src/core/google/calendar-window.ts` — which calendar events a google source keeps pages for: `[now - historyDays, now + futureDays]` (`g_future_days`, 1..3650, default `CALENDAR_HORIZON_DAYS` = 60; the parsed `futureDays` leaf exists only when the key is set, so an unset knob leaves every existing source's connector identity unchanged), checked by the sweep itself on every list because a syncToken delta cannot carry timeMin/timeMax. `CalendarSyncWindow` is built once per sweep: `side(start, end)` follows Google's rule (an event is `before` when it ends at or before the floor, `after` when it starts at or past the ceiling, unparseable dates stay `inside`); `coverageStartMs(horizon, listedWholeWindow)` says where the catch-up list for unchanged instances crossing the leading edge starts (none after a whole-window list, now for state without `calendar_horizon_ms`, the recorded horizon once the ceiling is a day past it); `startsInside` and `startsAfter` are the `--full` reconcile tests. `planCalendarPage` maps one listed event to a page change (a cancellation removes its page anywhere, aged-out history is left as it is, a page past the horizon is removed, otherwise write after removing a copy at an older path). `unlistedCalendarPages` returns sweep pages (with an `event_id`) starting inside the window that a complete `--full` list did not name; `staleCalendarPages` adds the sweep pages starting at or past the ceiling, which no windowed list can name (#5442), and is what the `--full` reconcile deletes through. `people-calendar-sweep.ts` (the contacts and calendar sweeps, peeled from `google-source.ts`) performs the changes with `importRendered`/`deletePageByRelPath`, discards the catch-up list's sync token, advances `calendar_horizon_ms` only after a list reached the ceiling, and sends reconcile deletes through the >200 mass-delete guard (a refusal marks the run partial). Its contacts cursor contract (#6324): `contacts_sync_token` and `contacts_person_fields` (the mask that minted it) commit together after the whole sweep, never on abort or import failure; a recorded mask other than `CONTACT_PERSON_FIELDS` (legacy state has none) drops the token for one full list; an expired or `GoogleSyncTokenRejectedError` token gets one full list, whose failure propagates with the token nulled; a full list with no replacement token nulls `contacts_sync_token` when the mask changed and keeps it otherwise. A full list (#8906) checkpoints `contacts_relist` per clean page, stops at `CONTACT_RELIST_PAGES_PER_RUN` (10) pages (not partial), resumes under the same mask, restarts once on a stale saved token, clears with the token. `resolveContactGroups` reads the directory once, when a listed contact first has a user group: a complete read replaces the `contact_groups` cache, an incomplete one merges and logs, a failed one falls back to it; unresolved groups render as raw ids. Pinned by `test/contacts-phone-only-groups-6324.test.ts` and `test/contacts-relist-checkpoint{-8906.slow,-managed-8906}.test.ts`; the migration-176 test in `test/connector-wave3.test.ts` asserts the resumed legacy token is not reused. Tests: `test/google-calendar-window.test.ts` (pure rules), `test/google-source-reconcile.test.ts` (calendar window suite).- `src/core/google/file-modes.ts` — detection and tightening for group/world-readable files gbrain wrote under a Google source directory outside `~/.gbrain` (inside it the 0700 home already protects them). `scanGoogleFileModes(engine, { sourceIds? })` reads non-archived Google sources, skips dirs inside the home (`outsideGbrainHome`, realpath-aware), and inspects only gbrain's own layout: `.google-source.json*` in the root, every recorded page `source_path` under `emails/`, `calendar/`, `people/` (malformed paths ignored), each page's `.tmp`, and the directories between the root and those pages. Each path is `lstat`-ed component by component (a symlink anywhere on the path, another owner, or the wrong file type is counted in `skipped`, never followed); an entry is loose when `mode & 0o077`. `tightenGoogleEntry(root, entry)` re-checks the path, opens the leaf `O_NOFOLLOW` (`O_DIRECTORY` for dirs), re-checks the owner on the fd and `fchmod`s `mode & ~0o077`, so a swap after the scan is refused, not followed; the user-chosen root is never in the candidate set. `googleFileModesPreviewCommand`/`googleFileModesApplyCommand` build the `gbrain repair google-file-modes --source <id> [--apply]` strings every surface prints. win32: scan returns nothing. Tests: `test/google-file-modes-repair.test.ts`.- `src/commands/google.ts` — `gbrain google connect|status|calendars|disconnect` (+ `setup` and `attachments` dispatch). Agent-first contract: every subcommand supports `--json` emitting `{ ok, status, next_action: { command?, user_message? }, error? }` (`calendars` adds `account` + `calendars[]` — id/summary/primary/accessRole — and carries the `sources add --calendar-id` template in `next_action.command`; it resolves a lone connected account, exits 2 when there are none or several without `--account`, and throws `not_connected` for an unknown `--account`); human copy the harness must relay verbatim is fenced in `[SHOW USER] ... [/SHOW USER]` blocks; secret intake is `--client-json <path|->` (preferred) / env `GOOGLE_CLIENT_ID`+`GOOGLE_CLIENT_SECRET` / TTY prompt, with raw argv flags accepted but documented last-resort; connect is an idempotent state machine (detects what exists, performs only the missing step — re-running is the documented fix for most errors). Credential commands are engine-free; `status` has a best-effort linked-sources listing, while `attachments backfill` requires the explicitly selected local managed brain. Funnel events append to `~/.gbrain/integrations/google/heartbeat.jsonl`; account addresses are hashed to a short non-reversible tag, never raw. The vault entry's `meta.scopes` records what Google ACTUALLY granted (the token response's `scope` — the consent screen lets users uncheck scopes; the requested set is only the fallback), which is what lets downstream preflights report `scope_missing` instead of opaque per-sweep 403s. `status` reports each linked source's calendar readability (`google-calendar-status.ts`, live probe unless `--no-probe`); an unreadable calendar makes the JSON `ok: false` and the exit 1.@@ -46,10 +46,4 @@ Historical Gmail repair selects explicit nested MIME metadata fields, excluding- `src/core/harness/registry.ts` — Canonical adapter identities, supported transports, credential-delivery mechanisms, guide links and dated evidence; legacy connection/register vocabularies derive their facts here. `scripts/build-harness-docs.ts` emits the user-facing adapter reference. A `manual` adapter such as `hermes` (stdio, `docs/mcp/HERMES.md`) installs as `pending` with its guide; no adapter claims a runtime-tested session without dated evidence.- `src/core/harness/credentials.ts` + `delivery.ts` + `install.ts` — Private credential handoff and host delivery journal, ownership-preserving native configuration and isolated thin launchers. A committed active client and matching current secret are prerequisites for recovery. Machine handoffs preserve optional POST/Basic authentication methods. Native setup is a distinct nested-client artifact; metadata reads never access journals or SDK client objects containing hashes. Configuration removal and server revocation are separate actions.-- `src/core/harness/oauth-setup.ts` + `client-setup.ts` — explicit client metadata projection, flow selection, native OAuth setup/private-file validation, and live-row-locked secret delivery recovery. Public PKCE needs no journal; confidential exports validate the retained secret against current registration, and machine exports discard cached tokens. Unknown/mixed flows refuse until an explicit supported flow is selected.-- `src/core/harness/capabilities.ts` + `src/mcp/capabilities.ts` — Shared effective-grant orientation for OAuth whoami and authenticated `gbrain://capabilities`. A stored client token lifetime outside 60 to 7,776,000 seconds (`AuthInfo.tokenTtlSeconds`) reports `token_ttl_invalid`, and the delegation repair template then includes a `--token-ttl <APPROVED_TTL_SECONDS>` choice, since every grant write validates the merged lifetime. The resource preserves the exact seven-tool surface; source, operation, scope, fence and server-gate restrictions remain enforced at dispatch. `grant_diagnosis` (shared with doctor `grant_new_ops_available` through `grantOperationGaps`, `grantAge` and `grantRescopeArgvs`) counts the operations the grant's scopes allow but its operation snapshot, its client pin or the server ceiling block, names none of them, keeps inferred grant age apart (`intent_unknown` without catalog provenance), and builds host commands only from the verifier's principal. No worker probe or per-tool database query during discovery (one audit read for provenance when a snapshot excludes operations). Shared administration guidance explains separate owner authority, links the MCP admin runbook, and exposes an admin URL only for a configured credential-free HTTP MCP endpoint. Stdio never infers an HTTP address. D4 in band: `grantBlockedNotice(diagnosis, {refused})` builds the `grant_blocked_operations` notice (blocker counts, grant age apart, missing scope only when refused) and `grantRepairAction` the host-owned repair (preview argv, `then` apply, verify = doctor `grant_new_ops_available` or `whoami`; server ceiling alone → the read-only doctor check). Dispatch (`grantBlockedNotices`) delivers it once per (principal, session) or, stateless, per (principal, grant revision).-- `src/commands/mcp.ts` + `mcp-provision.ts` + `harness-connect.ts` — Host-side grant/preview/CAS and recoverable private delivery, followed by installation inside the intended harness. Codex, Claude Code and opencode installs (`src/core/harness/install.ts`) store the bearer token inline in the harness config; `inlineTokenReceipt` adds `token_storage`, `config_path`, `renew_command`, `if_exposed` (invalidate-tokens preview/apply, renew, reload; `renew_command` carries `--fresh-token` for renewable handoffs so it always exchanges a new token) and a `token_warning` when a Git working tree would commit the file, and `harness-connect.ts` repeats them on stderr in human mode without printing the token (#5775; `test/harness-token-receipt.test.ts`). Running PGLite hosts are administered through their authenticated API, never by opening a second database process. CLI status uses the delivery-aware exit verdict. `mcp-admin.ts` and `mcp-admin-http.ts` provide engine-free owner commands with explicit-file/env credential precedence, in-memory sessions, private native exports, versioned lifecycle previews, and safe stage/outcome/remedy receipts. Unknown mutation outcomes require inspection instead of automatic repetition. `runMcp` also dispatches `gbrain mcp expose` to `runMcpExpose` (dynamic import of `./mcp-expose.ts`; HELP carries the expose lines so the flag registry harvests them) and sets the CLI exit verdict from its returned code. `mcpNeedsEngine(args)` is true only for `grant` without an owner credential (`--admin-token-file` or `GBRAIN_ADMIN_BOOTSTRAP_TOKEN`) and outside help; `admin`, `expose`, and `verify` never open the database.-- `src/commands/mcp-expose.ts` — `gbrain mcp expose [--port N] [--funnel] [--surface] [--enable-dcr] [--no-tailscale] [--no-service] [--no-install] [--force] [--dry-run] [--yes] [--json]` / `--status` / `--remove`: publishes `gbrain serve --http` on the user's Tailscale tailnet (Serve by default, Funnel only with the explicit flag) and keeps it running as a user service. `runMcpExpose(args, deps?)` returns the exit code (0 done, 1 failed, 2 needs `--yes`, the prompt was declined, or a step is pending — a tailnet feature to enable, Tailscale login, tailnet certificate). Arg validation via `validateHarnessArguments` (exclusive pairs `--status`/`--remove`, `--funnel`/`--no-tailscale`, `--dry-run`/`--status`); the help text names every flag and the `verify.local` / `verify.tailnet` checks. Ordered named checks — `plan` (platform, execution environment, engine kind from `loadConfig()`; thin clients are refused with "run on the brain host"; `engine === 'unknown'` — no config or an unreadable one — without `--no-service` is refused as `no_brain_config` / exit 1 with next action `gbrain init` BEFORE consent, because a service around a missing brain only crash-loops, while `--dry-run` still prints the plan with the refusal marked and exits 0; on a PGLite engine `deps.pgliteHolder` (default `probeLivePgliteHolder` from `src/core/bootstrap/uninstall.ts`, a read-only lock-file probe) is consulted with `cfg.database_path`, and a live holder that is not our own managed service — receipt present with `service.state` `running`/`loaded` — adds a `Lock` plan line plus a `pglite_lock` check with status `warn` (never a stop); `--no-tailscale` over an existing receipt whose `tailscale.dns_name` is set (a live Serve/Funnel mapping) is refused BEFORE consent as `tailscale_receipt_present` / exit 1 with next actions `gbrain mcp expose --remove --yes` and the re-run without the flag — `--dry-run` marks it `WOULD BE REFUSED`; then probes `127.0.0.1:<port>` with `probeOccupied(d, port, url)` — occupied when EITHER the injectable `deps.tcpProbe` (default `defaultTcpProbe`, one `node:net` connect, socket destroyed on every outcome; true on connect, false on refusal / timeout / throw) accepts a TCP connect OR the `/health` fetch RESOLVES with ANY status (2xx, 404, 500), so a non-HTTP listener counts too; only both rejecting is free — and refuses a foreign listener with no receipt claiming that port as `foreign_listener` BEFORE anything is published unless `--no-service`; the message names the interrupted-run escape hatch `gbrain mcp expose --remove --yes`; `probeHealth` (`res.ok`) stays the bar for `verify.local` / `verify.tailnet` / `--status`), `consent` (shared `confirmOrFinish` for publish and `--remove`: one stderr y/N prompt on a TTY; declining is `pending` / exit 2 / `declined` with "Nothing changed. Re-run with --yes to confirm."; non-interactive without `--yes` prints the plan and exits 2 / `confirmation_required`; every re-run hint is rendered by `rerunCommand(opts)` — the user's publish flags + `--yes`), `tailscale.binary` (install plan: brew cask on macOS — then `open -a Tailscale` and a bounded poll of `tailscale status --json`, up to 20 attempts 1s apart, breaking as soon as the app's daemon answers and otherwise falling through to the login step's daemon-not-running handling — official installer on Linux, `--no-install` → exit 1), `tailscale.login` (Linux `sudo tailscale set --operator=<user>` non-fatal then flagless `sudo tailscale up` — `sudo` is put in front of the binary ONLY when `isSystemTailscaleBinary(binary)` holds (one of `TAILSCALE_BINARY_CANDIDATES`, literally or via `realpathSync`); a user-writable `tailscale` found on PATH stops the step as `pending` / exit 2 / `tailscale_login_manual` with the message "tailscale at <path> is not a system install, so gbrain will not run it with sudo. If you trust that binary, sign in yourself (this runs it as root): `sudo <path> set --operator=$USER && sudo <path> up`, then re-run: <rerun>" — the command is `tailscaleManualLoginCommand(binary)`, naming the discovered path shell-quoted, because a binary outside sudo's `secure_path` is exactly this case — and never spawns `sudo`; macOS `tailscale up`; bounded wait via `GBRAIN_TAILSCALE_LOGIN_TIMEOUT_MS`), `tailscale.identity` (MagicDNS name → `public_url`; pre-checks so `tailscale serve`/`funnel` — which wait interactively instead of failing when a feature is off — are never started blind: empty `CertDomains` → `pending` / exit 2 / `tailscale_https_not_enabled` with `TAILSCALE_ADMIN_DNS_URL`; `--funnel` with `funnelCapable === false` → `tailscale_funnel_not_enabled` with the ACL admin + Funnel KB URLs; `funnelCapable === null` proceeds), `tailscale.publish` (reads the serve config through `readServeView`, which FAILS CLOSED — it returns `{ view: ServeStatusView | null, stderr, status }` with `view: null` when `tailscale serve status --json` exits non-zero / is killed (`status: null`) or when stdout is not a JSON object per `parseServeStatusStrict`; an empty document / `{}` / `null` from exit 0 is the legitimately empty view — a null view before `--bg` is described once by `describeServeReadFailure` (`{ kind, detail, fix }` from one `classifyTailscaleError` call), records `tailscale.publish` = fail and returns exit 1 with reason `tailscale_<kind>` without publishing; a null view after `--bg` is `tailscale_publish_unconfirmed` naming the read failure; refuses a `/` handler proxying a different port, a foreground session or a raw TCP forward without `--force` as `foreign_serve_config` — `next_actions` says `tailscale serve status`, only `message` explains `--force`; `PUBLISH_TIMEOUT_MS` (60s) bounds `--bg`, `SERVE_OFF_TIMEOUT_MS` (30s) every `--https=443 --set-path=/ off` and `STATUS_READ_TIMEOUT_MS` (15s) both status reads; a `status: null` timeout is `unknown` with a run-by-hand hint; stderr classified by `classifyTailscaleError` as the second line of defense; switching our own handler's shape pre-clears ONLY in the funnel → tailnet direction (`funnel --https=443 --set-path=/ off` before `serve --bg`, because `serve --bg` over a Funnel mount keeps `AllowFunnel`; tailnet → funnel is one atomic `funnel --bg`), and when that pre-off was followed by a failed publish (non-zero, timeout, or unconfirmed) `restorePrevious` best-effort re-publishes the previous shape with `tailscaleServeArgv(port, { funnel: true })`, re-reads the view, and appends to the `tailscale.publish` detail whether "the previous funnel handler was restored" or "could NOT be restored"; the existing receipt is never touched on those paths), `admin_token` (ensure the 0600 token file, never printed), `service` (launchd / systemd user unit / `manual` fallback with the exact foreground and `nohup` commands; a `--no-service` re-run carries the existing receipt's service block unchanged and does not rewrite the wrapper; `service_install_failed` still writes the receipt with `service.state: 'stopped'` before exit 1 so `--status`/`--remove` can clean up the published handler; the receipt is ALSO written right after a successful service step — service state as probed at that moment — before verify runs, so a kill during verify always leaves `--status`/`--remove` something to find), `verify.local` (wall-clock `/health` polling up to 20s, timeout → `warn`, exit 2, `verify.tailnet` skipped), `verify.tailnet` (up to 30s, `pending` is exit 2 — EXCEPT when the last probe's rejection was a name-resolution failure per `mcp-expose-probe.ts`: Bun's `fetch` rejects an unresolvable host and a refused connection with the same "Unable to connect. Is the computer able to access the url?" / `ConnectionRefused`, so after a rejected fetch the URL's hostname (never an IP literal or `localhost`) is handed to `deps.lookup` — default `dns.promises.lookup`, bounded by the probe timeout — and a rejection with code `ENOTFOUND` / `EAI_AGAIN` / `EAI_NONAME` / `EAI_NODATA` / `DNS_ENOTFOUND` (or a message naming one) is the verdict, the fetch-message regex staying a secondary hint; a name that resolves but does not answer stays `pending`: then the check is `warn` with `unresolvedDetail(dnsName)` — "this host cannot resolve <name> (MagicDNS may be off here: `tailscale set --accept-dns=true`); devices that do resolve it may already reach the server" — and the run exits 0, since this host's resolver says nothing about the server), `receipt` (rewrites the early receipt with the settled state — the supervisor is re-probed once verify.local ran — keeping `created_at`). The admin-token, service and verify steps run inside one try: a THROW there after this run's `--bg` succeeded but BEFORE the early receipt is rolled back by `rollbackAfterThrow(d, s, opts, published, error, receiptWritten)` — the fresh handler is turned off again with `tailscaleServeOffArgv({ funnel })` only when no `/` handler for our port existed before the run (a pre-existing one is left in place), a `rollback` check records what happened — "turned off again" is claimed only when a re-read of the serve view after an exit-0 `off` no longer shows our port; an exit-0 `off` whose re-read still shows it is a `warn` "NOT turned off (… the handler is still present)", an unreadable re-read is a `warn` "state unknown", and an `off` that exits non-zero or throws is a `warn` whose message says the handler was NOT turned off — no receipt is written, and the error is re-thrown so the outer catch reports `mcp_expose_failed` with a message naming the handler state; once the early receipt is on disk (`receiptWritten`, checked first) a throw tears nothing down (`rollback` = skipped pointing at `--status` / `--remove --yes`), because the receipt makes everything findable (the non-throwing `service_install_failed` path keeps its partial receipt). Success banner and `next_actions` gate the local-agent line on the engine: Postgres → `gbrain bootstrap harness --yes --port N`; PGLite → pre-mint (`gbrain auth create … --scopes read,write` before the service runs) + `--token`, or the scoped `mcp grant … --url http://127.0.0.1:N/mcp --admin-token-file …` + `gbrain connect … --install` path, and "host-side commands fail with `live_serve` — administer through the running server". `--json` emits one stdout document `{ status, receipt, checks[], next_actions, reason?, message? }` with prose on stderr; every `inherit` subprocess redirects its stdout to stderr under `--json`. `--status` and `--remove` read the receipt through `readExposeReceipt`'s shape guard (a partial receipt is `not_exposed` / "nothing to remove", never a crash) and execute the tailscale binary from `resolveReceiptBinary`: the receipt's recorded path is honored only when it still exists AND is either what `findTailscaleBinary` finds now or one of `TAILSCALE_BINARY_CANDIDATES`, otherwise discovery wins — a path in a receipt is data, never a licence to run it. the probes — `probeHealth` (`res.ok`), `probeOccupied` (any response, or an accepted TCP connect), the bounded never-throwing `tryFetch` → `FetchOutcome { res, unresolved }`, `pollHealth` → `{ ok, unresolved }` with the LAST probe's resolution verdict, `unresolvedDetail`, `defaultTcpProbe`, `defaultLookup` — live in `src/commands/mcp-expose-probe.ts` and take the narrow `ProbeDeps` slice of the resolved deps (`fetch`, `tcpProbe`, `lookup`, `now`, `sleep`, `healthIntervalMs`); `defaultTcpProbe` is re-exported here so its import site never moved; `isLiveService(state)` is the one definition of "the supervisor reports our service" (`running` or `loaded`) used by the lock-holder exemption, the service check, `--status` and both `--remove` paths; `serviceLabel` builds on `serviceKindLabel` (`launchd <label>` / `systemd (user) <unit>`). `--status` runs its four independent probes (serve config, supervisor state, local and tailnet `/health`) concurrently with `Promise.all` and still reports the checks in the fixed order `receipt`, `tailscale.publish`, `service`, `verify.local`, `verify.tailnet`; an unreadable serve config (null view) is a FAILED `tailscale.publish` check / exit 1, never "handler present"; a tailnet `/health` rejected for name resolution is `verify.tailnet` = warn (same `unresolvedDetail`), not `pending`, and does not by itself make the exit non-zero. `--status` with NO receipt is `runStatusWithoutReceipt`: it runs the read-only `probeLeftovers(d, opts.port)` (`--port` is honored) and, when the wrapper, the plist / unit or a live service, or a `/` handler on `:443` proxying the port is found, emits one `warn` check per artifact (`receipt`, `service`, `tailscale.publish`, `files`), pushes `recoveryCommand(port, force)` (`gbrain mcp expose --remove --yes`, `--force` only when a handler stands alone with no wrapper / service corroborating it, `--port N` when non-default) to `next_actions`, and finishes `error` / exit 1 / `leftovers_without_receipt` (also under `--json`); an unreadable serve status alone is a caveat warn, not a leftover; nothing found keeps the `not_exposed` answer (exit 0, `--json` exit 2). `--remove` (consent; decline is `pending` / exit 2) probes the supervisor and removes a service that exists even when the receipt says skipped — `recordServiceUninstall` prints the uninstall notes, and when `launchdBootoutFailed(result)` (a `launchctl bootout failed: …` / `unload failed: …` note, i.e. a non-"not loaded" failure) the `service` check is `warn` pointing at `launchctl print gui/$(id -u)/com.gbrain.serve` and "the launchd job (bootout failed)" is added to "Left in place"; it returns the one-line service summary quoted below — then clears only gbrain's own serve/funnel handler through `turnOffOurHandler` (Funnel off first; every `off` is `--https=443 --set-path=/ off`, scoped to our `/` mount; the serve config is re-read only after an `off` command ran, otherwise the view already read is reused; a failed re-read is reported as `unknown` — a warn, never "gone"; a foreign port on `:443` gets "nothing to turn off"). `--remove` never reports success while our handler survives: when `turnOffOurHandler` returns `remaining` as a handler (`tailscale.publish` = fail) or `'unknown'` (= warn), `finishHandlerNotRemoved` keeps the receipt AND the wrapper (mirroring the unreadable-status branch), records `receipt` = skipped "kept: …", pushes `tailscale serve status` + the re-run to `next_actions`, says which service outcome already happened, and exits 1 with reason `handler_not_removed`; `--remove` never runs `tailscale serve reset`, never uninstalls or logs out, keeps the admin token unless `--force` (deleted through the same `unlinkQuietly` as the wrapper and receipt), and unlinks the wrapper / receipt / token ONLY when the path's directory is the serve directory — a receipt path elsewhere is left untouched and named in "Left in place" (also in the plan). The receipt's recorded `plist_path` / `unit_path` are data, never a licence: `uninstallServeService` is always handed the computed `d.plistPath` / `d.unitPath` (home + the fixed label / unit name), and a recorded path that differs is not touched and is named in "Left in place" as "recorded in the receipt but not the expected location". A null serve view during `--remove` fails closed: `tailscale.publish` = fail "could not read tailscale serve status; handler left as is", reason `tailscale_serve_status_unreadable`, exit 1, and the receipt AND wrapper are kept so a re-run finishes the job. With NO receipt, `runRemoveWithoutReceipt` recovers from what is on disk through the same `probeLeftovers` `--status` uses (`wrapperPath(serveDir)`, the launchd plist / systemd unit or a `running`/`loaded` service, a `/` handler on `:443` proxying `opts.port` — `--port` may accompany `--remove`, default 3131); inside it the supervisor chain (`probeServiceTarget` → `serveServiceState`) and the `readServeView` read run concurrently under `Promise.all` (the binary is resolved synchronously first) and the plan / checks are emitted in the fixed order afterwards; the re-run hints come from `recoveryCommand`. The handler is turned off only with corroborating gbrain evidence — the wrapper present, our unit/plist present, or the supervisor reporting our service live — or with `--force`, because another tool may proxy `:443` to the same port: a handler standing alone is reported (`tailscale.publish` = warn naming the proxy target and `--force`, next action `gbrain mcp expose --remove --yes --force`) and left in place on the "not exposed — nothing to remove" exit-0 path; with `--force` the plan line says so. Otherwise it prints a "Recovering without a receipt" plan (`receipt` check = warn), takes consent as usual, removes exactly those artifacts (service via the supervisor — the same `recordServiceUninstall` bootout-failure warn applies — wrapper, the handler — funnel off first when `AllowFunnel` lists the host), leaves the admin token file, and finishes `removed` with reason `recovered_without_receipt`; a handler that survives the `off` is `handler_not_removed` / exit 1 here too, with the wrapper deliberately KEPT as the corroboration the re-run needs (`files` = skipped "kept: the wrapper"; the re-run hint carries `--force` when no wrapper is left); an unreadable serve status on this path (gbrain evidence present, `serveUnreadable` set) fails closed exactly like the receipt path — the service, when found, is still uninstalled, the plan says the handler cannot be checked and the wrapper is kept, `tailscale.publish` = fail "…; handler state unknown", `files` = skipped "kept: the wrapper" (or "nothing (no wrapper was found)"), `next_actions` = `tailscale serve status --json` + the recovery command (`--force` when no wrapper is left), exit 1 with reason `tailscale_serve_status_unreadable` and message "could not read tailscale serve status; handler state unknown"; when nothing of ours is found the answer stays "not exposed — nothing to remove", exit 0 (an unreadable serve status is then only the caveat warn — there is nothing to keep and a handler alone would not be touched anyway). Every filesystem/exec effect goes through injectable deps so tests run against a fake runner in a tmpdir. Success guidance separates owner login, native OAuth registration, and machine grant/install. It uses the expose-managed owner file only when installing or keeping that service; publication with `--no-service` and no managed service instead requires the existing server's independently configured owner credential. Publishing receipts and health checks do not certify client authorization or native activation.-- `src/commands/mcp-expose-probe.ts` — the health / occupancy probes `mcp-expose.ts` runs, peeled out behind a narrow `ProbeDeps` (`fetch`, `tcpProbe`, `lookup`, `now`, `sleep`, `healthIntervalMs`) rather than the whole resolved-deps bag: `tryFetch(d, url, timeoutMs)` (one bounded fetch, `redirect: 'manual'`, never throws → `FetchOutcome { res, unresolved }`), `probeHealth` (`res.ok` — the `verify.*` / `--status` bar), `probeOccupied` (an accepted TCP connect OR any HTTP answer — the foreign-listener bar), `pollHealth` (wall-clock budget from `d.now()`, per-probe timeout `min(1500, remaining)`, attempt cap `ceil(budget / healthIntervalMs)` as the frozen-clock backstop, `unresolved` = the LAST probe's verdict), `unresolvedDetail(dnsName)`, `defaultTcpProbe` (one `node:net` connect, socket destroyed on every outcome) and `defaultLookup` (local RFC 6761 `.invalid` rejection, otherwise `dns.promises.lookup`). The name-resolution verdict is the reason the module exists: Bun's `fetch` rejects an unresolvable host with the SAME error as a refused connection ("Unable to connect. Is the computer able to access the url?", code `ConnectionRefused`), so a message match alone never fires in production. After a rejection `nameUnresolved` takes `new URL(url).hostname`, skips IP literals (`isIP`) and `localhost`, and otherwise awaits `d.lookup(host)` raced against the probe's `timeoutMs` (a lookup that does not answer in time proves nothing; the race keeps a late rejection handled); `isUnresolvedLookupError` classifies the lookup rejection by `code` — `ENOTFOUND`, `EAI_AGAIN`, `EAI_NONAME`, `EAI_NODATA`, `DNS_ENOTFOUND` (a resolver outage counts: the verdict is about THIS host) — or by those tokens in its message, and the fetch-message regex (`ENOTFOUND|getaddrinfo|EAI_AGAIN|failed to resolve|Unable to connect.*resolve`) is OR-ed in afterwards as the secondary hint. Tests inject a fake fetch, TCP probe and resolver (`test/mcp-expose.test.ts`; the fixture's default `lookup` resolves every name, reserved-name and label-boundary cases do not query external DNS, and the real `defaultLookup` resolves localhost). `statusOnlyHealthDetail(port)` reads this host's live status-only marker for the port so `verify.local` reads "status-only (<reason>)" instead of a timeout or "no answer".--[Continue this subsystem](google-and-loops-continued.md).+[Continue this subsystem](google-and-loops-continued.md) · [More entries](google-and-loops-more.md).diff --git a/docs/guides/brain-layout.md b/docs/guides/brain-layout.mdindex 19b36c6af7..1a30342530 100644--- a/docs/guides/brain-layout.md+++ b/docs/guides/brain-layout.md@@ -54,8 +54,8 @@ gbrain setup claude-code --shape both --notes ~/notes --docs ~/acme-example/docsbackstop skips them; the scheduled atom extraction still reads them when a model keyis set, within `cycle.extract_atoms.budget_usd`, and so does event extraction(`auto_chronicle`) within its daily limit. Setup's `what leaves this machine` line says- which of these is on for your brain, or that nothing leaves. Each file is imported once: a re-run from the same folder reports it- unchanged, and a file you changed since keeps its first page (delete the page to+ which of these is on for your brain, or that nothing leaves. Each file is imported once: a re-run from the same folder, or from a folder above it,+ reports it unchanged, and a file you changed since keeps its first page (delete the page toimport it again). Above 500files setup prints the import command instead (`gbrain import DIR --calls --prefixcompany/calls --no-embed --source company`). It needs the company part on this brain,diff --git a/docs/mcp/ADMIN.md b/docs/mcp/ADMIN.mdindex 1bf9412f3f..a1ebc9c77b 100644--- a/docs/mcp/ADMIN.md+++ b/docs/mcp/ADMIN.md@@ -339,6 +339,10 @@ server's surface is narrower. The connection itself sees counts, never names,in `whoami` (`grant_diagnosis`) and `gbrain://capabilities`; operations outsidethe grant's scopes are never counted. On the host, `gbrain doctor` reports`grant_new_ops_available` with each grant's blockers and the operation names.+A grant missing only the membership operations the owner approves by name+(`join_brain`, `sync_brain_skills`, `leave_brain`) leaves the check `ok`: it+lists them with the command that adds them, because adding them is the owner's+choice, not a repair.The connection is also told in band, without asking: the`grant_blocked_operations` notice arrives once per session (once perdiff --git a/scripts/changelog-entry.sh b/scripts/changelog-entry.shindex a22b9bacd5..2b70e5f80c 100755--- a/scripts/changelog-entry.sh+++ b/scripts/changelog-entry.sh@@ -8,7 +8,8 @@# with one line per change: for every changelog.d fragment a release commit# deleted since the newest v* tag before HEAD, in fold order (oldest release# first, then path order), the fragment's first bold line plus the "(#N)" of-# the master commit that added it. The list goes on the GitHub release only;+# the master commit that added it; a trailing internal issue code such as+# "(GST-123)" is dropped from the line. The list goes on the GitHub release only;# CHANGELOG.md never carries it.## Usage: changelog-entry.sh [--pr-list] <version> [changelog-file]@@ -51,6 +52,7 @@ list_changes() {headline="${headline%.}"cited="$(printf '%s\n' "$headline" | sed -nE 's/.*[[:space:]]\((#[0-9]+(, #[0-9]+)*)\)$/\1/p')"if [ -n "$cited" ]; then headline="${headline% ("$cited")}"; fi+ headline="$(printf '%s\n' "$headline" | sed -E 's/[[:space:]]+\([A-Z]{2,5}-[0-9]+\)$//')"if [ -n "$pr" ] && [[ ", $cited, " != *", #$pr, "* ]]; then cited="${cited:+$cited, }#$pr"; fiif [ -n "$cited" ]; thenprintf -- '- %s (%s)\n' "$headline" "$cited"diff --git a/src/cli/migrations-notice.ts b/src/cli/migrations-notice.tsindex 3ef2d53485..28e2999e3f 100644--- a/src/cli/migrations-notice.ts+++ b/src/cli/migrations-notice.ts@@ -2,7 +2,7 @@ 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']);+const ORCHESTRATOR_MIGRATION_OWNERS: ReadonlySet<string> = new Set(['apply-migrations', 'post-upgrade', 'upgrade', 'doctor', 'init', 'setup']);/** 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 {@@ -12,15 +12,15 @@ export function migrationsNotice(why: string): Notice {/*** 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.+ * setup, never on connect. A reinstall over an older brain (`bun install -g` again) runs neither, so connect says so;+ * `gbrain serve` gets it once, at startup on stderr, since a brain used only over MCP runs no other command.+ * Returns null when nothing is pending, the command owns the migrations, the brain is fresh, 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 { declinedMigrations, migrationLedgerSummary, upgradeLedgerApplies } = await import('../core/migration-ledger.ts');+ if (!upgradeLedgerApplies(engine)) return null;const summary = migrationLedgerSummary(version, await declinedMigrations(engine));if (summary.wedged.length > 0) {const { wedgedMigrationFix } = await import('../commands/apply-migrations.ts');diff --git a/src/commands/doctor/checks/grant-new-ops.ts b/src/commands/doctor/checks/grant-new-ops.tsindex 103f9a066b..cffb4ca4cd 100644--- a/src/commands/doctor/checks/grant-new-ops.ts+++ b/src/commands/doctor/checks/grant-new-ops.ts@@ -1,6 +1,8 @@/*** D4 `grant_new_ops_available` (warn when non-zero): active OAuth clients and- * legacy tokens that cannot call operations their scopes allow.+ * legacy tokens that cannot call operations their scopes allow. A grant missing+ * only operations the owner approves by name is listed with its by-name command+ * and the check stays ok: granting those is the owner's call, not a repair.** Proven blockers come from the stored grant: the operation snapshot, the* client's own stored surface (pin) and the configured server surface. They@@ -69,13 +71,16 @@ function shownCommand(argv: string[]): string {return argv.map(arg => arg.length > 80 ? `<${arg.split(',').length} operations: see details.grants>` : arg).join(' ');}+function labelOf(f: GrantFinding): string {+ return f.kind === 'oauth_client' ? `client ${f.name} (${f.id})` : `token ${f.name}`;+}+function describeFinding(f: GrantFinding): string {- const label = f.kind === 'oauth_client' ? `client ${f.name} (${f.id})` : `token ${f.name}`;const parts = f.blockers.filter(b => b.blocker !== 'scope').map(b => b.blocker === 'operation_snapshot' ? `its operation snapshot excludes ${b.excluded_count}`: b.blocker === 'client_pin' ? `its stored ${b.surface} surface excludes ${b.excluded_count}`: `the configured ${b.surface} server surface excludes ${b.excluded_count}`);const age = 'statement' in f.grant_age ? ` ${f.grant_age.statement}` : '';- return `${label}: ${parts.join(', ')}.${age}${f.preview_argv ? ` Preview: ${shownCommand(f.preview_argv)}` : ''}${byNameNote(f)}`;+ return `${labelOf(f)}: ${parts.join(', ')}.${age}${f.preview_argv ? ` Preview: ${shownCommand(f.preview_argv)}` : ''}${byNameNote(f)}`;}function byNameNote(f: GrantFinding): string {@@ -133,9 +138,16 @@ export async function checkGrantNewOps(engine: BrainEngine, opts: { cfg?: GBraindetails: { grants: [], server_surface: ceiling, docs: DOCS } };}const first = findings.find(f => f.argv);- const placeholder = first?.argv?.includes('<OPERATIONS>');- const fix: Action | undefined = !first?.argv ? undefined : {- preview_argv: first.preview_argv!, argv: first.argv, consent: ['credentials'], actor: 'agent', requires_exclusive: false, docs: DOCS,+ if (!first) {+ return { name: 'grant_new_ops_available', status: 'ok',+ message: 'Every active client and token can call the operations its scopes allow, except operations the owner approves by name: '+ + findings.map(f => `${labelOf(f)}: ${f.by_name_operations.join(', ')}; an owner who approves them adds them with ${shownCommand(f.by_name_argv!)}`).join('; ')+ + `. Leave them out unless the owner names them.${ceilingNote} See ${DOCS}.`,+ details: { grants: findings, server_surface: ceiling, docs: DOCS } };+ }+ const placeholder = first.argv!.includes('<OPERATIONS>');+ const fix: Action = {+ preview_argv: first.preview_argv!, argv: first.argv!, consent: ['credentials'], actor: 'agent', requires_exclusive: false, docs: DOCS,verify: doctorVerify('grant_new_ops_available'),why: 'An operation snapshot or a stored client surface keeps this grant from operations its scopes allow; changing it widens what that credential can do.',user_message: `${findings.length} connection grant(s) cannot call operations their scopes allow (first: ${first.name}). `@@ -151,7 +163,7 @@ export async function checkGrantNewOps(engine: BrainEngine, opts: { cfg?: GBrain+ `Ask the user before changing any grant; nothing widens automatically, and --operations all (${ALL_OPERATIONS_CHOICE}) is a separate choice, not the default repair.`+ `${ceilingNote} See ${DOCS}.`,details: { grants: findings, server_surface: ceiling, all_operations_choice: ALL_OPERATIONS_CHOICE, docs: DOCS },- ...(fix ? { fix } : {}),+ fix,};} catch (e) {return checkError('grant_new_ops_available', 'read client and token grants', e);diff --git a/src/commands/doctor/checks/local-runtime.ts b/src/commands/doctor/checks/local-runtime.tsindex 21ba11632f..8e3120c93a 100644--- a/src/commands/doctor/checks/local-runtime.ts+++ b/src/commands/doctor/checks/local-runtime.ts@@ -8,7 +8,7 @@*/import { loadCompletedMigrations } from '../../../core/preferences.ts';-import { MIGRATION_OPT_OUT_KEYS, declinedMigrations, indexCompletedEntries, isFreshInstallStamp, migrationLedgerSummary, trailingPartialCount } from '../../../core/migration-ledger.ts';+import { MIGRATION_OPT_OUT_KEYS, declinedMigrations, indexCompletedEntries, isFreshInstallStamp, migrationLedgerSummary, trailingPartialCount, upgradeLedgerApplies } from '../../../core/migration-ledger.ts';import { VERSION } from '../../../version.ts';import { pendingFreshInstallCheck } from './pending-fresh-install.ts';import { autopilotInstallPendingCheck } from './autopilot-install-pending.ts';@@ -181,13 +181,16 @@ async function runMinionsMigration(ctx: DoctorContext): Promise<Check[]> {// Registered host migrations get_health lists as `pending` (no ledger// entry, or reset by a retry marker) that a NEWER migration already ran// past were skipped, not merely not reached yet. Versions above the newest- // run are the next apply-migrations' ordinary work and stay quiet here.+ // run are the next apply-migrations' ordinary work and stay out of this list.// #8720: without an engine (--fast) the config that declines an opt-out// migration is unreadable, so such a version is unknown, never pending.const newestRun = completedVersions.reduce<string | null>((a, v) => (a === null || compareVersions(v, a) > 0 ? v : a), null);const pending = completed.length === 0 ? [] : migrationLedgerSummary(VERSION, declined).pending.filter(v =>(engine || !(v in MIGRATION_OPT_OUT_KEYS))&& ((newestRun !== null && compareVersions(v, newestRun) < 0) || history.get(v)?.at(-1)?.status === 'retry'));+ // GBRA-541 4a: connected to the brain, doctor also reports the upgrade migrations connect's notice names (versions+ // not reached yet), so an owner whose brain runs only `gbrain serve` sees them here.+ const notReached = engine && upgradeLedgerApplies(engine) ? migrationLedgerSummary(VERSION, declined).pending : [];if (declined.size > 0) {const keys = [...declined].map(v => `${MIGRATION_OPT_OUT_KEYS[v]}=false`);@@ -222,6 +225,13 @@ async function runMinionsMigration(ctx: DoctorContext): Promise<Check[]> {message: `${pending.length} host migration(s) not run yet: ${pending.join(', ')}. Run: gbrain apply-migrations --yes`,details: { pending },});+ } else if (notReached.length > 0) {+ checks.push({+ name: 'minions_migration',+ status: 'warn',+ message: `${notReached.length} upgrade migration(s) have not run on this brain yet: ${notReached.join(', ')}. Run: gbrain apply-migrations --yes --no-autopilot-install`,+ details: { pending: notReached },+ });} else {const setup = pendingFreshInstallCheck();if (setup) checks.push(setup);diff --git a/src/commands/import-calls.ts b/src/commands/import-calls.tsindex f72b2164ab..cdb2a30f94 100644--- a/src/commands/import-calls.ts+++ b/src/commands/import-calls.ts@@ -17,8 +17,9 @@* anything embeds it (call_import.embedding_hold, the conversation archive's any-size hold);* - each file imports once: a rerun finds the page its file made by its folder and path under the prefix (call_import.root* and path, a digest of the folder and the unredacted relative path, so two names a redaction pattern makes alike stay- * apart; a page stored before path existed is found by its file), not by the computed slug, which a new modified day- * can move, and reports it unchanged, or kept when the file changed since, and never writes it again. The prefix is slugified per segment, as stored slugs are. Two files that map to one slug get a short hash+ * apart; a page stored before path existed is found by its file), whichever folder above the file an import started+ * from, not by the computed slug, which a new modified day can move, and reports it unchanged, or kept when the file+ * changed since, and never writes it again. A write of the file still pending is reported pending, not written again. The prefix is slugified per segment, as stored slugs are. Two files that map to one slug get a short hash* of their path on the second.** These are not agent sessions: nothing here touches conversations/ or the conversation archive switch.@@ -37,6 +38,8 @@ import { loadImportRedactionPatterns, redactSession, type ImportRedactionPatternimport { acceptPendingCovers, acceptPendingRequested, CLI_WRITE_WAIT_MS, pendingReceiptOf, pollCommand } from '../core/persistence/write-wait.ts';import { PENDING_WRITE_EXIT_CODE } from '../core/exit-codes.ts';import { cliRenderContext } from '../core/agent-output.ts';+import { TERMINAL_STATES } from '../core/persistence/model.ts';+import type { WriteReceipt } from '../core/persistence/types.ts';export const CALL_FILE_RE = /\.(txt|md)$/i;export const DEFAULT_CALL_PREFIX = 'calls';@@ -162,6 +165,18 @@ export function redactCallPath(rel: string, patterns: ImportRedactionPattern[]):/** The import folder's identity in a page: a short hash of its real path, so two folders holding the same file name stay apart. */export const callRootId = (dir: string): string => createHash('sha256').update(dir).digest('hex').slice(0, 12);+/** call_import.path: the file's identity, a digest of the import folder and the unredacted path under it. */+const callPathId = (folder: string, rel: string): string => createHash('sha256').update(`${folder}\u0000${rel}`).digest('hex').slice(0, 16);++/** Every call_import.path the file `abs` has had: one per folder above it that an import could have started from. */+function callPathIds(abs: string): Set<string> {+ const ids = new Set<string>();+ for (let dir = dirname(abs); ; dir = dirname(dir)) {+ ids.add(callPathId(dir, relative(dir, abs)));+ if (dirname(dir) === dir) return ids;+ }+}+function flagValue(args: string[], name: string): string | undefined {const i = args.indexOf(name);return i >= 0 ? args[i + 1] : undefined;@@ -174,22 +189,30 @@ export async function runCallImport(engine: BrainEngine, dir: string, args: striconst patterns = loadImportRedactionPatterns();const { operations } = await import('../core/operations.ts');const putPage = operations.find(op => op.name === 'put_page')!;+ const getWriteRequest = operations.find(op => op.name === 'get_write_request')!;const ctx = { engine, config: loadConfig() ?? { engine: engine.kind }, logger: { info() {}, warn: (m: string) => process.stderr.write(`${m}\n`), error: (m: string) => process.stderr.write(`${m}\n`) },dryRun: false, remote: false, cliOpts: getCliOptions(), sourceId, writeWaitMs: CLI_WRITE_WAIT_MS } as Parameters<typeof putPage.handler>[0];const single = lstatSync(dir).isFile();const folder = single ? dirname(dir) : dir;const files = single ? [dir] : listCallFiles(dir);const root = callRootId(folder);- const prior = await engine.executeRaw<{ slug: string; file: string; path: string | null }>(- `SELECT slug, frontmatter->'call_import'->>'file' AS file, frontmatter->'call_import'->>'path' AS path FROM pages- WHERE source_id = $1 AND deleted_at IS NULL AND starts_with(slug, $2) AND frontmatter->'call_import'->>'root' = $3- AND frontmatter->'call_import'->>'file' IS NOT NULL`,- [sourceId, `${prefix}/`, root]);+ const prior = await engine.executeRaw<{ slug: string; root: string | null; file: string; path: string | null }>(+ `SELECT slug, frontmatter->'call_import'->>'root' AS root, frontmatter->'call_import'->>'file' AS file, frontmatter->'call_import'->>'path' AS path FROM pages+ WHERE source_id = $1 AND deleted_at IS NULL AND starts_with(slug, $2) AND frontmatter->'call_import'->>'file' IS NOT NULL`,+ [sourceId, `${prefix}/`]);const byPath = new Map(prior.filter(r => r.path).map(r => [r.path, r.slug]));- const byFile = new Map(prior.filter(r => !r.path).map(r => [r.file, r.slug]));- const sameImport = (frontmatter: unknown, page: CallPage): boolean => {+ const byFile = new Map(prior.filter(r => !r.path && r.root === root).map(r => [r.file, r.slug]));+ const pendingByPath = new Map<string, { slug: string; request_id: string }>();+ for (const row of await engine.executeRaw<{ slug: string; request_id: string; content: string | null }>(+ `SELECT slug, request_id::text AS request_id, intent->>'content' AS content FROM persistence_requests+ WHERE source_id = $1 AND operation = 'put_page' AND starts_with(slug, $2) AND NOT (state = ANY($3::text[])) ORDER BY sequence`,+ [sourceId, `${prefix}/`, [...TERMINAL_STATES]])) {+ const id = /^ {2}path: "([0-9a-f]{16})"$/m.exec(row.content ?? '')?.[1];+ if (id && !pendingByPath.has(id)) pendingByPath.set(id, { slug: row.slug, request_id: row.request_id });+ }+ const sameImport = (frontmatter: unknown, page: CallPage, ids: Set<string>): boolean => {const ci = callImportOf(frontmatter);- return ci?.root === root && (typeof ci.path === 'string' ? ci.path === page.path : ci.file === page.file);+ return typeof ci?.path === 'string' ? ids.has(ci.path) : ci?.root === root && ci.file === page.file;};const results: CallFileResult[] = [];const used = new Set<string>();@@ -202,24 +225,34 @@ export async function runCallImport(engine: BrainEngine, dir: string, args: stricontinue;}try {- page = callPageFor(rel, readFileSync(path, 'utf8'), lstatSync(path).mtimeMs, prefix, patterns, root, createHash('sha256').update(`${folder}\u0000${rel}`).digest('hex').slice(0, 16));+ page = callPageFor(rel, readFileSync(path, 'utf8'), lstatSync(path).mtimeMs, prefix, patterns, root, callPathId(folder, rel));} catch (e) {results.push({ file: redactCallPath(rel, patterns).file, slug: '', status: 'error', error: e instanceof Error ? e.message : String(e) });continue;}const suffixed = `${page.slug}-${createHash('sha256').update(`${root}/${rel}`).digest('hex').slice(0, 6)}`;+ const ids = callPathIds(path);const legacy = byFile.get(page.file);- const priorSlug = byPath.get(page.path!) ?? (legacy && !used.has(legacy) ? legacy : undefined);+ const priorSlug = [...ids].map(id => byPath.get(id)).find(Boolean) ?? (legacy && !used.has(legacy) ? legacy : undefined);+ const held = priorSlug ? undefined : [...ids].map(id => pendingByPath.get(id)).find(Boolean);+ if (held) {+ used.add(held.slug);+ const receipt = await getWriteRequest.handler(ctx, { request_id: held.request_id }).catch(() => null) as WriteReceipt | null;+ if (!receipt || !acceptPendingCovers(receipt)) uncovered++;+ results.push({ file: page.file, slug: held.slug, date_from: page.date_from, redactions: page.redactions, status: 'pending', request_id: held.request_id,+ poll: pollCommand(held.request_id, undefined, cliRenderContext().routing) });+ continue;+ }let slug = priorSlug ?? (used.has(page.slug) ? suffixed : page.slug);let existing = await engine.readPageSnapshot(slug, { sourceId });- if (!priorSlug && existing && !sameImport(existing.page.frontmatter, page) && slug !== suffixed) {+ if (!priorSlug && existing && !sameImport(existing.page.frontmatter, page, ids) && slug !== suffixed) {slug = suffixed;existing = await engine.readPageSnapshot(slug, { sourceId });}used.add(slug);const base = { file: page.file, slug, date_from: page.date_from, redactions: page.redactions };if (existing) {- if (!sameImport(existing.page.frontmatter, page)) results.push({ ...base, status: 'error', error: `${slug} already holds another page; rename the file to import it` });+ if (!sameImport(existing.page.frontmatter, page, ids)) results.push({ ...base, status: 'error', error: `${slug} already holds another page; rename the file to import it` });else results.push({ ...base, status: callImportOf(existing.page.frontmatter)?.hash === page.hash ? 'unchanged' : 'kept' });continue;}diff --git a/src/commands/init-embedding-plane.ts b/src/commands/init-embedding-plane.tsindex eb377e751e..fc7419634e 100644--- a/src/commands/init-embedding-plane.ts+++ b/src/commands/init-embedding-plane.ts@@ -31,6 +31,17 @@ export async function keptEmbeddingIdentity(engine: BrainEngine, aiOpts: Resolvereturn agrees ? { model: stored!.model!, dimensions: stored!.dimensions } : null;}+/**+ * #9451: an init that resolved an embedding model clears embedding_disabled and records the model and width in the+ * database plane too. assertInitEmbeddingIdentity already refused when stored vectors belong to another model, so only a+ * brain with no vectors (or the same model) gets here.+ */+export async function recordInitEmbedding(engine: BrainEngine, model: string, dimensions: number): Promise<void> {+ await engine.unsetConfig('embedding_disabled');+ await engine.setConfig('embedding_model', model);+ await engine.setConfig('embedding_dimensions', String(dimensions));+}+/** The notice init prints instead of the deferred-setup hint when it kept the database's identity. */export function keptEmbeddingNotice(kept: KeptEmbedding): string {let key = 'the provider API key';diff --git a/src/commands/init.ts b/src/commands/init.tsindex e78a32922e..10fe1bc03e 100644--- a/src/commands/init.ts+++ b/src/commands/init.ts@@ -18,7 +18,7 @@ import type { BrainEngine } from '../core/engine.ts';import { readPrimaryEmbeddingStores, readStoredEmbeddingIdentity } from '../core/stored-embedding-identity.ts';import { deferInitJsonError, flushInitJsonResult, initJsonError, setInitJsonResult, writeDeferredInitJsonError } from './init-json.ts';import { deferredEmbeddingHint, firstRunBundle, firstRunJson, harnessRegistrationCommand } from './init-first-run.ts';-import { keptEmbeddingIdentity, keptEmbeddingNotice } from './init-embedding-plane.ts';+import { keptEmbeddingIdentity, keptEmbeddingNotice, recordInitEmbedding } from './init-embedding-plane.ts';import { writeCliNotices } from '../core/interop-notices.ts';import { exitCodeForCode } from '../core/error-catalogue.ts';import { promptLineStderr } from '../core/interaction.ts';@@ -1237,7 +1237,7 @@ export async function initPGLite(opts: {// disables embedding at runtime.if (!opts.aiOpts?.noEmbedding && resolvedModel && resolvedDim) {delete config.embedding_disabled;- await engine.unsetConfig('embedding_disabled');+ await recordInitEmbedding(engine, resolvedModel, resolvedDim);}// PR1: new installs publish their skill catalog over MCP by default// (existing config wins on re-init, so a prior opt-out is preserved).@@ -1579,7 +1579,7 @@ export async function initPostgresCore(opts: {// disables embedding at runtime.if (!opts.aiOpts?.noEmbedding && resolvedModel && resolvedDim) {delete config.embedding_disabled;- await engine.unsetConfig('embedding_disabled');+ await recordInitEmbedding(engine, resolvedModel, resolvedDim);}// PR1: new installs publish their skill catalog over MCP by default// (existing config wins on re-init, so a prior opt-out is preserved).diff --git a/src/core/migrate-pending.ts b/src/core/migrate-pending.tsindex 584ec71bdd..742088d75a 100644--- a/src/core/migrate-pending.ts+++ b/src/core/migrate-pending.ts@@ -3,11 +3,19 @@ import { engineKey } from './engine-key.ts';import { LATEST_SCHEMA_VERSION } from './schema-migrations/latest.generated.ts';const SCHEMA_VERSION_SEEN = Symbol('gbrain.schemaVersionSeen');-type Recorded = { [SCHEMA_VERSION_SEEN]?: number };+const SCHEMA_VERSION_AT_CONNECT = Symbol('gbrain.schemaVersionAtConnect');+type Recorded = { [SCHEMA_VERSION_SEEN]?: number; [SCHEMA_VERSION_AT_CONNECT]?: number };/** GST-2687: records config `version` on the engine as it just read or wrote it (the connect gate below, migrations); a transaction or view records on its engine. */export function noteSchemaVersion(engine: object, version: number): void {- (engineKey(engine) as Recorded)[SCHEMA_VERSION_SEEN] = Number.isInteger(version) ? version : undefined;+ const recorded = engineKey(engine) as Recorded;+ recorded[SCHEMA_VERSION_SEEN] = Number.isInteger(version) ? version : undefined;+ if (recorded[SCHEMA_VERSION_AT_CONNECT] === undefined && Number.isInteger(version)) recorded[SCHEMA_VERSION_AT_CONNECT] = version;+}++/** The first schema version recorded on `engine`, read before this process migrated anything; above 1, the brain's schema existed before this run. */+export function schemaVersionAtConnect(engine: object): number | undefined {+ return (engineKey(engine) as Recorded)[SCHEMA_VERSION_AT_CONNECT];}/** The schema version `engine` (or the engine a transaction or view belongs to) last recorded, read with no query; undefined when none was. */diff --git a/src/core/migration-ledger.ts b/src/core/migration-ledger.tsindex 4d0614764b..6d337f07c2 100644--- a/src/core/migration-ledger.ts+++ b/src/core/migration-ledger.ts@@ -15,6 +15,8 @@import type { BrainEngine } from './engine.ts';import { loadCompletedMigrations, preferencesPaths, type CompletedMigrationEntry } from './preferences.ts';+import { schemaVersionAtConnect } from './migrate-pending.ts';+import { LATEST_SCHEMA_VERSION } from './schema-migrations/latest.generated.ts';/*** Version strings of every registered host migration, in registry order.@@ -51,6 +53,17 @@ export async function declinedMigrations(engine: Pick<BrainEngine, 'getConfig'>)return declined;}+/**+ * Whether this host's upgrade-migration ledger speaks for the brain. The ledger lives under GBRAIN_HOME, so an empty one+ * is a fresh brain only when the brain's schema is new too: an existing brain an older release last opened (its schema+ * version above 1 and behind this release when this process connected) still has its upgrade migrations to run. A brain+ * whose schema is already current was opened by this release before, so a new or rebuilt GBRAIN_HOME stays quiet there.+ */+export function upgradeLedgerApplies(engine: object): boolean {+ const atConnect = schemaVersionAtConnect(engine) ?? 0;+ return loadCompletedMigrations().length > 0 || (atConnect > 1 && atConnect < LATEST_SCHEMA_VERSION);+}+/** Bug 3 attempt cap — consecutive partials before a version counts wedged. */export const MAX_CONSECUTIVE_PARTIALS = 3;diff --git a/src/core/persistence/root-registry.ts b/src/core/persistence/root-registry.tsindex 4c606ad857..a57e59b2cb 100644--- a/src/core/persistence/root-registry.ts+++ b/src/core/persistence/root-registry.ts@@ -40,7 +40,8 @@ export function enclosingGitMetadata(root: string): string | null {* tracks `root` (a committed subdirectory). A directory a checkout only encloses (a connector clone or a plain directory* under a dotfiles home) belongs to none, and so does a `.git`, its own or an enclosing one, that is not a repository* (#9430). A Git read that fails for another reason keeps the enclosing checkout, unless the root has its own invalid- * `.git`: a gitdir file pointing nowhere fails every Git read there, so nothing proves the enclosing checkout tracks it.+ * `.git`: an empty file or a gitdir file pointing nowhere fails every Git read there, so nothing proves the enclosing+ * checkout tracks it.*/export function checkoutGitMetadata(root: string): string | null {const own = gitMetadataDirectory(root);@@ -48,7 +49,7 @@ export function checkoutGitMetadata(root: string): string | null {const enclosing = enclosingGitMetadata(dirname(root));if (!enclosing) return null;try { execFileSync('git', ['-C', root, 'rev-parse', '--verify', '--quiet', 'HEAD:./'], { stdio: 'ignore', timeout: 10_000, env: gitChildEnv() }); }- catch (error) { if ((error as { status?: unknown }).status === 1 || own || !isGitDirectory(enclosing)) return null; }+ catch (error) { if ((error as { status?: unknown }).status === 1 || existsSync(join(root, '.git')) || !isGitDirectory(enclosing)) return null; }return enclosing;}/** #9430: Git's own test for a repository directory: HEAD, plus objects/ and refs/ in its common directory (`commondir` in a linked worktree). */diff --git a/test/checkout-git-metadata-invalid-enclosing-9430.test.ts b/test/checkout-git-metadata-invalid-enclosing-9430.test.tsindex 76b7ef0ce8..6fc785b8ae 100644--- a/test/checkout-git-metadata-invalid-enclosing-9430.test.ts+++ b/test/checkout-git-metadata-invalid-enclosing-9430.test.ts@@ -120,3 +120,21 @@ test('control: a real repository that tracks the root stays its checkout', () =>git('-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-qm', 'wiki');expect(checkoutGitMetadata(wiki)).toBe(join(base, 'repo', '.git'));});++for (const tracked of [false, true]) {+ test(`a root whose own .git is an empty file is no checkout, even inside a repository (${tracked ? 'tracked' : 'untracked'} directory)`, () => {+ const base = mkdtempSync(join(tmpdir(), 'gbrain-9430-empty-file-'));+ bases.push(base);+ const repo = join(base, 'repo'), root = join(repo, 'source-a');+ mkdirSync(root, { recursive: true });+ const git = (...args: string[]) => execFileSync('git', ['-C', repo, ...args], { stdio: 'ignore' });+ git('init', '-q');+ writeFileSync(join(repo, 'README.md'), 'Repository.\n');+ if (tracked) writeFileSync(join(root, 'alice-example.md'), 'Notes.\n');+ git('add', '.');+ git('-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-qm', 'initial');+ writeFileSync(join(root, '.git'), '');+ expect(checkoutGitMetadata(root)).toBeNull();+ });+}+diff --git a/test/doctor-grant-by-name-only-ok.test.ts b/test/doctor-grant-by-name-only-ok.test.tsnew file mode 100644index 0000000000..74cdc8da10--- /dev/null+++ b/test/doctor-grant-by-name-only-ok.test.ts@@ -0,0 +1,46 @@+/**+ * `grant_new_ops_available` when the only missing operations are the membership ones the owner approves by name+ * (join_brain, sync_brain_skills, leave_brain): the check is ok and names those operations with the command that adds+ * them, because no default repair exists and a warn that clears only by granting them pushes owners to widen a grant.+ * A grant missing any other operation still warns with the default repair.+ */+import { afterAll, beforeAll, expect, test } from 'bun:test';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';+import { sqlQueryForEngine } from '../src/core/sql-query.ts';+import { resolveGrantProfile } from '../src/core/grants/service.ts';+import { mintLegacyToken } from '../src/core/token-mint.ts';+import { checkGrantNewOps } from '../src/commands/doctor/checks/grant-new-ops.ts';++const cfg = { engine: 'pglite' } as any;+let engine: PGLiteEngine;+beforeAll(async () => { engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema(); }, 120_000);+afterAll(async () => { await engine.disconnect(); });++type Finding = { name: string; argv: string[] | null; by_name_operations: string[]; by_name_argv: string[] | null };++test('a grant missing only by-name operations is ok with those operations and their command; one missing others still warns', async () => {+ const profile = resolveGrantProfile({ profile: 'memory-writer', sourceId: 'default' });+ const scopes = ['read', 'write', 'skills_member_self'];+ const provider = new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });+ await provider.registerClientManual('member-example', ['client_credentials'], scopes.join(' '), [], 'default', undefined, undefined, undefined,+ { ...profile, scopes, allowedOperations: profile.allowedOperations });++ const byNameOnly = await checkGrantNewOps(engine, { cfg });+ const [finding] = (byNameOnly.details?.grants ?? []) as Finding[];+ expect(finding).toMatchObject({ name: 'member-example', argv: null });+ expect([...finding!.by_name_operations].sort()).toEqual(['join_brain', 'leave_brain', 'sync_brain_skills']);+ expect(finding!.by_name_argv).not.toBeNull();+ expect(byNameOnly.status).toBe('ok');+ expect(byNameOnly.fix).toBeUndefined();+ expect(byNameOnly.message).toContain(`member-example (`);+ expect(byNameOnly.message).toContain(finding!.by_name_operations.join(', '));+ expect(byNameOnly.message).toContain(finding!.by_name_argv!.slice(0, 3).join(' '));++ await mintLegacyToken(engine, { name: 'token-example', scopes, takesHolders: ['world'],+ allowedOperations: profile.allowedOperations!.filter(op => op !== 'put_pages') });+ const mixed = await checkGrantNewOps(engine, { cfg });+ expect(mixed.status).toBe('warn');+ expect(((mixed.details?.grants ?? []) as Finding[]).map(f => f.name).sort()).toEqual(['member-example', 'token-example']);+ expect(mixed.fix).toBeDefined();+}, 120_000);diff --git a/test/doctor-upgrade-ledger-existing-brain.test.ts b/test/doctor-upgrade-ledger-existing-brain.test.tsnew file mode 100644index 0000000000..860d32548b--- /dev/null+++ b/test/doctor-upgrade-ledger-existing-brain.test.ts@@ -0,0 +1,71 @@+/**+ * GBRA-541 4a/4b: the upgrade-migration ledger lives under GBRAIN_HOME, so an empty one is a fresh brain only when the+ * brain's schema is new too. A brain an older release last opened, reopened with an empty ledger, gets doctor's+ * minions_migration warn naming the upgrade migrations; a brain created in this run, or one whose schema is already+ * current (a new or rebuilt GBRAIN_HOME), does not. Real PGLite engines on data dirs, isolated GBRAIN_HOME.+ */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import { mkdtempSync, rmSync } from 'node:fs';+import { join } from 'node:path';+import { tmpdir } from 'node:os';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { hasPendingMigrations } from '../src/core/migrate-pending.ts';+import { buildChecks } from '../src/commands/doctor.ts';+import { MIGRATION_VERSIONS } from '../src/core/migration-ledger.ts';+import { LATEST_SCHEMA_VERSION } from '../src/core/schema-migrations/latest.generated.ts';+import { withEnv } from './helpers/with-env.ts';++const dir = mkdtempSync(join(tmpdir(), 'gbrain-upgrade-ledger-'));+const olderDir = join(dir, 'older.pglite');+const currentDir = join(dir, 'current.pglite');++beforeAll(async () => {+ for (const dataDir of [olderDir, currentDir]) {+ const created = new PGLiteEngine();+ await created.connect({ database_path: dataDir });+ await created.initSchema();+ if (dataDir === olderDir) await created.setConfig('version', String(LATEST_SCHEMA_VERSION - 1));+ await created.disconnect();+ }+}, 240_000);+afterAll(() => { rmSync(dir, { recursive: true, force: true }); });++async function minionsRow(engine: PGLiteEngine) {+ const home = mkdtempSync(join(dir, 'home-'));+ return withEnv({ GBRAIN_HOME: home, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined }, async () =>+ (await buildChecks(engine, ['--fast', '--json'])).find(c => c.name === 'minions_migration'));+}++describe('doctor on an existing brain with an empty upgrade ledger', () => {+ test('a brain an older release last opened gets the upgrade migrations that have not run on it', async () => {+ const engine = new PGLiteEngine();+ await engine.connect({ database_path: olderDir });+ try {+ expect(await hasPendingMigrations(engine)).toBe(true);+ const row = await minionsRow(engine);+ expect(row?.status).toBe('warn');+ expect(row?.message).toContain('have not run on this brain yet');+ expect((row?.details as { pending: string[] }).pending).toContain(MIGRATION_VERSIONS[MIGRATION_VERSIONS.length - 1]!);+ } finally { await engine.disconnect(); }+ }, 120_000);++ test('a brain whose schema is already current stays quiet', async () => {+ const engine = new PGLiteEngine();+ await engine.connect({ database_path: currentDir });+ try {+ expect(await hasPendingMigrations(engine)).toBe(false);+ const row = await minionsRow(engine);+ expect(row?.message ?? '').not.toContain('have not run on this brain yet');+ } finally { await engine.disconnect(); }+ }, 120_000);++ test('a brain created in this run stays quiet', async () => {+ const engine = new PGLiteEngine();+ await engine.connect({});+ await engine.initSchema();+ try {+ const row = await minionsRow(engine);+ expect(row?.message ?? '').not.toContain('have not run on this brain yet');+ } finally { await engine.disconnect(); }+ }, 120_000);+});diff --git a/test/import-calls.test.ts b/test/import-calls.test.tsindex 8133d3fca0..ee5ea72617 100644--- a/test/import-calls.test.ts+++ b/test/import-calls.test.ts@@ -24,12 +24,17 @@ import { _resetCliExitVerdictForTests, currentExitCode } from '../src/core/cli-fimport { PGLiteEngine } from '../src/core/pglite-engine.ts';import { parseMarkdown } from '../src/core/markdown.ts';import { listBudgetLimitedPages, planPageEmbedding } from '../src/core/page-embedding-budget.ts';+import { acquireWorktree, getWorktreeBinding } from '../src/core/persistence/ownership.ts';+import { disposePersistenceConsumer, startPersistenceConsumer } from '../src/core/persistence/service.ts';+import { withEnv } from './helpers/with-env.ts';const roots: string[] = [];afterAll(() => { for (const r of roots) rmSync(r, { recursive: true, force: true }); });const temp = (prefix: string): string => { const d = mkdtempSync(join(tmpdir(), prefix)); roots.push(d); return d; };const plantedToken = (): string => 'github' + '_pat_' + randomBytes(24).toString('hex');const MTIME = new Date(2026, 0, 15, 12).getTime();+/** A put_page wait short enough that a write held behind the worktree lock answers pending at once. */+const SHORT_WRITE_WAIT_MS = 200;describe('call pages', () => {test('date and title come from a dated file name, else the first line, else the modified day', () => {@@ -291,3 +296,82 @@ describe('call import, in process', () => {expect(lines.join('\n')).toContain(`gbrain write-request -- ${requestId}`);});});++describe('call import finds the same file across import roots and pending writes', () => {+ let engine: PGLiteEngine;+ beforeAll(async () => { engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema(); }, 120_000);+ afterAll(async () => { await disposePersistenceConsumer(engine); await engine.disconnect(); });+ beforeEach(() => _resetCliExitVerdictForTests());+ afterEach(() => mock.restore());++ const callPages = (prefix: string) => engine.executeRaw<{ slug: string }>(+ "SELECT slug FROM pages WHERE source_id='default' AND deleted_at IS NULL AND starts_with(slug, $1) ORDER BY slug", [`${prefix}/`]);++ test('a file in a subfolder of an imported folder is found by a single-file import, and the other way round', async () => {+ const calls = realpathSync(temp('gbrain-calls-nested-'));+ mkdirSync(join(calls, 'team-a'));+ mkdirSync(join(calls, 'team-b'));+ writeFileSync(join(calls, 'team-a', 'Kickoff call.txt'), 'Kickoff call\nAlice: kickoff.\n');+ writeFileSync(join(calls, 'team-b', 'Review call.txt'), 'Review call\nAlice: review.\n');+ for (const f of ['team-a/Kickoff call.txt', 'team-b/Review call.txt']) utimesSync(join(calls, f), MTIME / 1000, MTIME / 1000);+ spyOn(console, 'log').mockImplementation(() => {});+ expect(await runCallImport(engine, join(calls, 'team-b', 'Review call.txt'), ['--calls', '--prefix', 'nested'], { json: false })).toMatchObject({ imported: 1, errors: 0 });+ expect(await runCallImport(engine, calls, ['--calls', '--prefix', 'nested'], { json: false })).toMatchObject({ imported: 1, errors: 0 });+ expect(await runCallImport(engine, join(calls, 'team-a', 'Kickoff call.txt'), ['--calls', '--prefix', 'nested'], { json: false })).toMatchObject({ imported: 0, errors: 0 });+ expect(await runCallImport(engine, join(calls, 'team-a'), ['--calls', '--prefix', 'nested'], { json: false })).toMatchObject({ imported: 0, errors: 0 });+ expect((await callPages('nested')).map(p => p.slug)).toEqual(['nested/2026-01-15-kickoff-call', 'nested/2026-01-15-review-call']);+ });++ test('a rerun while the first write is still pending finds the pending request and writes nothing', async () => {+ const fixture = realpathSync(temp('gbrain-calls-pending-rerun-'));+ const calls = join(fixture, 'calls');+ mkdirSync(join(fixture, 'brain'));+ mkdirSync(calls);+ const managed = new PGLiteEngine();+ await managed.connect({});+ await managed.initSchema();+ await managed.setConfig('sync.repo_path', join(fixture, 'brain'));+ await withEnv({ GBRAIN_HOME: join(fixture, 'home') }, async () => {+ spyOn(console, 'log').mockImplementation(() => {});+ startPersistenceConsumer(managed, { engine: 'pglite' });+ writeFileSync(join(calls, 'Seed call.txt'), 'Seed call\nAlice: seed.\n');+ expect(await runCallImport(managed, calls, ['--calls', '--prefix', 'held'], { json: false })).toMatchObject({ imported: 1, errors: 0 });+ const put = operations.find(op => op.name === 'put_page')!;+ const handler = put.handler;+ spyOn(put, 'handler').mockImplementation(((ctx: Parameters<typeof handler>[0], params: Parameters<typeof handler>[1]) => handler({ ...ctx, writeWaitMs: SHORT_WRITE_WAIT_MS }, params)) as never);+ const file = join(calls, 'Pending call.txt');+ writeFileSync(file, 'Pending call\nAlice: pending.\n');+ utimesSync(file, MTIME / 1000, MTIME / 1000);+ const requests = () => managed.executeRaw<{ slug: string; request_id: string }>(+ "SELECT slug, request_id::text AS request_id FROM persistence_requests WHERE source_id='default' AND operation='put_page' AND slug LIKE 'held/%pending-call' ORDER BY sequence");+ const lock = (await acquireWorktree((await getWorktreeBinding(managed, 'default'))!))!;+ try {+ expect(await runCallImport(managed, calls, ['--calls', '--prefix', 'held'], { json: false })).toMatchObject({ imported: 0, errors: 0 });+ expect(currentExitCode()).toBe(10);+ const [pending] = await requests();+ expect(pending).toBeDefined();+ utimesSync(file, MTIME / 1000 + 3 * 86_400, MTIME / 1000 + 3 * 86_400);+ _resetCliExitVerdictForTests();+ const lines: string[] = [];+ spyOn(console, 'log').mockImplementation((line: string) => { lines.push(line); });+ expect(await runCallImport(managed, calls, ['--calls', '--prefix', 'held'], { json: false })).toMatchObject({ imported: 0, errors: 0 });+ expect(currentExitCode()).toBe(10);+ expect(await requests()).toEqual([pending!]);+ expect(lines.join('\n')).toContain(`gbrain write-request -- ${pending!.request_id}`);+ await withEnv({ GBRAIN_ACCEPT_PENDING: '1' }, async () => {+ _resetCliExitVerdictForTests();+ expect(await runCallImport(managed, calls, ['--calls', '--prefix', 'held'], { json: false })).toMatchObject({ imported: 0, errors: 0 });+ expect(currentExitCode()).toBe(0);+ const read = operations.find(op => op.name === 'get_write_request')!;+ const readHandler = read.handler;+ spyOn(read, 'handler').mockImplementation((async (ctx: Parameters<typeof readHandler>[0], params: Parameters<typeof readHandler>[1]) =>+ ({ ...await readHandler(ctx, params) as object, diagnostic: { reason: 'owner_unavailable', next_action: 'inspect_owner', owner: { last_active: '2026-01-01T00:00:00Z' } } })) as never);+ _resetCliExitVerdictForTests();+ expect(await runCallImport(managed, calls, ['--calls', '--prefix', 'held'], { json: false })).toMatchObject({ imported: 0, errors: 0 });+ expect(currentExitCode()).toBe(10);+ });+ expect(await requests()).toEqual([pending!]);+ } finally { await lock.release(); }+ }).finally(async () => { await disposePersistenceConsumer(managed); await managed.disconnect(); });+ }, 120_000);+});diff --git a/test/init-force-embedding-db-plane-9451.test.ts b/test/init-force-embedding-db-plane-9451.test.tsnew file mode 100644index 0000000000..f9736d95cf--- /dev/null+++ b/test/init-force-embedding-db-plane-9451.test.ts@@ -0,0 +1,28 @@+/**+ * #9451: `gbrain init --force --embedding-model X` on a keyless PGLite brain moved the file plane to X but left the+ * database plane's embedding_model on the new-install default, so fact and take vectors, doctor and+ * `migrate embeddings --status` kept targeting a model the brain no longer uses. With no stored vectors from another+ * model, the re-init now records X in both planes.+ */+import { afterAll, expect, test } from 'bun:test';+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { runCli } from './helpers/cli-spawn.ts';++const root = mkdtempSync(join(tmpdir(), 'gbrain-9451-'));+afterAll(() => rmSync(root, { recursive: true, force: true }));++test('init --force --embedding-model on a keyless PGLite brain moves the database plane to the new model', async () => {+ const home = join(root, 'home');+ mkdirSync(home);+ const env = { HOME: home, GBRAIN_HOME: home, DATABASE_URL: undefined, GBRAIN_DATABASE_URL: undefined, GBRAIN_SOURCE: undefined, GBRAIN_SKIP_STARTUP_HOOKS: '1',+ OPENAI_API_KEY: undefined, VOYAGE_API_KEY: undefined, ANTHROPIC_API_KEY: undefined, GEMINI_API_KEY: undefined, GBRAIN_EMBEDDING_MODEL: undefined, GBRAIN_EMBEDDING_DIMENSIONS: undefined };+ expect((await runCli(['init', '--pglite', '--no-embedding', '--json'], { env })).exitCode).toBe(0);+ const reinit = await runCli(['init', '--force', '--pglite', '--embedding-model', 'ollama:mxbai-embed-large', '--embedding-dimensions', '1024', '--skip-embed-check', '--json'], { env });+ expect(reinit.exitCode).toBe(0);+ const status = await runCli(['migrate', 'embeddings', '--status', '--json'], { env });+ const doc = JSON.parse(status.stdout) as { file_plane: { model: string; dims: number }; db_plane: { model: string; dims: string } };+ expect(doc.file_plane).toEqual({ model: 'ollama:mxbai-embed-large', dims: 1024 });+ expect(doc.db_plane).toEqual({ model: 'ollama:mxbai-embed-large', dims: '1024' });+}, 240_000);diff --git a/test/migrations-notice.test.ts b/test/migrations-notice.test.tsindex 4b77cd1023..61e6fccc30 100644--- a/test/migrations-notice.test.ts+++ b/test/migrations-notice.test.ts@@ -11,6 +11,8 @@ 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';+import { noteSchemaVersion } from '../src/core/migrate-pending.ts';+import { LATEST_SCHEMA_VERSION } from '../src/core/schema-migrations/latest.generated.ts';const engine = { getConfig: async () => null } as never;const homes: string[] = [];@@ -65,7 +67,7 @@ describe('pendingUpgradeMigrationsNotice', () => {});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']) {+ for (const command of ['apply-migrations', 'post-upgrade', 'upgrade', 'doctor', 'init', 'setup']) {const notice = await inHome(async () => {appendCompletedMigration({ version: MIGRATION_VERSIONS[0]!, status: 'complete' } as never);return pendingUpgradeMigrationsNotice(engine, command, latest);@@ -73,4 +75,33 @@ describe('pendingUpgradeMigrationsNotice', () => {expect(notice).toBeNull();}});++ test('gbrain serve gets the notice, since a brain used only over MCP runs no other command', async () => {+ const notice = await inHome(async () => {+ appendCompletedMigration({ version: MIGRATION_VERSIONS[0]!, status: 'complete' } as never);+ return pendingUpgradeMigrationsNotice(engine, 'serve', latest);+ });+ expect(notice).toMatchObject({ code: 'migrations_pending' });+ });++ test('an empty ledger on a brain an older release last opened still gets the notice', async () => {+ const existing = { getConfig: async () => null } as never;+ noteSchemaVersion(existing, LATEST_SCHEMA_VERSION - 1);+ const notice = await inHome(() => pendingUpgradeMigrationsNotice(existing, 'query', latest));+ expect(notice).toMatchObject({ code: 'migrations_pending' });+ expect(notice!.why).toContain(latest);+ });++ test('an empty ledger on a brain whose schema is already current (a new or rebuilt GBRAIN_HOME) gets no notice', async () => {+ const current = { getConfig: async () => null } as never;+ noteSchemaVersion(current, LATEST_SCHEMA_VERSION);+ expect(await inHome(() => pendingUpgradeMigrationsNotice(current, 'query', latest))).toBeNull();+ });++ test('an empty ledger on a brain created in this run (schema version 1 at connect) gets no notice', async () => {+ const created = { getConfig: async () => null } as never;+ noteSchemaVersion(created, 1);+ noteSchemaVersion(created, 316);+ expect(await inHome(() => pendingUpgradeMigrationsNotice(created, 'query', latest))).toBeNull();+ });});diff --git a/test/release-workflow.test.ts b/test/release-workflow.test.tsindex 3abe16745f..2fd23ebed5 100644--- a/test/release-workflow.test.ts+++ b/test/release-workflow.test.ts@@ -249,6 +249,21 @@ describe('scripts/changelog-entry.sh --pr-list', () => {}});+ test('a headline that ends in an internal issue code drops the code and keeps the pull request bracket', () => {+ const repo = fixture();+ try {+ commit(repo, 'Doctor names the fix (GST-2731) (#21)', { 'changelog.d/e-eps.md': '**Doctor names the fix (GST-2731).**\n' });+ commit(repo, 'Direct note', { 'changelog.d/f-zeta.md': '**Import keeps calls apart (ABC-7)**\n' });+ commit(repo, 'Release notes cite issues (#22)', { 'changelog.d/g-eta.md': '**Release notes keep the (ENG-5) code they quote, and PROJECT-9 codes too (TOOLONG-3).**\n' });+ commit(repo, 'v0.1.1.0 release (#23)', { VERSION: '0.1.1.0\n', 'CHANGELOG.md': section('0.1.1.0', 'Folded.'), 'changelog.d/a-alpha.md': null, 'changelog.d/b-beta.md': null,+ 'changelog.d/e-eps.md': null, 'changelog.d/f-zeta.md': null, 'changelog.d/g-eta.md': null });+ expect(run(repo, '--pr-list', '0.1.1.0')).toBe('- Search finds old pages again (#12)\n- Sync is faster (#11)\n- Doctor names the fix (#21)\n- Import keeps calls apart\n'+ + '- Release notes keep the (ENG-5) code they quote, and PROJECT-9 codes too (TOOLONG-3) (#22)\n\n\nFolded.\n');+ } finally {+ rmSync(repo, { recursive: true, force: true });+ }+ });+test('with no earlier release tag the body is the plain entry', () => {const repo = fixture();try {