Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Fix doctor's grant repair command, storage shelf adopt and find, and seven smaller bugs (#9447)

Garry Tane5e2b6215cb3
diff --git a/changelog.d/capy-small-fix-wave-2.md b/changelog.d/capy-small-fix-wave-2.md
new file mode 100644
index 0000000000..4948d7ced3
--- /dev/null
+++ b/changelog.d/capy-small-fix-wave-2.md
@@ -0,0 +1,20 @@
+**Fifteen small fixes: the doctor's grant repair grants every operation it counted except the ones you approve by name, call import handles single files, look-alike names and pending writes, a folder whose own `.git` is not a repository is no longer taken as a checkout, storage adopt reports what it did, and doctor's type check reads through an index.**
+
+### Fixed
+- `gbrain doctor` (grant_new_ops_available) now prints a repair that grants every operation it counted as missing from a token's or OAuth client's grant, not only `put_pages`, and its preview is the same command with `--dry-run`, which shows each changed grant line as before and after. Membership operations (`join_brain`, `sync_brain_skills`, `leave_brain`), which you approve by name, are left out of that repair and listed apart with their own command. The apply still needs your agreement.
+- `gbrain import <file> --calls` imports that one call file instead of reporting success with nothing imported; a file that is not `.txt` or `.md` is reported as an error.
+- Call import keeps two files apart when a redaction pattern makes their names look the same, so the second file is imported instead of being treated as the first. Pages imported before this release are still found on a rerun.
+- Call import reports a write that was accepted but is still being saved as pending, with the command that reads its receipt, and exits 10 instead of counting it as a failure.
+- A folder whose own `.git` is not a repository (an empty `.git` folder, or a `.git` file pointing at a missing directory) is no longer taken as its own checkout, and when that folder sits untracked inside a real repository, gbrain no longer writes its managed marker into that repository, which made writes elsewhere in it fail with `writer_coordinator_required`.
+- `gbrain doctor` (type_proliferation) reads the distinct source and type pairs through a new index on pages (schema migration 316) instead of scanning every page, which took over 20 seconds on a large brain.
+- `gbrain storage adopt --apply` on a hosted shelf now indexes the cards it committed, so the shelf's sync checkpoint no longer lags until a manual sync; when it cannot, it prints the sync command to run.
+- `gbrain storage adopt --apply --json` counts adopted, skipped, refused and pending records and gives each write its receipt id.
+- `gbrain storage adopt` reports a record cut off by its 64 KiB read as `truncated`, and says to move the `## Record` section to the top, instead of reporting the record as missing.
+- Atom extraction skips the storage shelf, and doctor no longer names the shelf as a source with held atoms.
+- `gbrain storage-find` reports a card asked for by its exact title as an exact hit, not as a closest match.
+- An empty storage location path now says to write `/` for an item at the root of its bucket or repository.
+- Sync no longer tells you to restart a `gbrain serve` that already runs your gbrain version.
+- Owner sessions whose first message starts with a Claude Code slash command (such as `/clear` or `/model`) are no longer classed as launched by an agent (#9390).
+
+### Changed
+- The graduation tests bound and retry their git calls to the remote, so a hung fetch fails fast with a clear error.
diff --git a/docs/architecture/key-files/ambient-capture.md b/docs/architecture/key-files/ambient-capture.md
index 63009a257f..5a920daa9e 100644
--- a/docs/architecture/key-files/ambient-capture.md
+++ b/docs/architecture/key-files/ambient-capture.md
@@ -11,4 +11,4 @@ Key files:
- `src/core/context/capture-consent.ts` + `src/core/facts/capture-sources.ts` (+ `captureGateDecision` in `src/core/facts/writeback-config.ts`) — `captureGateDecision(cfg, lane)` is the ONE truth table for the ambient capture lanes (`writeback` = `.wb-` Stop-hook turns, `compact` = PreCompact segments + OpenClaw compactions, `session_end` = SessionEnd `<sid>.txt`): explicit `off` retires every lane; unset retires `writeback` and extracts `compact`/`session_end` (the hooks are their opt-in); read error, plane drift, invalid mode, and (compact/session_end) a DB-absent file-mirror `off` (`off_unsynced`) hold. `captureLaneStates`/`captureLaneSummary`/`writebackOffMessage`/`writebackUnsetMessage`/`WRITEBACK_RESTART_AFTER_OFF` render it for `config set|unset|get` (stderr lane line), doctor `memory_writeback` (`details.capture_lanes`, `details.restart_after_off`) and the guide's truth table. `src/core/context/capture-consent.ts`: capture side `recordCaptureIfOff` (the PreCompact `bankCompactSegment` `beforeWrite` callback, the SessionEnd corpus write and the OpenClaw spool write this brain's own `<file>.capture-off.<brain>.json` (`captureOffRecordPath`; brain identity = hash of the resolved config dir, turn hashes via `corpus-turns.ts`) BEFORE the file lands, unioning a pre-wave-12 single `<file>.capture-off.json` that names this brain, so two brains sharing a corpus directory never overwrite each other's off turns; GC (`corpus-segments.ts`, `CAPTURE_OFF_INFIX`) reaps any brain's orphan record only after the seat grace); extraction side `resolveCaptureGate` + `applyCaptureGate` (hold / `retireCorpusFile` / fold this brain's turns, own record plus a matching legacy record, via `retireCorpusTurns`, retiring a file whose every turn was captured under off; foreign-brain records ignored; an unreadable or invalid record holds `capture_record_unreadable` and makes `recordCaptureIfOff` throw, never reads as "no record"), called under the claim before any provider call or receipt republish in `checkpoint-harvest.ts` (`runOne`, `runWritebackTurn`), `context-engine.ts` rung 3 and `sweep.ts` (including the keyless/extraction-disabled early returns). Publication side: `src/core/facts/capture-sources.ts` holds `FACTS_BACKSTOP_SOURCES` (`as const`; `FactsBackstopCtx['source']` derives from it), the ambient subset, `captureGateLaneForSource` and `assertAmbientCaptureAdmissible` (code `ambient_capture_off`), re-checked inside `admitManagedFactsBatch`'s transaction (`facts-maintenance.ts`; sessions and intents carry `captureSource` / `capture_source`, so #6048 follow-up batches are re-checked too) and before the unmanaged fence write in `backstop.ts`; requests admitted before `off` publish. Tests: `test/capture-consent-gate.serial.test.ts`, `test/capture-consent-admission.test.ts` (PGLite + Postgres), `test/capture-consent-inventory.test.ts`. Retired turn hashes also land in `.progress` `retired_turns` (`retireCorpusFile`, `retireCorpusTurns`); `planCorpusWindows` skips them wherever a rewrite places them, and `withoutOffPeriodTurns` (capture-consent.ts) strips them from what `discoverTranscripts` hands dream synthesis.
- `src/core/context-engine.ts` + `src/openclaw-context-engine.ts` — the deterministic context engine OpenClaw loads on every turn (`assemble()` injects the Live Context block, zero-LLM). `createGBrainContextEngine({workspaceDir, resolveEntities?})` accepts an OPTIONAL host-injected resolver (`ENGINE_API_VERSION` 0.3.0, additive — older hosts work unchanged; the plugin entry maps `ctx.resolveEntities`/`ctx.brainQuery` onto it). Checkpoint compaction: `compact()` runs a time-bounded (8s), fail-open, lazily-imported checkpoint step BEFORE delegating — spools the since-last-boundary window (openclaw tail reader over the exported adapter mapper, 40-turn cap = the no-prior-boundary fallback) as a content-addressed corpus segment + ledger entry, then rung 2 (PGLite: one `bankOnly`+`flushCorpusFile` IPC round trip to serve) or rung 3 (Postgres: inline harvest over the reflex ladder's exported `getDirectPostgresEngine` singleton, under sweep claim fencing + capability/kill-switch gates, abort post-check) — and rides an additive `result.gbrain_checkpoint` bag on the delegate's return (`ownsCompaction` stays false). After the segment is spooled, the Memorable receipt lane runs (gate + stamp via `memorableGateAllowed`, span-filtered redacted tool calls, `recordAndRelayReceipt` with `harness: 'openclaw'` — per-compaction capture, content-hash dedup on retries, fail-open for the checkpoint; the whole block is skipped once the host's compact() deadline has fired; the rendered segment text is re-scanned with highEntropy at receipt time and the relay REFUSED fail-closed on any hit — the segment rendering feeds the ledger hash and cannot change, so the next compaction window re-evaluates; this lane NEVER compacts the receipts file — the hook lane is the ONE compactor, single-rewriter rule — but DOES trim the relay file, since an openclaw-only host has no hook lane and converging newest-keeping trims make concurrent trims safe). `assemble()` consumes `sessionId ?? sessionKey` and splices a deterministic envelope-bearing Compaction-checkpoint block at parts[1] (after Live Context) from the banked manifest via an in-process memo + hash-keyed polls (≤5; stale manifests can't satisfy a poll for the new segment; no manifest ⇒ byte-identical output). `assemble()` runs the Retrieval Reflex after the Live Context block: extracts the current turn's user text, builds prior-context text (every message EXCEPT the current turn — suppression must not see the triggering mention), passes the rolling window (`getWindowTurns`, last 12 user/assistant turns; the reflex slices to its configured `retrieval_reflex_window_turns`), and appends the pointer block. `warmReflex()` fires at construction. Current-host plugin factories may be called with zero arguments. The host workspace takes precedence; ambiguous/unbound legacy fallback warns and reads no source. The canonical slot ID is `gbrain-context-engine`; `gbrain-context` remains a registry alias, not a current-host slot alias. The exclusive context-engine contract and no-write stateless admitted-turn acknowledgement are additive. `assemble` uses an authoritative separate prompt: sqlite transcript-storage metadata fences historic turns, whereas an identical final legacy user message already represents the current turn. Reflex-only synthesis leaves messages intact; absent prompt keeps message extraction. These contracts do not prove model recall. `compact()` records the session's seat sidecar (`context/seat.ts`, harness `openclaw`, seat keyed to the agent directory holding `sessions/`) before spooling the segment; a failure never fails the checkpoint. A sub-agent session (`isOpenClawSubagentKey`: `agent:<id>:subagent:<uuid>`) is marked first with a speaker sidecar (`agent-launched`, #8080; nothing is banked when it cannot be written), and rung 3 passes the speaker to the facts pipeline. OpenClaw 2026.9.x calls `compact()` with a `sessionTarget` and no `sessionFile`; `readCompactTail` then reads the transcript through the host's `openclaw/plugin-sdk/session-transcript-runtime` (`readSessionTranscriptEvents`, lazily imported; `__setTranscriptRuntimeLoaderForTests` is the seam) and maps the events with the JSONL mapper (`readOpenclawEventsTail` in `corpus-segments.ts`), keeping the file path for older hosts. Every compaction writes one `openclaw-compact` heartbeat (status and reason codes); doctor `memory_writeback` warns when a week of compactions banked none (`details.openclaw_compactions_7d`). Pinned-host proof: `test/openclaw-context-engine-native.serial.test.ts` (gateway plus `openclaw sessions compact`); fake runtime: `test/openclaw-compact-transcript-runtime.serial.test.ts`.
- `src/commands/doctor/checks/agent-session-facts.ts` — `agent_session_facts` (wave check, host-only, #8064): counts active owner-attributed capture-lane facts `classifyAgentSessionFacts` classes `evidenced` (speaker sidecar; no operator flags) or `ambiguous` (repeated first user turn); `excluded` and `unclassifiable` are reported, never a finding. Names `gbrain repair agent-session-facts` (explicit-only) and says the apply needs the user's agreement. Read-only; health unknown when the scan fails.
-- `src/core/repair/agent-session-facts.ts` — `gbrain repair agent-session-facts` (#8064), explicit-only, preview-bound and destructive (`--apply --expect <hash> --yes`). `classifyAgentSessionFacts` (read-only; also doctor `agent_session_facts`) takes active capture-lane facts attributed to `user` or nobody and classes each by its session (`captureSessionId`): `evidenced` by a speaker sidecar (`readSpeakerSidecar` in the corpus dir, its spool dir or beside the session's files), an operator `--session <id>`, or a `<sid>.source.json` cwd under an operator `--cwd <prefix>` (realpath, path-boundary compare); `ambiguous` when the session's first user turn (head of its earliest retained file, whitespace-normalized, lowercased, at least 40 chars) shares its first 160 chars with 3+ other sessions; `excluded:owner_also_said` when the claim and entity also have an active user-attributed row from a non-suspect session; no retained corpus, sidecar or record is `unclassifiable`. `agentSessionTakes` lists active, unresolved fact/self takes whose every `consolidated_into` fact is non-user once the approved facts are. Approved items, one write each: fact pages (phase 0; a page with database-only and fenced rows is two items, the fenced one after every fact page, so a pending database write never skips its fenced rows) then take pages (phase 1); one apply run builds the corpus index once (`PageItem.indexes`). The apply rechecks each row; fenced facts get `attributed_to: other` and `speakerContextNote(principal)` in the `## Facts` fence and fenced takes are struck in the takes fence, each by one revision-bound `put_page`; database-only facts and takes change through one `managed_maintenance_agent_session_facts` request per page on a managed brain (`prepareAgentSessionFactsWrite`, dispatched from `prepareMaintenanceMutation`) or one `maintenanceTransaction` otherwise (`applyAgentSessionWrite` rechecks under the row lock). Nothing is deleted. Pinned by `test/repair-agent-session-facts.test.ts`.
+- `src/core/repair/agent-session-facts.ts` — `gbrain repair agent-session-facts` (#8064), explicit-only, preview-bound and destructive (`--apply --expect <hash> --yes`). `classifyAgentSessionFacts` (read-only; also doctor `agent_session_facts`) takes active capture-lane facts attributed to `user` or nobody and classes each by its session (`captureSessionId`): `evidenced` by a speaker sidecar (`readSpeakerSidecar` in the corpus dir, its spool dir or beside the session's files), an operator `--session <id>`, or a `<sid>.source.json` cwd under an operator `--cwd <prefix>` (realpath, path-boundary compare); `ambiguous` when the session's first user turn with owner text (head of its earliest retained file, Claude Code slash-command and caveat blocks dropped (#9390), whitespace-normalized, lowercased, at least 40 chars) shares its first 160 chars with 3+ other sessions; `excluded:owner_also_said` when the claim and entity also have an active user-attributed row from a non-suspect session; no retained corpus, sidecar or record is `unclassifiable`. `agentSessionTakes` lists active, unresolved fact/self takes whose every `consolidated_into` fact is non-user once the approved facts are. Approved items, one write each: fact pages (phase 0; a page with database-only and fenced rows is two items, the fenced one after every fact page, so a pending database write never skips its fenced rows) then take pages (phase 1); one apply run builds the corpus index once (`PageItem.indexes`). The apply rechecks each row; fenced facts get `attributed_to: other` and `speakerContextNote(principal)` in the `## Facts` fence and fenced takes are struck in the takes fence, each by one revision-bound `put_page`; database-only facts and takes change through one `managed_maintenance_agent_session_facts` request per page on a managed brain (`prepareAgentSessionFactsWrite`, dispatched from `prepareMaintenanceMutation`) or one `maintenanceTransaction` otherwise (`applyAgentSessionWrite` rechecks under the row lock). Nothing is deleted. Pinned by `test/repair-agent-session-facts.test.ts`.
diff --git a/docs/architecture/key-files/commands-5-continued.md b/docs/architecture/key-files/commands-5-continued.md
index 685f86b436..fefd5af896 100644
--- a/docs/architecture/key-files/commands-5-continued.md
+++ b/docs/architecture/key-files/commands-5-continued.md
@@ -21,4 +21,4 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/commands/storage.ts` — `gbrain storage status [--repo P] [--json]`. Split into pure data (`getStorageStatus`) + JSON formatter + human formatter (ASCII-only) matching the `orphans.ts` pattern. `PageCountsByTier` and `DiskUsageByTier` are distinct nominal types so swaps fail at compile time. The repo and the counted source come from `resolveRestoreTarget` (`src/core/restore-target.ts`, the `export --restore-only` rule), and a page is listed missing exactly when that export would restore it (`isDbOnly`, then `restoreFilePath` in the page source's `scannerSlugRootMode` and `nativeFileTarget`: the recorded `source_path`, else `<slug>.md`, absent; the repo walk answers without a per-page syscall whenever it saw that exact file as a regular file under real directories, and a recorded path starting with the repo's path inside its git checkout, which export re-anchors, takes the full check), so the printed `Use: gbrain export --restore-only --source <id> --repo <path>` (the path passed through `shellQuote`, `src/core/shell-quote.ts`) writes exactly the listed files into `--dir` (default `./export`, not the repo). An unsafe recorded path or a symlinked/ambiguous file target (`OperationError` from `nativeFileTarget`) becomes one warning per reason (lowest slug plus a count of further pages) plus the refusal export would give, printed even when no file is missing; a repo whose own owner (`resolveSourceForRepoPath`: dotfile, then longest registered `local_path`) is archived is refused too (unless an active source is registered at the repo's exact path, which owns it outright), although export's exact-path rule would fall back to the only active source; a refused rule prints `Cannot suggest a restore command:` and falls back to the `--repo` / default-source path, counting the active repo owner's pages (dotfile, then longest registered `local_path`) or every source's pages when no active source owns it. `restoreSource` / `restoreRefusal` carry this in the JSON result. Pinned by `test/storage-restore-hint.test.ts`. The storage shelf subcommands (GST-1943) are `storage init`, `storage adopt` (preview, `--apply --expect`, `--finalize [--expect]`; logic in `src/core/storage-manifest/adopt.ts`) and `storage export|import --jsonl` (`src/core/storage-manifest/jsonl.ts`); each builds a trusted local `OperationContext` and renders refusals with `writeCliError`.
- `src/core/storage-manifest/schema.ts`, `src/core/storage-manifest/door.ts`, `src/core/storage-manifest/source.ts`, `src/core/storage-manifest/find.ts` and `src/core/ops/storage-manifest.ts` — GST-1943 storage shelf (guide: `docs/guides/storage-manifest.md`). A card is a `type: stored-object` page in source `storage` whose card sits under the `storage` frontmatter key (`title` and `aliases` are the page's own); `parseCardInput` validates every write (strict shapes, `credentialShape` and the secret scanner on string fields, `isCommandKey` on every key, `registered_by` and `origin` stamped by gbrain only, `restore` as `{ skill, args }` with flat scalar args), and `cardDigest` compares two copies. `door.ts` holds the source id, the role `storage_manifest` and the `STORAGE_DOOR` symbol the verbs set on their context, which no request parameter can carry; `assertStorageSourceWriter`, called by the page door (`page-mutations.ts`) and `remember`/`forget` (`memory-mutations.ts`), refuses every other writer `storage_source_managed`, except the owner's import of commits already in the hosted repository. `source.ts`: `shelfWritable`/`ensureStorageSource` create the database-only, non-federated shelf on a repo-less brain's first register, finish a creation that stopped part way, refuse an archived shelf or a `storage` source that is someone else's, and on a repo brain refuse `storage_manifest_missing` until `initStorageSource` (`gbrain storage init`, preview then `--expect`, through `hostRepo`, needs managed persistence) hosts it. `find.ts`: keyless ranked lookup in one statement (exact id, `page_aliases`, word matches over title, aliases and body, then `pg_trgm` closest cards on a miss) under the caller's read policy. The ops: `storage_find`, `storage_get` and `storage_list` read under the caller's grant (`federatedSearchScope`, so a remote client needs a grant naming `storage`), and `storage_get` refuses `storage_record_invalid`, with the revision, for a stored card that fails the rules; `storage_register` and `storage_update` are trusted-local only, write through `submitPageMutation` with the door mark, never overwrite (`storage_card_exists`), bind an update to `expected_revision` (`storage_revision_conflict`) and keep the page's `PROTECTED_FRONTMATTER_KEYS` (access labels included). Pinned by `test/storage-manifest.test.ts`, `test/storage-manifest-hosted.test.ts` and `test/e2e/storage-manifest-postgres.test.ts`.
-- `src/core/storage-manifest/adopt.ts`, `src/core/storage-manifest/jsonl.ts` and `src/commands/doctor/checks/storage-manifest.ts` — GST-1943 storage shelf recovery. Adopt reads interim `stored-object` pages under a prefix (never `<prefix>index`) from the bounded body prefix (`boundedBodyPrefixSql`), takes the JSON block under `## Record`, strips every field the card refuses (`command_field`, `unknown_field`, `stamped_field`; `CARD_KEYS` in `schema.ts`) and validates the rest with `parseCardInput`; a credential-shaped value (`credentialShape`) blocks the page whatever is dropped. Apply registers through `registerCard` (`origin: adopt`) and tags the original `storage-manifest-adopted` through `submitPageMutation`; it never deletes. Finalize soft-deletes tagged originals only when `cardDigest` of the shelf card equals the mapped card. Every plan_hash covers end state (mapped cards, refusals, blocks, conflicts), never progress, so the printed rerun of a partial apply still applies. JSONL import registers `origin: import` and never overwrites. The doctor check `storage_manifest` is read-only: schema-failing cards, unadopted interim records outside the shelf, a hosted shelf directory gone; `not_applicable` with neither shelf nor interim pages. Pinned by `test/storage-manifest-adopt.test.ts`, `test/storage-manifest-jsonl.test.ts`, `test/doctor-storage-manifest.test.ts` and `test/storage-manifest-adopt-hosted.test.ts`.
+- `src/core/storage-manifest/adopt.ts`, `src/core/storage-manifest/jsonl.ts` and `src/commands/doctor/checks/storage-manifest.ts` — GST-1943 storage shelf recovery. Adopt reads interim `stored-object` pages under a prefix (never `<prefix>index`) from the bounded body prefix (`boundedBodyPrefixSql`), takes the JSON block under `## Record`, strips every field the card refuses (`command_field`, `unknown_field`, `stamped_field`; `CARD_KEYS` in `schema.ts`) and validates the rest with `parseCardInput`; a credential-shaped value (`credentialShape`) blocks the page whatever is dropped. Apply registers through `registerCard` (`origin: adopt`) and tags the original `storage-manifest-adopted` through `submitPageMutation`; it never deletes. On a hosted shelf it then indexes its own commits (`indexShelfCommits`: the managed `--no-pull` drain under the shelf's drain lease, as a git conversion's strict pass does) and reports `index`. Finalize soft-deletes tagged originals only when `cardDigest` of the shelf card equals the mapped card. Every plan_hash covers end state (mapped cards, refusals, blocks, conflicts), never progress, so the printed rerun of a partial apply still applies. JSONL import registers `origin: import` and never overwrites. The doctor check `storage_manifest` is read-only: schema-failing cards, unadopted interim records outside the shelf, a hosted shelf directory gone; `not_applicable` with neither shelf nor interim pages. Pinned by `test/storage-manifest-adopt.test.ts`, `test/storage-manifest-jsonl.test.ts`, `test/doctor-storage-manifest.test.ts` and `test/storage-manifest-adopt-hosted.test.ts`.
diff --git a/docs/architecture/key-files/commands-5.md b/docs/architecture/key-files/commands-5.md
index 521dd6fe2d..e005f8aa94 100644
--- a/docs/architecture/key-files/commands-5.md
+++ b/docs/architecture/key-files/commands-5.md
@@ -3,9 +3,9 @@
[Subsystem index](../KEY_FILES.md). Read only the entries relevant to your change.
Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.
-- `src/commands/repair.ts` — `gbrain repair [<kind>] [--apply] [--source <id>] [--limit <n>] [--no-embed] [--json]` and `gbrain repair --all`. Kinds `timeline` (#5567 materialize), `visibility` (#5525 tighten-only backfill) `safe-chunks` (#5050/#5247 projection-only re-seal of pages of every kind below the safe-chunk fence; `--no-embed` defers embedding to `embed --stale`), `contextual-mode` (#5621 projection-only stamp of the import-time contextual retrieval mode on pages that have none; honors `--no-embed`) `connector-checkpoints` (#5686 brain-wide cleanup of connector checkpoint rows no source can load), `take-supersession` (#5886 relinks takes supersession chains from journal, stored-pointer or forced fence-structure evidence; ambiguous pages are reported with the manual edit, never rewritten; `src/core/repair/take-supersession.ts`), `orphan-bindings` (#5732 brain-wide cleanup of persistence source bindings whose source or incarnation is gone) and `embedding-effects` (#5629/#5734 settlement of stale queued and failed embedding effects: reconciled, superseded, retry_queued or blocked, reported per item in `outcomes` / `outcome_items`) and `google-file-modes` (clears group/other bits on gbrain's own files under Google source dirs outside `~/.gbrain`; filesystem only); no kind previews every kind. Dry run unless `--apply` (no prompt; `--yes` refused). `gbrain repair fences [--only <path>]... [--skip <path>]... [--slug <slug>]... [--diff] [--no-llm] [--max-usd <n>] [--apply [--expect <hash>]]` repairs malformed facts and takes fences (#6188, `src/core/repair/fences.ts`). `parseRepairArgs` is strict: any unknown option or a second positional refuses `invalid_params` before anything runs; flags a kind does not take name the kinds that do (`--only`/`--skip`/`--diff`: frontmatter, fences; `--slug`: fences; `--yes`: frontmatter); `--expect` is accepted for explicit-only and preview-bound kinds, `--include-ambiguous` for explicit-only kinds; `--max-usd <n>` and `--no-llm` only for `spends: 'llm'` kinds (a non-negative USD amount that only lowers the kind's cap), and on any other kind `--max-usd` names the capped route `gbrain doctor --remediate --yes --include-repairs --max-usd <n> --expect <plan_hash>` (hash from `doctor --remediation-plan --json`), as `--max-cost` always does. Help lines come from `REPAIR_REGISTRY`; `--json` adds `paid` per kind and `paid_kinds`. An apply with a report hook prints `repaired N; still waiting: <reason>=<count>` (never a repair count it did not make) and a partial scan; a stop prints its `fix` command and the consent it asks for. Output carries the resolved scope, affected count, a capped `source:slug` sample, residual counts, request-ID / receipt-byte / re-embedding cost (plus, for a `spends: 'llm'` kind, the paid-model estimate or spend and what is left under today's cap) and capacity, and the apply command; `--json` has the same fields. The dry run lists the kinds that may queue paid embeddings and, when a result carries `cost.llm_usd`, `Kinds that may call a paid model` with the summed estimate and the cap left. Host-only: thin clients refuse via `THIN_CLIENT_REFUSED_COMMANDS`. Logic lives in `src/core/repair/`. Segmented pages (Wave B) are not repaired by the whole-body kinds: `timeline`, `timeline-comments`, `connector-fences` (timeline region searched with `segmentedRegionContains`), `split-facts` (manifest facts regions) and `conversation-labels` report them as `segmented_*` residuals with their slugs (`test/large-pages/segmented-repair-scans.test.ts`). An item whose apply fails item-scoped (any failure `classifyItemFailure` does not call run-scoped, a superset of `REPAIR_ITEM_FAILURE_CODES` in `src/core/repair/core.ts`) is a per-item verdict: `runRepair` records it in `result.failed[]` (`item`, `source_id`, `slug`, `reason` the classified code, redacted `message`, `retry: 'next_full_scan'`, `fix` the kind's read-only preview for the source) plus a `failed` outcome, writes no cursor for it and continues; a later success moves the cursor past it, so a resumed run skips it and the next full scan retries it (the `revision_conflict` rule). The command prints `failed N`, each `FAILED <item> (<reason>)` line and the full-scan command, and `repairExitVerdict` exits 1 on any failure or stop. `runRepairKinds` is the kind loop of the no-kind preview and `--all`: a kind whose plan or apply throws item-scoped is listed as a result stopped with reason `error`, its redacted message and the kind's preview as `fix` (`kindErrorResult`, `src/core/remediation/repairs.ts`), and the later kinds still run; a run-scoped error, or most kinds failing (`item_failures_systemic`, ItemRun site `repair.all_kinds`), stops the command; a named kind's error is the command's error. Consumers never read failures as an all-clear: `runRepairSteps` (`RepairStepResult.failed`, status `failed`), the content lane (`ContentLaneResult.failed[]`, exit 1), and the `fence_repair` / `content_repair` phases (`warn`). Test: `test/repair-apply-continue-6459.test.ts`. A `label_edit_refused` item (GST-2603, a label repair whose file cannot take the line edit) counts as declined (`REPAIR_DECLINE_CODES`), exits 0 and never counts toward `item_failures_systemic`. `gbrain repair stuck-recovery` takes `--request-id <uuid>` and, with `--apply --expect <hash> --yes`, `--keep prior|disk` (both refused for other kinds, the value checked once the kind is known); the consent argv carries them. `gbrain repair ghost-pages --source <id>` (#6696 B5) accepts `--yes` with `--apply --expect <hash>` (destructive consent; `src/core/repair/ghost-pages.ts`). `gbrain repair file-drift` also takes `--only`/`--skip` (canonical file path globs, passed to the kind like the other path kinds'), and `--keep` on it refuses `invalid_params` with the same command rewritten to `--prefer database` as a read-only preview fix (`fileDriftKeepRefusal`).
+- `src/commands/repair.ts` — `gbrain repair [<kind>] [--apply] [--source <id>] [--limit <n>] [--no-embed] [--json]` and `gbrain repair --all`. Kinds `timeline` (#5567 materialize), `visibility` (#5525 tighten-only backfill) `safe-chunks` (#5050/#5247 projection-only re-seal of pages of every kind below the safe-chunk fence; `--no-embed` defers embedding to `embed --stale`), `contextual-mode` (#5621 projection-only stamp of the import-time contextual retrieval mode on pages that have none; honors `--no-embed`) `connector-checkpoints` (#5686 brain-wide cleanup of connector checkpoint rows no source can load), `take-supersession` (#5886 relinks takes supersession chains from journal, stored-pointer or forced fence-structure evidence; ambiguous pages are reported with the manual edit, never rewritten; `src/core/repair/take-supersession.ts`), `orphan-bindings` (#5732 brain-wide cleanup of persistence source bindings whose source or incarnation is gone) and `embedding-effects` (#5629/#5734 settlement of stale queued and failed embedding effects: reconciled, superseded, retry_queued or blocked, reported per item in `outcomes` / `outcome_items`) and `google-file-modes` (clears group/other bits on gbrain's own files under Google source dirs outside `~/.gbrain`; filesystem only); no kind previews every kind. Dry run unless `--apply` (no prompt; `--yes` refused). `gbrain repair fences [--only <path>]... [--skip <path>]... [--slug <slug>]... [--diff] [--no-llm] [--max-usd <n>] [--apply [--expect <hash>]]` repairs malformed facts and takes fences (#6188, `src/core/repair/fences.ts`). `parseRepairArgs` is strict: any unknown option or a second positional refuses `invalid_params` before anything runs; flags a kind does not take name the kinds that do (`--only`/`--skip`/`--diff`: frontmatter, fences; `--slug`: fences; `--yes`: frontmatter); `--expect` is accepted for explicit-only and preview-bound kinds, `--include-ambiguous` for explicit-only kinds; `--max-usd <n>` and `--no-llm`... (line truncated to 2000 chars)
- `src/commands/repair-content.ts` — `gbrain repair content [--source <id>] [--only <path>]... [--skip <path>]... [--no-llm] [--max-usd <n>] [--diff] [--apply [--expect <h1>[,<h2>]]] [--json]` (#6377): the content-repair lane as one command. `content` is parsed by `repair.ts`'s strict flag grammar like a kind (`CONTENT_LANE`; `--only`/`--skip`/`--diff`, `--no-llm`, `--max-usd` and `--expect` are accepted for it, `--slug`, `--yes`, `--include-ambiguous` and `--all` refuse) and dispatched before the kind check; it is a lane, not a `RepairKind`: no registry entry, no cursor of its own, listed under "Lanes:" in `REPAIR_HELP`. `runRepairContentCommand` resolves the scope, runs `runContentLane` and prints each kind's result through `renderRepairResult` plus a lane line (spend, allowance left, each kind's hash, every stop, the apply command); `--json` prints `{ lane, scope, mode, kinds, results[] (with `paid`), preview_hashes, cost, stopped, paid_kinds, apply_command }`. A kind's stop sets exit verdict 1; a wrong `--expect` count is `invalid_params` with the preview as its fix. Test: `test/repair-content.test.ts`.
-- `src/commands/reindex.ts` — `gbrain reindex --markdown [--type PAGE_TYPE] [--limit N] [--workers N] [--dry-run] [--json] [--no-embed] [--yes] [--max-usd USD] [--repo PATH]`. W4.5: re-embedding is paid, so `runReindex(engine, args, { authorized?, interactive? })` calls `requireReindexConsent` (`src/core/reindex-consent.ts`) after the dry-run return and before the managed dispatch for every caller unless `--no-embed` or `authorized` (the upgrade path's TTY yes, the job handler's stored spend record); `src/cli/commands/reindex.ts` renders the exit-3 consent refusal and `cost_cap_exceeded`. The approved finite cap runs the inline pass (and the managed dispatch) under a `BudgetTracker` via `withBudgetTracker`; once it is exhausted (an import swallows the refused embedding) the loop stops at the next page and `reportBudgetStop` exits 1 with `budget_exhausted` in `--json`. `countPending` is exported for `jobs submit reindex` and the mode-switch prompt. The writer pool is sized once from the run's page target (pending, capped by `--limit`) through `resolveWorkersWithClamp`, so Postgres runs over 100 pages default to `DEFAULT_PARALLEL_WORKERS` while PGLite stays at one; `--workers` overrides and the used count is reported as `workers` in the result and JSON (pinned by `test/e2e/reindex-auto-workers-5181.test.ts`). Walks markdown pages with stale `chunker_version` (plus unstamped contextual-retrieval mode when embedding is enabled; `--no-embed` still stamps the mode of every page it re-chunks) in 100-row id-keyset batches; a failed row cannot starve later batches in the same invocation. `--type` adds a bound-parameter `pages.type = $N` scope for focused backfills such as atom pages and is rejected by reindex modes that do not consume it. Current-version chunkless healing deliberately remains owned by the native, bounded `embed --stale` path. Rows with non-null `source_path` re-import via `importFromFile`; rows without fall back to `importFromContent`. Both paths pass `forceRechunk: true` to bypass `importFromContent`'s `content_hash` short-circuit — without it the chunker version bump never reaches pages whose source content hasn't changed, AND the stripFactsFence privacy strip never applies to chunks stored without it. Wired into `src/commands/upgrade.ts:runPostUpgrade` after `apply-migrations`. The DB-only fallback (no source file on disk) does NOT pass body-only `compiled_truth` to `importFromContent` (that path re-parses with EMPTY frontmatter and OVERWRITES the page's real frontmatter/title/timeline); it `getPage`+`getTags`, reconstructs FULL markdown via `serializeMarkdown(frontmatter, compiled_truth, timeline, {type, title, tags})`, and re-imports THAT so re-chunking a DB-only page preserves everything while bumping `chunker_version`. Pinned by `test/reindex-preserve-tags.test.ts` and `test/reindex.test.ts`. #5377: on a managed brain (`managedPersistenceEnabled`) the `--markdown` sweep delegates to the projection repairs through `runRepair` (`safe-chunks`, then `contextual-mode` unless `--no-embed`), so it never takes the legacy writer and changes no page revision, journal request or canonical file; `--type` is refused there with the repair commands, and pages the repairs cannot rebuild are reported as `unsupported_pages`; a page the repairs held (`projection_unbuildable`) or failed per item is counted in `failed` (`--json` adds `failures`, exit 1) instead of failing the command. The doctor, upgrade and post-upgrade hints that name `gbrain reindex --markdown` therefore work on both brain modes (C-NEW-5).
+- `src/commands/reindex.ts` — `gbrain reindex --markdown [--type PAGE_TYPE] [--limit N] [--workers N] [--dry-run] [--json] [--no-embed] [--yes] [--max-usd USD] [--repo PATH]`. W4.5: re-embedding is paid, so `runReindex(engine, args, { authorized?, interactive? })` calls `requireReindexConsent` (`src/core/reindex-consent.ts`) after the dry-run return and before the managed dispatch for every caller unless `--no-embed` or `authorized` (the upgrade path's TTY yes, the job handler's stored spend record); `src/cli/commands/reindex.ts` renders the exit-3 consent refusal and `cost_cap_exceeded`. The approved finite cap runs the inline pass (and the managed dispatch) under a `BudgetTracker` via `withBudgetTracker`; once it is exhausted (an import swallows the refused embedding) the loop stops at the next page and `reportBudgetStop` exits 1 with `budget_exhausted` in `--json`. `countPending` is exported for `jobs submit reindex` and the mode-switch prompt. The writer pool is sized once from the run's page target (pending, capped by `--limit`) through `resolveWorkersWithClamp`, so Postgres runs over 100 pages default to `DEFAULT_PARALLEL_WORKERS` while PGLite stays at one; `--workers` overrides and the used count is reported as `workers` in the result and JSON (pinned by `test/e2e/reindex-auto-workers-5181.test.ts`). Walks markdown pages with stale `chunker_version` (plus unstamped contextual-retrieval mode when embedding is enabled; `--no-embed` still stamps the mode of every page it re-chunks) in 100-row id-keyset batches; a failed row cannot starve later batches in the same invocation. `--type` adds a bound-parameter `pages.type = $N` scope for focused backfills such as atom pages and is rejected by reindex modes that do not consume it. Current-version chunkless healing deliberately remains owned by the native, bounded `embed --stale` path. Rows with non-null `source_path` re-import via `importFromFile`; rows without fall back to `importFromContent`. Both paths pass `force... (line truncated to 2000 chars)
- `src/commands/repair-jsonb.ts` — `gbrain repair-jsonb [--dry-run] [--json]`: rewrites `jsonb_typeof='string'` rows in place across 8 affected columns (pages.frontmatter, raw_data.data, ingest_log.pages_updated, files.metadata, page_versions.frontmatter, subagent_messages.content_blocks, subagent_tool_executions.input, subagent_tool_executions.output). The subagent targets are `jsonPayloadOnly`: those columns can legitimately hold jsonb string scalars (persistToolExec binds a tool's pre-serialized string payload as-is), so their damage predicate additionally requires container-shaped content (`^\s*[\[{]`) that `gbrain_try_jsonb(...)` (jsonb or NULL; portable to Postgres 15, unlike the `pg_input_is_valid` it replaced, #7112) actually parses — a plain-text value that merely starts with `[` or `{` is never flagged or corrupted. Targets whose table doesn't exist on the brain are skipped via `to_regclass` (brains without the subagent tables), and one target's failure is recorded on stderr while the run continues — earlier repairs are already committed and the v0_12_2 migration orchestrator JSON-parses stdout. `runDoctor`'s `jsonb_integrity` check counts damage with the same predicate over the same target list. Repairs double-encoded rows on Postgres; PGLite no-ops. Idempotent. Pinned by `test/repair-jsonb.test.ts` + `test/doctor.test.ts`.
@@ -17,24 +17,24 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/commands/search-diagnose.ts` — `gbrain search diagnose "<query>" --target <slug> [--json] [--source <id>]`: Phase-0 retrieval diagnostic. Traces WHERE a target page surfaces (or fails to) across keyword / vector (per-page max-pool) / alias / hybrid layers and names the layer responsible for an incident, so an operator can pin whether the fix is max-pool/innerLimit (vector) vs title/alias. The verdict names the layer that DOES surface the target (or "none"). Pinned by `test/search/search-diagnose.test.ts`.
-- `src/commands/search.ts:gbrain search stats` — `rerank_gate` section (eligible, graded, would_skip and `would_skip_rate` over graded, provider_calls, `by_reason`, `ineligible` by why), read from the reserved `(date, 'rerank_gate', <counter>)` rows of `search_telemetry` (no DDL; diverted out of `total_calls` like the empty-result rows; written only when `search.reranker.gate` is not `off`; cache hits add nothing); human output prints it when anything was graded. `graph_signals` section (enabled/source/failures_count/failures_by_reason). JSON envelope adds a `graph_signals` sibling property; `_meta.metric_glossary` adds `graph_signals.enabled` + `graph_signals.failures_by_reason`. Human output prints the section after the existing block. Reads `search.graph_signals` config first, falls back to the mode default. Pinned by `test/search/search-stats-graph-signals.test.ts`. Both `gbrain search stats` and `gbrain search tune` also surface a `coverage` disclosure (JSON: `{cli_invocations: 'recorded_on_clean_exit', reason}`; human: a one-line caveat) sourced from `telemetryCoverage()`/`TELEMETRY_COVERAGE_CAVEAT` in `src/core/search/telemetry.ts`: a short-lived CLI call's buffer flushes during the bounded CLI teardown drain, so a CLEAN exit is recorded; hard kills, drains that exceed their bound, and anything buffered when an engine disconnects outside the CLI teardown path still drop — the disclosure is display-only and reads its truth from the telemetry module's single-source constants. Pinned by the coverage-disclosure tests in `test/commands-search.test.ts`. `gbrain search tune --apply` writes in order and stops at the first write that did not land; a thrown write is reconciled by re-reading its key (`applied` when the target value is there, `failed` when not, `outcome_unknown` when the read fails too). JSON lists only landed changes in `applied` and `revert_commands`, adds per-item `results`, `not_applied` and `apply_error`, and the command rethrows the write error (non-zero exit). Tests: `test/search-tune-apply-truthful.serial.test.ts`.
+- `src/commands/search.ts:gbrain search stats` — `rerank_gate` section (eligible, graded, would_skip and `would_skip_rate` over graded, provider_calls, `by_reason`, `ineligible` by why), read from the reserved `(date, 'rerank_gate', <counter>)` rows of `search_telemetry` (no DDL; diverted out of `total_calls` like the empty-result rows; written only when `search.reranker.gate` is not `off`; cache hits add nothing); human output prints it when anything was graded. `graph_signals` section (enabled/source/failures_count/failures_by_reason). JSON envelope adds a `graph_signals` sibling property; `_meta.metric_glossary` adds `graph_signals.enabled` + `graph_signals.failures_by_reason`. Human output prints the section after the existing block. Reads `search.graph_signals` config first, falls back to the mode default. Pinned by `test/search/search-stats-graph-signals.test.ts`. Both `gbrain search stats` and `gbrain search tune` also surface a `coverage` disclosure (JSON: `{cli_invocations: 'recorded_on_clean_exit', reason}`; human: a one-line caveat) sourced from `telemetryCoverage()`/`TELEMETRY_COVERAGE_CAVEAT` in `src/core/search/telemetry.ts`: a short-lived CLI call's buffer flushes during the bounded CLI teardown drain, so a CLEAN exit is recorded; hard kills, drains that exceed their bound, and anything buffered when an engine disconnects outside the CLI teardown path still drop — the disclosure is display-only and reads its truth from the telemetry module's single-source constants. Pinned by the coverage-disclosure tests in `test/commands-search.test.ts`. `gbrain search tune --apply` writes in order and stops at the first write that did not land; a thrown write is reconciled by re-reading its key (`applied` when the target value is there, `failed` when not, `outcome_unknown` when the read fails too). JSON lists only landed changes in `applied` and `revert_commands`, adds per-item `results`, `not_applied` and `apply_error`, and the command rethrows the write error (no... (line truncated to 2000 chars)
- `src/commands/serve-http-grants.ts` + `admin/src/components/ClientGrant.tsx` — typed admin grant request validation and shared profile/advanced permission editor. Register/rescope/TTL routes in `serve-http-registration.ts`, `serve-http-grants.ts`, and `serve-http-admin-api.ts` use canonical grant validation and audit; legacy response shapes remain available. Registration and permission-edit failures add safe classifications, stage, outcome and inspection remedies; an unacknowledged mutation stays outcome-unknown, while read/preview failures and known refusals remain failed. New UI creation defaults to memory-writer and requires a preview, while edits carry the displayed revision and require a fresh preview after any field change or conflict. Detail/catalog endpoints expose non-secret grants and the shared harness registry. Operation authority snapshots, source sets, delegated tools/namespaces, spend, concurrency, and future TTL are independently reviewable; profile regrant is explicit. `admin/src/pages/Agents.tsx` previews machine/public PKCE/confidential PKCE registration and current permissions, and exposes versioned lifecycle actions. Explicit downloads select machine `HarnessCredentials` or native `OAuthClientSetup`; mixed clients require a flow choice. Loading errors preserve stale rows with Retry and disable creation when required source metadata is missing. Browser downloads and native connection evidence remain distinct. Rebuild committed `admin/dist` and `src/admin-embedded.ts` after SPA edits.
-- `src/commands/serve-http.ts` — Express 5 HTTP MCP server with OAuth 2.1, admin dashboard, and SSE live activity feed. The legacy `POST /ingest` queue refuses operation-snapshot clients; they use approved MCP writes so execution stays inside the shared grant contract. Started via `gbrain serve --http [--port N] [--token-ttl N] [--enable-dcr] [--public-url URL] [--bind HOST] [--log-full-params]`. OAuth discovery's `scopes_supported` (RFC 8414 AS metadata and both RFC 9728 protected-resource documents, one value through the SDK router) comes from `scopesSupportedForDiscovery({ enableDcr })` in `src/core/scope.ts`: with `--enable-dcr` it is exactly the self-registration ceiling (`read write`), so a client that copies discovery into its `/register` request succeeds; without DCR it is every scope except operator-only `agent`. The DCR ceiling still rejects an explicit privileged request, and operator-registered clients are never narrowed by the advertisement. Combines MCP SDK's `mcpAuthRouter` (authorize/token/register/revoke), a custom `client_credentials` handler running BEFORE the router (SDK's token endpoint throws `UnsupportedGrantTypeError` for CC; custom handler falls through for `auth_code` / `refresh_token`), `requireBearerAuth` middleware for `/mcp` with scope enforcement + `localOnly` rejection before op dispatch, and per-IP `express-rate-limit` buckets: the MCP SDK's defaults on `/authorize` (100 / 15 min), `/register` (20 / hour) and `/token` (50 / 15 min) because `authRouterOptions` passes no `rateLimit: false`, the custom `client_credentials` handler's `ccRateLimiter`, and independent owner limits: 60 total authentication requests/min/IP, 10 failed authentications/min/IP (verified authority, independent of response status), and 60 consent requests/min/authenticated session in `serve-http-admin-limits.ts`. Admin no-store, no-referrer and framing headers precede login/link handlers. Explicit pending IDs survive fresh-browser links; invalid or restarted requests require native authorization to restart. Serves the built admin SPA from `admin/dist/` with SPA fallback. `/admin/events` SSE broadcasts every MCP request. `cookie-parser` wired (Express 5 has no built-in). Startup logging prints port, engine, issuer URL (honors `--public-url`), client count, DCR status, and the admin bootstrap token line — but the generated token's raw value only prints when stderr is an interactive TTY (`shouldSuppressBootstrapPrint`): a non-TTY (containerized/piped) start hides it so the secret never lands in centralized log storage, env-sourced tokens (`$GBRAIN_ADMIN_BOOTSTRAP_TOKEN`) are always hidden, `--print-admin-token` forces the raw value on a trusted terminal, and `--suppress-bootstrap-token` hides everything. The `/mcp` request handler's OperationContext literal sets `remote: true` explicitly (without it `submit_job`'s protected-name guard would see a falsy undefined and a `read+write`-scoped OAuth token could submit `shell` jobs). `summarizeMcpParams` from `src/mcp/dispatch.ts` feeds both `mcp_request_log` writes and the SSE feed by default (raw via `--log-full-params`). Cookie `Secure` flag set behind HTTPS or a public-URL proxy; magic-link nonce store LRU-bounded; DCR disable routes through the `GBrainOAuthProvider` `dcrDisabled` constructor option (not a router monkey-patch); `transport.handleRequest` wrapped in try/catch to return a JSON-RPC 500 envelope; OperationError + unexpected exceptions unified through `buildError` / `serializeError` so `/mcp` always returns the same envelope. `/health` is liveness-only via `probeLiveness(engine, engineName, version, timeoutMs)` racing `engine.executeRaw('SELECT 1', undefined, { signal })` against the exported `HEALTH_TIMEOUT_MS = 3000`; when the timeout wins, an `AbortController` cancels the Postgres query (PGLite can only discard its eventual result) before the same tagged `ProbeHealthResult` 503 envelope is returned (single timer-cleanup site); body shape `{status, version, engine}` only. Full stats live at admin-only `/admin/api/full-stats` (gated by `requireAdmin`, calls `probeHealth(engine, ...)`) — keeps `getStats()`'s 6× count(*) off the public route so a saturated pool doesn't trigger orchestrator restart cascades. OAuth/admin/audit SQL outside the abortable liveness probe routes through `sqlQueryForEngine(engine)` from `src/core/sql-query.ts` so it works against PGLite; the four `mcp_request_log.params` INSERT sites (success / auth_failed / scope_denied / server-error) go through `executeRawJsonb(engine, ...)` so the column stores real objects (`params->>'op'` returns `search`, not the quoted string). `--bind HOST` defaults `127.0.0.1` (self-hosters pass `--bind 0.0.0.0`); a stderr WARN fires when `--public-url` is set without `--bind`; the banner prints a `Bind:` line. `AuthInfo.sourceId` + `AuthInfo.allowedSources` + `AuthInfo.takesHoldersAllowList` are the typed source of truth, populated by `oauth-provider.ts:verifyAccessToken` (source scope from the `oauth_clients` row; takes-holders from `access_tokens.permissions.takes_holders` for legacy bearer tokens). The `/mcp` dispatch site reads `authInfo.takesHoldersAllowList ?? ['world']` — absent grants (OAuth-client tokens, pre-v29 brains) fail closed to world-only takes visibility, while an explicit `[]` grant is preserved as deny-all; pinned end-to-end by `test/e2e/serve-http-takes-holders.test.ts`. The HTTP MCP `tools/list` handler at `:837-849` uses `paramDefToSchema(v)` from `src/mcp/tool-defs.ts` so array params keep `items` (strict-mode OAuth clients otherwise reject the whole tool list). `POST /ingest` enforces the slug-prefix write fence at the ROUTE, not the op layer: the route hands its payload to the `ingest_capture` minion handler, which deliberately bypasses `put_page`, so no `OperationContext` exists and `enforceClientSlugFence` never runs — a slug-bound client must therefore supply `X-Gbrain-Slug` and it must satisfy `slugUnderBoundPrefixes`, else 403 (without the check a bound client could overwrite any page inside its granted source). The write source is resolved server-side as `authInfo.sourceId ?? 'default'` and travels on the job as `job.data.sourceId`; the caller-supplied `X-Gbrain-Source-Id` header routes nothing and only names the emitter (`webhook-<clientId>`), which is what the event's `source_id` and the 202's back-compat `source_id` field carry. The 202 additionally reports the routed destination as `write_source_id`, and the write source and normalized target slug (hashed) join the queue idempotency key, so a rescoped client or a second slug gets its own capture, and a slug over 1024 bytes gets 400 `invalid_slug` (`test/serve-http-ingest-write-loss.test.ts`). confidential revoke: a pre-router `/revoke` handler validates the RFC 7009 body, verifies hash-only secrets for both `client_secret_post` and `client_secret_basic`, rejects mixed authentication, preserves the SDK path for public clients, and separates opaque client-auth failures from retryable/backend failures. OAuth metadata advertises both confidential methods. Pinned by `test/e2e/serve-http-oauth.test.ts`. three admin routes: `/admin/api/calibration/profile`, `/admin/api/calibration/charts/:type` (image/svg+xml; type in {brier-trend, domain-bars, pattern-statements, abandoned-threads}), `/admin/api/calibration/pattern/:id` (drill-down). The manual mint route `/admin/api/register-client` in `serve-http-registration.ts` accepts optional `source` + `federatedRead` bindings mirroring the CLI's `--source`/`--federated-read` (validated via `normalizeSourceInput`/`normalizeFederatedReadInput` from `src/core/source-id.ts`; omitting both preserves the default binding `source_id='default'` / `federated_read=[source_id]`, invalid values return a structured 400 `invalid_source`), so an admin SPA or provisioning proxy can mint a source-confined client over HTTP. The route mirrors the CLI lane end to end: structured 400s for `unknown_source` / `archived_source` (one batched `ANY($1::text[])` existence check), `invalid_token_ttl` (shared `TOKEN_TTL_MIN/MAX_SECONDS` bounds, integer-validated BEFORE the tx), and `brain_too_old` (column pre-flight OUTSIDE the tx — a pre-scoped-clients brain refuses up front instead of aborting mid-transaction); the duplicate-name pre-check + INSERT run in ONE transaction under the SAME name-scoped advisory lock the CLI takes (`registerClientNameLockKey`), returning 409 `duplicate_name` with the existing `client_id`; the INSERT composes `registerScopedClient` (the CLI's registration core) so the two paths cannot drift; any post-commit failure includes the created `client_id` so the operator can revoke (never a false "nothing was created"). Pinned by `test/register-client-source-normalize.test.ts`. The `/mcp` tools/list is the honest catalog: per-request filters (token scope incl. the `agentCallable` carve-out, bound-client fence via `opAllowedForBoundClient`, publish gates via `disabledOpsForPublishGates`) over the surface-filtered op set, schemas via `buildToolDefs` (strict emission when `mcp.strict_params` resolves reject); the tools/list `mcp_request_log` row records the listed size as `params.tool_count`. Call-time op-level denials the list should have prevented — the inline scope deny, publish-gate backstop (`config_key=...`), fence op-level deny (`fence=op`, classified via `isListLevelDenialEnvelope`) — log `status='denied_after_list'` instead of `'error'` (the trend-to-zero honest-catalog metric, see docs/operations/mcp-surface-runbook.md) — every tools/call row's status resolves through `requestLogStatusForResult` (dispatch.ts) on BOTH transports. The admin health-indicators error rate counts `status NOT IN ('success','success_with_warnings')` and excludes `operation='surface_change'` audit rows from numerator AND denominator (audit rows record operator/self actions, not traffic). Per-request surface resolution lives in `resolveEffectiveSurface`: a `verbs` ceiling skips the default-surface config read, and a failed read applies the last successfully read default per process (fail-closed — a transient config outage cannot widen a NULL-surface client). OAuth protected-resource metadata (RFC 9728) names `/mcp` as the resource (`resourceServerUrl`), so the SDK mounts the PRM at `/.well-known/oauth-protected-resource/mcp` and the 401 `resource_metadata` URL is derived from the same value; the bare root path is kept as an alias by rewriting `req.url` onto the SDK's handler (same document, same CORS). Shutdown: `waitForHttpServerLifecycle` tracks accepted sockets weakly (`trackServerSockets`; Bun never emits socket `close`, so a strong set leaked one per request), severs the still-reachable ones right after `server.close()`, and bounds the close wait at `CLOSE_TIMEOUT_MS` (5s) — a collected keep-alive wrapper whose native handle keeps `close()` from returning gets one stderr line and shutdown proceeds instead of hanging. DCR startup copy: the SECURITY WARNING states self-registered clients are limited to read/write (read-only for `client_credentials` under `--enable-dcr-insecure`) and that every authorization_code connection needs owner approval in the admin UI; banner `DCR:` values are `enabled (consent; DCR max read write)` / `enabled (INSECURE: read-only M2M)` / `disabled`.
- Layout: `runServeHttp` binds through `listenOrRefuse` (`serve-http-listen.ts`: `serve_port_in_use` on a taken port; with `options.adoptServer` from status-only recovery it hands the app to the already-bound listener instead of binding). `buildServeHttpApp` builds one shared `ServeHttpContext` (sessions, nonce stores, limiters, `requireAdmin`, SSE fan-out, OAuth provider, resource verifier, non-`localOnly` op list) and mounts in registration order `serve-http-oauth.ts` (CORS gates, DCR TTL hook, confidential credentials, SDK router, discovery, owner login links, consent), `serve-http-metrics.ts` (`/health`, `/metrics`, probes), `serve-http-admin-api.ts` (`requireAdmin`, `/admin/login`, `/admin/api/*`, `/admin/events`), `serve-http-spa.ts`, `serve-http-mcp.ts` (`/mcp`; writes `[gbrain-serve] dispatch op=<name> args_sha256=<16 hex>` to stderr before each tool call so a stall's last line names its request, never the arguments) and `serve-http-webhooks.ts` (`/ingest`, which maps a legacy-authority `permission_denied` from submission to 409 `{error, message, hint, docs_url}` (`test/serve-http-ingest-legacy.test.ts`), answers 429 `ingest_backlog_full` when the 50-capture waiting cap hands back another job, and every other submission error to 500; `legacyIngestJob` answers a retried POST /ingest recorded under the pre-v0.60.609.0 key (no slug) when that row's slug matches (`test/serve-http-ingest-legacy-key-retry.test.ts`, `test/e2e/serve-http-ingest-legacy-key-retry-postgres.test.ts`); the queue key dedupes only while the job row exists, and the `ingest_capture` handler (`minions/handlers/ingest-capture.ts`) applies a capture once per job idempotency key for 90 days through `ingest_applied_captures` (`ingestion/applied-captures.ts`, migration v296), even after `gbrain jobs prune`: the row is inserted in the page write's transaction (`importFromContent`'s `beforeCommit`; a run that loses the insert rolls its write back and returns the stored result) or after a committed managed door write, whose per-attempt `request_id` (`ingest-capture:<key sha256 prefix>:<attempt>`) lets a committed request in `persistence_requests` count as applied and backfill the row; tombstones and keyless jobs are unchanged, and the purge phase drops rows past 90 days (`test/ingest-capture-applied-once.test.ts`, `test/e2e/ingest-capture-applied-once-postgres.test.ts`); `/webhooks/github`, which HMACs every body, with a throwaway key when there is no source or secret); `runServeHttp` keeps listen, banner, resolve-IPC binding and shutdown, and the façade re-exports moved symbols. Order is pinned by `test/serve-http-route-golden.test.ts` (AST) and `test/serve-http-route-runtime-golden.test.ts` (router stack). Size ceiling: `scripts/module-size-limits.tsv`.
+- `src/commands/serve-http.ts` — Express 5 HTTP MCP server with OAuth 2.1, admin dashboard, and SSE live activity feed. The legacy `POST /ingest` queue refuses operation-snapshot clients; they use approved MCP writes so execution stays inside the shared grant contract. Started via `gbrain serve --http [--port N] [--token-ttl N] [--enable-dcr] [--public-url URL] [--bind HOST] [--log-full-params]`. OAuth discovery's `scopes_supported` (RFC 8414 AS metadata and both RFC 9728 protected-resource documents, one value through the SDK router) comes from `scopesSupportedForDiscovery({ enableDcr })` in `src/core/scope.ts`: with `--enable-dcr` it is exactly the self-registration ceiling (`read write`), so a client that copies discovery into its `/register` request succeeds; without DCR it is every scope except operator-only `agent`. The DCR ceiling still rejects an explicit privileged request, and operator-registered clients are never narrowed by the advertisement. Combines MCP SDK's `mcpAuthRouter` (authorize/token/register/revoke), a custom `client_credentials` handler running BEFORE the router (SDK's token endpoint throws `UnsupportedGrantTypeError` for CC; custom handler falls through for `auth_code` / `refresh_token`), `requireBearerAuth` middleware for `/mcp` with scope enforcement + `localOnly` rejection before op dispatch, and per-IP `express-rate-limit` buckets: the MCP SDK's defaults on `/authorize` (100 / 15 min), `/register` (20 / hour) and `/token` (50 / 15 min) because `authRouterOptions` passes no `rateLimit: false`, the custom `client_credentials` handler's `ccRateLimiter`, and independent owner limits: 60 total authentication requests/min/IP, 10 failed authentications/min/IP (verified authority, independent of response status), and 60 consent requests/min/authenticated session in `serve-http-admin-limits.ts`. Admin no-store, no-referrer and framing headers precede login/link handlers. Explicit pending IDs survive fresh-browser links; invalid or restarted reque... (line truncated to 2000 chars)
+ Layout: `runServeHttp` binds through `listenOrRefuse` (`serve-http-listen.ts`: `serve_port_in_use` on a taken port; with `options.adoptServer` from status-only recovery it hands the app to the already-bound listener instead of binding). `buildServeHttpApp` builds one shared `ServeHttpContext` (sessions, nonce stores, limiters, `requireAdmin`, SSE fan-out, OAuth provider, resource verifier, non-`localOnly` op list) and mounts in registration order `serve-http-oauth.ts` (CORS gates, DCR TTL hook, confidential credentials, SDK router, discovery, owner login links, consent), `serve-http-metrics.ts` (`/health`, `/metrics`, probes), `serve-http-admin-api.ts` (`requireAdmin`, `/admin/login`, `/admin/api/*`, `/admin/events`), `serve-http-spa.ts`, `serve-http-mcp.ts` (`/mcp`; writes `[gbrain-serve] dispatch op=<name> args_sha256=<16 hex>` to stderr before each tool call so a stall's last line names its request, never the arguments) and `serve-http-webhooks.ts` (`/ingest`, which maps a legacy-authority `permission_denied` from submission to 409 `{error, message, hint, docs_url}` (`test/serve-http-ingest-legacy.test.ts`), answers 429 `ingest_backlog_full` when the 50-capture waiting cap hands back another job, and every other submission error to 500; `legacyIngestJob` answers a retried POST /ingest recorded under the pre-v0.60.609.0 key (no slug) when that row's slug matches (`test/serve-http-ingest-legacy-key-retry.test.ts`, `test/e2e/serve-http-ingest-legacy-key-retry-postgres.test.ts`); the queue key dedupes only while the job row exists, and the `ingest_capture` handler (`minions/handlers/ingest-capture.ts`) applies a capture once per job idempotency key for 90 days through `ingest_applied_captures` (`ingestion/applied-captures.ts`, migration v296), even after `gbrain jobs prune`: the row is inserted in the page write's transaction (`importFromContent`'s `beforeCommit`; a run that loses the insert rolls its write back and returns the stored result) or after a committed m... (line truncated to 2000 chars)
-- `src/commands/serve.ts` — `gbrain serve` stdio MCP entrypoint with idempotent shutdown across every parent-disconnect signal. Surface: stdio resolves `GBRAIN_SURFACE` > `--surface` > config > full (`resolveStdioSurface`; an invalid env value is ignored with a stderr line and handed to `startMcpServer` as `invalidSurfaceEnv`), `--http` resolves `--surface` > config > full and says on stderr that it ignores `GBRAIN_SURFACE`; both print `surface=<x> (source: …)` at start. `--http --token-ttl` goes through `parseTokenTtl` (`src/commands/auth.ts`) and refuses anything outside 60 to 7,776,000 seconds before the server starts. Stdio EOF, SIGTERM, SIGINT, SIGHUP, and parent-process death (every reparent case — PID 1, launchd subreaper, systemd, tmux, or a parent shell with `PR_SET_CHILD_SUBREAPER`) all funnel into one `cleanup(reason)` that first awaits `shutdownDelegatedSync()` (idempotent shared promise; a running delegated sync is aborted and settles its checkpoint against the live engine, with the cleanup deadline extended by `GBRAIN_SERVE_SYNC_SETTLE_MS` only while a job runs) and then releases the engine and the PGLite write-lock dir within 5 seconds (otherwise the lock is held indefinitely after Claude Desktop / Cursor / launchd-managed gateways disconnect, forcing a 5-minute stale-lock wait on next start). Watchdog reparent check is `getParentPid() !== initialParentPid` (the `=== 1` check missed the subreaper case under launchd/systemd). Bun's `process.ppid` cache is stale across reparenting ([oven-sh/bun#30305](https://github.com/oven-sh/bun/issues/30305)) so `getParentPid()` runs `spawnSync('ps', ['-o', 'ppid=', '-p', PID])` per tick. Startup probe verifies `ps` is on PATH; if not (stripped containers, busybox), the watchdog skips installing AND emits a loud `[gbrain serve] watchdog disabled: ps unavailable ...` stderr line so operators see the degraded mode. The idle maintenance sweep skips ticks while a delegated sync runs and drains deferred embeds afterwards (`maybeDrainDeferredEmbeds`); it targets the source `resolveMcpStdioSourceScope` resolves (GBRAIN_SOURCE > `.gbrain-source` dotfile > local_path > `sources.default` > …) — the SAME ladder as stdio dispatch and the startup sweep, so dotfile/local_path-scoped serves reconcile their in-session MCP writes (pinned by `test/serve-idle-sweep-source.serial.test.ts`). #7599: `lean` (`readOnlyServeSkipsResidentDuties`, a read-only stdio serve on Postgres; PGLite keeps both) turns off the idle sweep and `installResidentTickers` (facts drain, movement watch, on-commit head watcher, request-log retention ticker). Both lanes start the hourly request-log retention prune (`installMcpLogPrune`, `src/core/mcp-request-log-retention.ts`; PGLite only, vetoed while a delegated sync runs) and stop it at shutdown; seam `ServeOptions.mcpLogPrune`. Both stdin activity listeners (the default-on idle sweep and the opt-in `--stdio-idle-timeout`) attach only AFTER the MCP SDK transport's own stdin listener — the sweep on its first interval tick, the idle timeout through the activator `installStdioLifecycle` returns, which `runServe` invokes once `startMcpServer` resolves (and which re-arms the countdown so boot time does not eat into the idle window) — so neither can flip stdin into flowing mode and consume a fast client's initialize frame before the SDK sees it. The boot-readiness deadline (`GBRAIN_SERVE_BOOT_TIMEOUT_SECONDS`, default 60, 0 disables) measures time WITHOUT boot progress: every `onBootPhase` change and every `noteForwardProgress()` note (`src/core/forward-progress.ts`; progress ticks and each completed stdio request via `trackStdioRpc` in `src/mcp/server.ts`) restarts the window, so a large brain's slow but advancing boot is never killed; only a full window without progress releases the engine and exits 1 with the `serve_boot_timeout` line (stuck phase, pool pressure, seconds since boot started). Pinned by `test/serve-stdio-lifecycle.test.ts` (boot-readiness block). #6543: after the pool stall watch, `recordServeTransport` (`src/commands/serve-health.ts`) reads the read pool's transport once (live `prepare`/`max_pipeline` with `max_pipeline_reason`, the doctor probe's `SHOW statement_timeout` and its ALTER ROLE fix when a configured timeout reads 0, `application_name` when Supavisor), logs one `[gbrain serve] transport` line and caches it for `/health?deep=1` (never re-read per probe). `GBRAIN_SERVE_RESTART_REQUIRED_EXIT_SECONDS=<n>` (>= 120, else `invalid_params` at start) arms `installRestartRequiredExit`: an in-process `restart_required` held continuously for n seconds (the hold resets when it clears) disconnects under a 5 s deadline and exits `SERVE_UNHEALTHY_EXIT_CODE` (69, `serve_unhealthy_exit`); a durable ledger (`serve-self-exit.json` under the gbrain home) suppresses the exit after 3 within an hour (`serve_self_exit_suppressed`, `self_exit_suppressed` in the deep 503). `probeDeepHealth` (`serve-http-metrics.ts`) answers 503 `persistence_restart_required` before its pooled probe, `pool_inflight_over_budget` or `deep_health_probe_failed` (`reason`), each with `fix`/`docs` from the registry and the cached `transport`, no request ids. Pinned by `test/serve-health-6543.test.ts` (a real `PersistenceConsumer` driven to restart_required).
+- `src/commands/serve.ts` — `gbrain serve` stdio MCP entrypoint with idempotent shutdown across every parent-disconnect signal. Surface: stdio resolves `GBRAIN_SURFACE` > `--surface` > config > full (`resolveStdioSurface`; an invalid env value is ignored with a stderr line and handed to `startMcpServer` as `invalidSurfaceEnv`), `--http` resolves `--surface` > config > full and says on stderr that it ignores `GBRAIN_SURFACE`; both print `surface=<x> (source: …)` at start. `--http --token-ttl` goes through `parseTokenTtl` (`src/commands/auth.ts`) and refuses anything outside 60 to 7,776,000 seconds before the server starts. Stdio EOF, SIGTERM, SIGINT, SIGHUP, and parent-process death (every reparent case — PID 1, launchd subreaper, systemd, tmux, or a parent shell with `PR_SET_CHILD_SUBREAPER`) all funnel into one `cleanup(reason)` that first awaits `shutdownDelegatedSync()` (idempotent shared promise; a running delegated sync is aborted and settles its checkpoint against the live engine, with the cleanup deadline extended by `GBRAIN_SERVE_SYNC_SETTLE_MS` only while a job runs) and then releases the engine and the PGLite write-lock dir within 5 seconds (otherwise the lock is held indefinitely after Claude Desktop / Cursor / launchd-managed gateways disconnect, forcing a 5-minute stale-lock wait on next start). Watchdog reparent check is `getParentPid() !== initialParentPid` (the `=== 1` check missed the subreaper case under launchd/systemd). Bun's `process.ppid` cache is stale across reparenting ([oven-sh/bun#30305](https://github.com/oven-sh/bun/issues/30305)) so `getParentPid()` runs `spawnSync('ps', ['-o', 'ppid=', '-p', PID])` per tick. Startup probe verifies `ps` is on PATH; if not (stripped containers, busybox), the watchdog skips installing AND emits a loud `[gbrain serve] watchdog disabled: ps unavailable ...` stderr line so operators see the degraded mode. The idle maintenance sweep skips ticks while a delegated sync runs and drains deferred embeds afterwards... (line truncated to 2000 chars)
- `src/commands/skillify-check.ts` — `gbrain skillpack-check` agent-readable health report. Exit 0/1/2 for CI gating; JSON for debugging. Wraps `check-resolvable --json`, `doctor --json`, and migration ledger into one payload. Required item 12 (`brain_first_compliance`) calls `analyzeSkillBrainFirst()` on the candidate SKILL.md; exits 1 when the verdict is `missing_brain_first` (external-lookup pattern present, no callout, no `brain_first: exempt`). The scaffold path in `src/core/skillify/templates.ts` pre-inserts the canonical Convention callout into new SKILL.md files so freshly-scaffolded skills pass item 12.
-- `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 that config directory, compared after symlink resolution; project-scoped hooks; or a receipt recording no paths for the host) or another gbrain marker on a wanted event; #7771, `test/setup-harness-lane-scope-7771.test.ts`). Consent is three recorded decisions (`resolveConsent`): wiring scope (`--scope`, `--no-hooks`, `GBRAIN_HOOKS=0`), capture (`--capture`/`--no-capture`; a file-config `memory.auto_writeback: off` wins) and providers; read-context events come from the capability row, capture events only when accepted. Verify reuses `smokeStdioRegistration` from `doctor/checks/harness-wiring.ts`; states are `configured` → `connection-verified` → `native-pending` (`native-verified` is never claimed). `gbrain setup codex` (`runCodexSetup`/`runCodexRemove`, writer in `src/core/setup/codex.ts`) shares the target, consent, refusal and verify steps: user scope only (`--scope project` exits 2), the codex plugin (`codexPluginProvidesName`) skips the MCP table, `harness_lane` also covers a bootstrap harness receipt targeting codex (in the same scoped sense) or a bootstrap-lane group on a wanted event, the dry run adds a `trust` step, and the final state is `native-verified` when the codex row's push is verified and the receipt owns the trusted UserPromptSubmit hook. Unsupported harness ids (`openclaw`, `hermes`, unknown) refuse with `setup_harness_unsupported` naming the row's guide (exit 2). `GBRAIN_SETUP_ABORT_AFTER=receipt|mcp|hooks` is the crash-injection seam. `--serves one|several` (GST-363, `src/commands/setup-serves.ts`; tests `test/setup-serves-several.test.ts`, `test/setup-serves-stdio-member.test.ts`, `test/setup-serves-upgrade.test.ts`): `several` runs `gbrain access serves several --yes --json` and one `gbrain find people/ --as <member> --json` per member as children and prints the receipt (paths, never keys); a one-person setup on a several-person brain refuses `setup_serves_several` unless the owner (written as `mcp.stdio_member`) or `mcp.stdio_member` binds the connection; the brain-first access then carries `serves: 'several'`. Pinned by `test/setup.test.ts` and `test/setup-serves-several.test.ts`.
-- `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 (default none, nothing written). `me/facts` and `company/facts` carry `type: facts` (declared in both base packs; gbrain-base-v2 1.7.0), and the block's facts line tells the agent to quote only their dated lines. `--transcripts DIR` (company shape, not `--team`; refused otherwise before anything is written) runs one `gbrain import DIR --calls --prefix company/calls --no-embed --json` child pinned to the company source (over `IMPORT_INLINE_MAX` .txt/.md files it returns `brain_layout_import_pending` with that argv), then reads who can read the first call page with `gbrain access who-can-read <slug> --source company --json` and `gbrain access serves --json --no-open-pages` (`transcripts.readers`: `every_source_reader` or the members the source's rules allow, plus one or several). Every applied shape (not dry run) ends with `archive` (on, off, offered or unknown), read from `gbrain doctor --only transcript_archive_freshness --json` details, never the archive's first-run notice. At a terminal `askBrainShape(folders, read)` asks for the transcripts folder after the docs folder (solo only). The flag is `--shape` because `--brain` is the global brain-id flag (`cli-options.ts`). Pinned by `test/setup-brain-layout.test.ts`.
-- `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); `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, hash, redactions, embedding_hold: call_import}` (root and hash JSON-quoted so they read back as strings), with no `readable_by`. `root` is `callRootId(dir)` (a hash of the folder path) 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 `file` under the prefix (not the computed slug, which a new modified day can move) and reports it `unchanged` (same hash) or `kept` (never overwritten); a slug held by another page or file gets a hash suffix of root and path. Pinned by `test/import-calls.test.ts`.
+- `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/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 Claude Code and Codex plugin manifests declare setup's UserPromptSubmit hook with `GBRAIN_HOOK_LANE=plugin`; it yields when another gbrain lane wires the event (`bootstrap/plugin-lanes.ts` `pluginHookYields`; `test/plugin-turn-hook.test.ts`). `managed-block.ts` is the shared marker splice/probe/remove that `bootstrap/instructions-block.ts` also uses (`test/setup-brain-first.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`).
-- `src/core/setup/hook-launcher.ts` + `src/core/setup/hook-launcher-refresh.ts` — the trusted-directory hook launcher (#8424): `<config dir>/hook-launcher/gbrain-hook`, a POSIX sh script that records the session directory in `GBRAIN_HOOK_CWD`, changes into its own directory and execs gbrain there, so a script-mode install never lets the session directory's `bunfig.toml` preload or `.env` load; it refuses (exit 1, one stderr line) when its directory holds anything else. A script-mode install's launcher also records the directory of the Bun that wrote it (`launcherRuntimeDir`, preferring the bun on PATH when it is the same file; `hookLauncherScript(dir)`) and puts it first on PATH, so a harness started without bun on PATH still starts gbrain (GST-2784); a compiled gbrain gets the plain launcher (`isScriptRuntime`, exported from cli-preflight.ts). `hookLauncherState` calls a launcher `stale` when it records no Bun that a script install needs, or a Bun that is gone, and `ensureHookLauncher` moves a launcher that records another Bun. Every setup-lane and turn-rule hook command names it (`buildClaudeHookCommand(…, launcher)`, `codexSetupHookGroup(…, launcher)`, `buildCodexSessionEndCommand(bin, launcher)`); `ensureHookLauncher` writes it before any hook that names it, and `gbrain hook` reads the session directory through `hookSessionCwd()`. `hookLauncherProblem` (turn-hook-check.ts) feeds doctor `harness_wiring` (`withHookLaunchers`, code `hook_session_cwd`, reasons `session_cwd|missing|stale|foreign`); `refreshHookLaunchers` runs in `gbrain post-upgrade`, rewrites this install's stale launcher file in place (no entry changes, so no Codex trust moves) and moves the turn-rule entries and each installed user-scope setup receipt's hooks onto the launcher through their own writers. The stdio MCP entries (`desiredMcpEntry`, `desiredCodexMcpEntry`, `registerClaudeMcp`/`registerCodexMcp` with `hookLauncher`) and the bootstrap, harness and Codex SessionEnd lanes use it too (#8426, #8428); `gbrain serve` captures `GBRAIN_HOOK_CWD` through `src/core/session-cwd.ts` and never changes directory. `src/core/setup/launcher-lanes.ts` (`launcherLaneFindings`) finds those entries for doctor and post-upgrade; post-upgrade rewrites only a Claude Code setup MCP entry setup still owns, under the setup lock, and names every Codex and bootstrap entry. Tests: `test/launcher-lanes-bunfig.serial.test.ts`. Tests: `test/hook-launcher-bunfig.test.ts` (a hostile checkout's preload never runs from any shape), `test/setup.test.ts` (#8424 block), `test/setup-codex-bare-path.test.ts` (setup codex's entries start under a PATH with no bun).
+- `src/core/setup/hook-launcher.ts` + `src/core/setup/hook-launcher-refresh.ts` — the trusted-directory hook launcher (#8424): `<config dir>/hook-launcher/gbrain-hook`, a POSIX sh script that records the session directory in `GBRAIN_HOOK_CWD`, changes into its own directory and execs gbrain there, so a script-mode install never lets the session directory's `bunfig.toml` preload or `.env` load; it refuses (exit 1, one stderr line) when its directory holds anything else. A script-mode install's launcher also records the directory of the Bun that wrote it (`launcherRuntimeDir`, preferring the bun on PATH when it is the same file; `hookLauncherScript(dir)`) and puts it first on PATH, so a harness started without bun on PATH still starts gbrain (GST-2784); a compiled gbrain gets the plain launcher (`isScriptRuntime`, exported from cli-preflight.ts). `hookLauncherState` calls a launcher `stale` when it records no Bun that a script install needs, or a Bun that is gone, and `ensureHookLauncher` moves a launcher that records another Bun. Every setup-lane and turn-rule hook command names it (`buildClaudeHookCommand(…, launcher)`, `codexSetupHookGroup(…, launcher)`, `buildCodexSessionEndCommand(bin, launcher)`); `ensureHookLauncher` writes it before any hook that names it, and `gbrain hook` reads the session directory through `hookSessionCwd()`. `hookLauncherProblem` (turn-hook-check.ts) feeds doctor `harness_wiring` (`withHookLaunchers`, code `hook_session_cwd`, reasons `session_cwd|missing|stale|foreign`); `refreshHookLaunchers` runs in `gbrain post-upgrade`, rewrites this install's stale launcher file in place (no entry changes, so no Codex trust moves) and moves the turn-rule entries and each installed user-scope setup receipt's hooks onto the launcher through their own writers. The stdio MCP entries (`desiredMcpEntry`, `desiredCodexMcpEntry`, `registerClaudeMcp`/`registerCodexMcp` with `hookLauncher`) and the bootstrap, harness and Codex SessionEnd lanes use it too (#8426... (line truncated to 2000 chars)
- `src/commands/skillify.ts` + `src/core/skillify/{generator,templates}.ts` — `gbrain skillify scaffold <name>` creates all stubs for a new skill: SKILL.md, script, tests, routing-eval.jsonl, resolver entry, filing-rules pointer. `gbrain skillify check <script>` runs the 10-step checklist (LLM evals, routing evals, check-resolvable gate, filing audit) against a candidate skill before it lands.
-- `src/commands/skillpack.ts` + `src/core/skillpack/{bundle,scaffold,reference,migrate-fence,scrub-legacy,harvest,harvest-lint,copy,apply-hunks,diff-text,installer}.ts` — `install`/`uninstall` are not supported (they exit non-zero with a hint to the replacement). Surface: `scaffold` (one-time additive copy via `copyArtifacts` in `copy.ts`; refuses to overwrite; partial-state fills missing paired sources declared in SKILL.md frontmatter `sources:`), `reference` (read-only diff lens + `--apply-clean-hunks` two-way auto-apply via pure-JS unified-diff parser/applier in `apply-hunks.ts` + `diff-text.ts`; strict arguments through the `skillpack reference` row of `src/cli/strict-args.ts` (#5491): `--dry-run=true`, a typo or an unknown flag exits 2 before any write, the per-skill and `--all` grammars print separately, and `--all --apply-clean-hunks` refuses with the three-command update path; pinned by `test/skillpack-reference-strict-args.test.ts`), `migrate-fence` (one-shot strip of legacy fence; cumulative-slugs receipt → row-parsing fallback; preserves rows verbatim as user-owned routing), `scrub-legacy-fence-rows` (opt-in row cleanup with skill-present + non-empty-triggers gate), `harvest` (host→gbrain inverse with symlink-reject + canonical-path containment via a `validateUploadPath`-style gate + default-on privacy linter in `harvest-lint.ts` against `~/.gbrain/harvest-private-patterns.txt` plus built-in a built-in fork-name pattern + email + Slack-channel patterns; rollback on match). Paired-source declarations live in each SKILL.md's frontmatter `sources:` array (validated by `loadSkillSources` in `bundle.ts`). `autoDetectSkillsDir` (in `src/core/repo-root.ts`) has a `cwd_walk_up` tier ahead of `~/.openclaw/workspace` (`$OPENCLAW_WORKSPACE` precedence preserved). `gbrain skillpack check --strict` exits non-zero on drift (CI gate); top-level `gbrain skillpack-check` keeps exit-1-on-issues for cron. Companion editorial skill `skills/skillpack-harvest/SKILL.md` drives the genericization checklist. Doc: `docs/guides/skillpacks-as-scaffolding.md`. Test coverage across `test/skillpack-{copy,scaffold,reference,reference-apply,apply-hunks,migrate-fence,scrub-legacy,harvest,harvest-lint,frontmatter-sources}.test.ts` + 9-case E2E in `test/skillpack-flow.test.ts`. `installer.ts` + `test/skillpack-install.test.ts` remain because `gbrain skillpack diff` uses `diffSkill` from there.
+- `src/commands/skillpack.ts` + `src/core/skillpack/{bundle,scaffold,reference,migrate-fence,scrub-legacy,harvest,harvest-lint,copy,apply-hunks,diff-text,installer}.ts` — `install`/`uninstall` are not supported (they exit non-zero with a hint to the replacement). Surface: `scaffold` (one-time additive copy via `copyArtifacts` in `copy.ts`; refuses to overwrite; partial-state fills missing paired sources declared in SKILL.md frontmatter `sources:`), `reference` (read-only diff lens + `--apply-clean-hunks` two-way auto-apply via pure-JS unified-diff parser/applier in `apply-hunks.ts` + `diff-text.ts`; strict arguments through the `skillpack reference` row of `src/cli/strict-args.ts` (#5491): `--dry-run=true`, a typo or an unknown flag exits 2 before any write, the per-skill and `--all` grammars print separately, and `--all --apply-clean-hunks` refuses with the three-command update path; pinned by `test/skillpack-reference-strict-args.test.ts`), `migrate-fence` (one-shot strip of legacy fence; cumulative-slugs receipt → row-parsing fallback; preserves rows verbatim as user-owned routing), `scrub-legacy-fence-rows` (opt-in row cleanup with skill-present + non-empty-triggers gate), `harvest` (host→gbrain inverse with symlink-reject + canonical-path containment via a `validateUploadPath`-style gate + default-on privacy linter in `harvest-lint.ts` against `~/.gbrain/harvest-private-patterns.txt` plus built-in a built-in fork-name pattern + email + Slack-channel patterns; rollback on match). Paired-source declarations live in each SKILL.md's frontmatter `sources:` array (validated by `loadSkillSources` in `bundle.ts`). `autoDetectSkillsDir` (in `src/core/repo-root.ts`) has a `cwd_walk_up` tier ahead of `~/.openclaw/workspace` (`$OPENCLAW_WORKSPACE` precedence preserved). `gbrain skillpack check --strict` exits non-zero on drift (CI gate); top-level `gbrain skillpack-check` keeps exit-1-on-issues for cron. Companion editorial skill `skills/skillpack-harvest/SKILL.md` drives ... (line truncated to 2000 chars)
diff --git a/docs/architecture/key-files/core-cycle.md b/docs/architecture/key-files/core-cycle.md
index 96295363f2..6f99374844 100644
--- a/docs/architecture/key-files/core-cycle.md
+++ b/docs/architecture/key-files/core-cycle.md
@@ -23,7 +23,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/cycle/extract-atoms-budget-notice.ts` — #6425: `drainBudgetNotice(result)` renders the `atom_drain_budget` notice a `budget`-stopped drain carries in `gbrain dream --drain --json` (spend, per-run cap, pages left; paid fix `gbrain config set cycle.extract_atoms.budget_usd <USD>`, verify `gbrain config get`), and `usd` formats the amounts for the stderr stop line. Dynamically imported by `dream.ts` so its notice-rendering imports stay out of the CLI flag scan. Tests: `test/dream-drain-failure-summary.serial.test.ts`.
- `src/core/cycle/extract-atoms-input.ts` — #6503 the input cap and the partial disposition. `resolveExtractAtomsInputCap` reads `cycle.extract_atoms.max_input_chars` (floor 1000; the older `max_source_chars`, floor 500, loses when both are set; default 50 000) before discovery. `extractAtomsInput(item, cap)` binds the cut once: paste-stripped for a transcript (#5812), UTF-8-safe, with `truncated` measured on the text the cap applied to. A page item also takes its stored `extract_atoms` watermark (`src/core/extraction-watermark.ts`, large pages A7): when the body still starts with the watermarked prefix the model reads only the appended text (its newest `cap` characters when longer), which is still partial input, so the same disposition below applies; `inputTruncatedLine` is null for a complete tail read (not counted, no stderr) and names the window otherwise, and the phase commits the plan once the item's writes committed (a pending managed batch keeps the old watermark). A cut item is extracted once from its head and gets a partial disposition instead of a completion: `input_truncated` counts it on the phase result (and the drain sums it into `input_truncated`, with one `[drain]` line), `inputTruncatedLine` is written to stderr naming the knob, the head atoms publish, no completion stamp is written and nothing is retired. `recordPartialDisposition` stores the cap under (content hash, cap) in `extract_atoms_page_state` / `extract_atoms_transcript_state.partial_input_chars` (migration v240; the page row is pinned to the identity discovery read), and on a managed brain the origin carries `partialInputChars`, which enters the run key, keeps the completion's checkpoint `partial`, skips the page-state stamp and the retirement, and marks the completion outcome `status: 'partial'`. Discovery and the backlog count skip a partial row like a tombstone (`PAGE_SCAN_STATE_EXCLUSION_SQL`, `tombstonedTranscriptsForHashes`, the partial checkpoint); `releasePartialDispositions` runs before discovery with the current cap and clears the rows and checkpoints a raised cap supersedes, so the item is eligible again with zero model calls in between; `countExtractAtomsBacklog` reads the same cap and counts a page whose partial row or checkpoint sits below it (`pageScanStateExclusionSql` / `managedAtomDiscoverySql` with the cap; #7391), so a drain, doctor and autopilot see it before any phase has released it, while counting itself writes nothing (`test/extract-atoms-raised-cap-drain-7391.test.ts`); a content change is a new row. Resumed and budget-skipped items are not counted. `stampTranscriptTombstone` (v146) lives here too. Tests: `test/extract-atoms-input-truncated-6503.test.ts` (PGLite and Postgres, page and transcript, managed and unmanaged). A page is read as a world reader sees it (`publicBody` from `mentions/aliases.ts`: facts rows other than world and the takes fence removed) before the cap and the watermark apply, so the prompt, the atoms and a verified `source_quote` never hold a row a remote read of the page hides; test: `test/extract-atoms-world-fence-rows.test.ts` (unmanaged and managed, PGLite and Postgres).
-- `src/core/cycle/extract-atoms.ts` — the extract_atoms lens phase: mines eligible pages into `atoms/<date>/<stem>-<hash>` pages. The input cap, the cut and the partial disposition of a cut item are in `extract-atoms-input.ts` (#6503). Transcript input is paste-stripped before the cut (#5812); discovery skips self-captures (#5820) and keeps only the session-corpus files `keepSessionSourceTranscripts` (`synthesize-source-routing.ts`, shared with synthesize; a file is a corpus file by its spelled or real path, an unreadable real path is held `corpus_path_unresolvable`, #7871) resolves to the run's source, read-only in a dry run, reporting the rest in `details.source_routing` (#7846); a resumed generation member whose transcript no longer resolves to the run's source (`transcriptSourceHold`) is held, not resubmitted, and counted in `details.source_routing.generation_members_held` (#7870); the meeting transcripts dir is read only for `default`. Discovery and the backlog count append `connectorAtomExclusionSql` (`connector-atoms.ts`), so connector `email`/`meeting` pages stay out only when `cycle.extract_atoms.connector_pages` is false. The type allowlist is `unionExtractableTypes(packExtractable, packExcluded)`: the legacy floor (meeting, source, article, video, book, original) minus the floor types the active pack declares not extractable (`nonExtractableTypesFromPack`, #5756; a declared type without `extractable: true` is a pack decision, an undeclared type keeps the floor), plus the pack's `extractable: true` types, minus synthesis outputs; gbrain-base is unchanged, gbrain-recommended's `source: false` now holds for atoms as it did for facts. Pinned by `test/pack-extractable-floor-5756.test.ts`. A drain attempt passes `opts.attempt` (`budgetTracker`, `writeWait`) so its batches share one budget and one maintenance publish wait. Eligibility reads source-incarnation/page/full-hash-keyed derived scan state; scan and failure markers do not mutate canonical frontmatter. Managed extraction checks source-wide local authority and owner readiness before provider work, admits outputs plus a completion request together, and replays retained output without another model call. A failed managed batch is retried by the next run instead (#6325, `resumeManagedAtoms` in `persistence/atom-maintenance.ts`); an origin held after `MAX_DETERMINISTIC_FAILURES` (now defined in `extract-atoms-page-state.ts`, re-exported here) is skipped with no model call and counted in `details.held_failed`, never in `failures`. Managed atom files keep provisional source hashes; only the source-incarnation/page/full-hash durable completion receipt excludes an item from discovery and backlog counts. Unmanaged atom completion flips and their cardinality check share a transaction after provenance links persist, so a partial match rolls back and stays retryable. A page-derived atom upserts at its locator-folded slug, else a compatible legacy title-only slug; when both miss, the source page's live bound atoms are loaded once per page per run and exactly one JS-lowercased title match is adopted (a case-only title change never mints a duplicate; zero or several matches mint the new slug). Response parsing lives in `extract-atoms-parse.ts`. Atoms of one item that resolve to one slug (a repeated title) publish once, the first kept (#7514: two items at one key failed the generation, managed `generation_live_conflict`, unmanaged a primary-key violation). A managed item whose atom write did not commit is a write failure (`atomWriteFailure`, `persistence/atom-maintenance.ts`): its `failures` entry carries `request_id`, `code`, and its strike, never a provider classification. An undated source dates its atoms by the source page's creation date (`undated` for transcripts), never the run date. A page-derived atom's frontmatter `date` is the source page's content date (`atom-source-date.ts`: the stored `effective_date`, else `computeEffectiveDate`), read with the input before the model call, so classic import and managed publication store that `effective_date` (source `date`) and `extracted_at` stays the processing stamp; transcript-derived atoms carry no `date`. After an unmanaged item completes (`completeUnmanagedItem`), `retireStaleAtoms` soft-deletes that source's atoms from earlier extractions (other or provisional `source_hash`) that this extraction did not re-produce; a cut item neither completes nor retires. Hard `opts.signal` (chat call, pacing, checks before each item and commit) leaves no strike, receipt or rollup; soft `opts.stopSignal` stops before the next item.
+- `src/core/cycle/extract-atoms.ts` — the extract_atoms lens phase: mines eligible pages (shelf excluded) into `atoms/<date>/<stem>-<hash>` pages. The input cap, the cut and the partial disposition of a cut item are in `extract-atoms-input.ts` (#6503). Transcript input is paste-stripped before the cut (#5812); discovery skips self-captures (#5820) and keeps only the session-corpus files `keepSessionSourceTranscripts` (`synthesize-source-routing.ts`, shared with synthesize; a file is a corpus file by its spelled or real path, an unreadable real path is held `corpus_path_unresolvable`, #7871) resolves to the run's source, read-only in a dry run, reporting the rest in `details.source_routing` (#7846); a resumed generation member whose transcript no longer resolves to the run's source (`transcriptSourceHold`) is held, not resubmitted, and counted in `details.source_routing.generation_members_held` (#7870); the meeting transcripts dir is read only for `default`. Discovery and the backlog count append `connectorAtomExclusionSql` (`connector-atoms.ts`), so connector `email`/`meeting` pages stay out only when `cycle.extract_atoms.connector_pages` is false. The type allowlist is `unionExtractableTypes(packExtractable, packExcluded)`: the legacy floor (meeting, source, article, video, book, original) minus the floor types the active pack declares not extractable (`nonExtractableTypesFromPack`, #5756; a declared type without `extractable: true` is a pack decision, an undeclared type keeps the floor), plus the pack's `extractable: true` types, minus synthesis outputs; gbrain-base is unchanged, gbrain-recommended's `source: false` now holds for atoms as it did for facts. Pinned by `test/pack-extractable-floor-5756.test.ts`. A drain attempt passes `opts.attempt` (`budgetTracker`, `writeWait`) so its batches share one budget and one maintenance publish wait. Eligibility reads source-incarnation/page/full-hash-keyed derived scan state; scan and failure markers do not mutate canonical frontmatter. Managed extraction checks source-wide local authority and owner readiness before provider work, admits outputs plus a completion request together, and replays retained output without another model call. A failed managed batch is retried by the next run instead (#6325, `resumeManagedAtoms` in `persistence/atom-maintenance.ts`); an origin held after `MAX_DETERMINISTIC_FAILURES` (now defined in `extract-atoms-page-state.ts`, re-exported here) is skipped with no model call and counted in `details.held_failed`, never in `failures`. Managed atom files keep provisional source hashes; only the source-incarnation/page/full-hash durable completion receipt excludes an item from discovery and backlog counts. Unmanaged atom completion flips and their cardinality check share a transaction after provenance links persist, so a partial match rolls back and stays retryable. A page-derived atom upserts at its locator-folded slug, else a compatible legacy title-only slug; when both miss, the source page's live bound atoms are loaded once per page per run and exactly one JS-lowercased title match is adopted (a case-only title change never mints a duplicate; zero or several matches mint the new slug). Response parsing lives in `extract-atoms-parse.ts`. Atoms of one item that resolve to one slug (a repeated title) publish once, the first kept (#7514: two items at one key failed the generation, managed `generation_live_conflict`, unmanaged a primary-key violation). A managed item whose atom write did not commit is a write failure (`atomWriteFailure`, `persistence/atom-maintenance.ts`): its `failures` entry carries `request_id`, `code`, and its strike, never a provider classification. An undated source dates its atoms by the source page's creation date (`undated` for transcripts), never the run date. A page-derived atom's frontmatter `date` is the source page's content date (`atom-source-date.ts`: the stored `effective_date`, else `computeEffectiveDate`), read with the input before the model call, so classic import and managed publication store that `effective_date` (source `date`) and `extracted_at` stays the processing stamp; transcript-derived atoms carry no `date`. After an unmanaged item completes (`completeUnmanagedItem`), `retireStaleAtoms` soft-deletes that source's atoms from earlier extractions (other or provisional `source_hash`) that this extraction did not re-produce; a cut item neither completes nor retires. Hard `opts.signal` (chat call, pacing, checks before each item and commit) leaves no strike, receipt or rollup; soft `opts.stopSignal` stops before the next item.
Managed completion admits revision-pinned `managed_atom_delete` children alongside replacement pages, removes canonical files through the page deletion path, and commits its checkpoint only after every publication and retirement commits.
Both paths prevent LLM-chosen titles that drift between extractions from piling up.
Atom identity: page-derived atoms fold the source-page slug into the slug hash (8 chars, NUL-separated) so two same-date pages emitting the same title get DISTINCT slugs; the source CONTENT hash is deliberately NOT folded (a reworded source still upserts rather than duping); transcript atoms keep the legacy title-only 6-char hash. `resolvePageAtomSlug` adopts a legacy-slug atom with a compatible binding in place on re-extraction (upgrade idempotency — no migration, no duplicate), while `assertAtomImportBinding` fail-closed refuses to reuse a slug bound to a DIFFERENT source locator. Both share `isCompatibleAtomBinding(frontmatter, sourcePageSlug)` — the ONE definition of compatible: bound to THIS source page, or carrying no `source_slug`/`source_path` at all (pre-binding-era adoption, not a clobber); a `source_path`-bound legacy transcript atom or a different `source_slug` is a different origin, and a non-atom page squatting on the slug is refused. `source_quote` is verified at extraction time against the exact `truncateUtf8` prompt prefix the model saw (`locateQuote` advances by full code points): located quotes persist original characters + [start,end) offsets + `source_quote_verified`; unlocatable quotes are dropped with the atom kept. Edges write before the completion flip; per-item drain failures stay typed (bounded, sanitized, reconcilable). Transcript items carry the same failure-count/tombstone machinery as pages, in the `extract_atoms_transcript_state` table (keyed `(source_id, file_path, content_hash)`, 16-char hash prefix, so an edit is a new row): `recordItemFailureCount` counts a transcript's malformed output or prompt-level provider block (`providerContentBlockReason`; never feeds the outage halt) toward `MAX_DETERMINISTIC_FAILURES`, a zero-yield transcript tombstones immediately (as pages do), and `tombstonedTranscriptsForHashes` is the batch read-side gate mirroring `atomsExistingForHashes` (fail-open on error). Reported as `tombstoned_transcripts` (paths), separate from the page-slug `tombstoned_for_failures`. Malformed managed output requires a newly approved protected-job retry identity; publication retry reuses retained output and original/current grants.
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.md
index e13e4afd03..9b5920cb99 100644
--- a/docs/guides/error-codes.md
+++ b/docs/guides/error-codes.md
@@ -5652,9 +5652,9 @@ More: [docs/guides/write-refusals.md#storage-manifest-refusals](../../docs/guide
| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
|---|---|---|---|---|---|---|
-| A storage card failed validation (a missing or malformed field, a command field, or a field gbrain stamps itself); nothing was written. | Every card must say where the item is, how big it is and how to restore it, and carries no commands, so a card is complete and safe to act on when it is found months later. | Fix the field the message names and send the card again; gbrain storage-register --help lists the card fields. For an adopt blocked on access_pending or access_unpreservable, settle the access rules over the interim page (gbrain access status) or give it readers its folder rules also list, then preview again. | agent | `repeat the read that failed` | 1 | no |
+| A storage card failed validation (a missing or malformed field, a command field, or a field gbrain stamps itself); nothing was written. | Every card must say where the item is, how big it is and how to restore it, and carries no commands, so a card is complete and safe to act on when it is found months later. | Fix the field the message names and send the card again; gbrain storage-register --help lists the card fields. For an adopt blocked on access_pending or access_unpreservable, settle the access rules over the interim page (gbrain access status) or give it readers its folder rules also list, then preview again. For truncated, move the ## Record section to the top of the interim page. | agent | `repeat the read that failed` | 1 | no |
-Reasons: `schema`, `command_field`, `stamped_field`, `not_json`, `not_object`, `too_large`, `id_change`, `no_record`, `duplicate_id`, `access_unpreservable`, `access_pending`, `labels`, `remote_written`.
+Reasons: `schema`, `command_field`, `stamped_field`, `not_json`, `not_object`, `too_large`, `id_change`, `no_record`, `truncated`, `duplicate_id`, `access_unpreservable`, `access_pending`, `labels`, `remote_written`.
More: [docs/guides/write-refusals.md#storage-manifest-refusals](../../docs/guides/write-refusals.md#storage-manifest-refusals)
diff --git a/docs/guides/storage-manifest.md b/docs/guides/storage-manifest.md
index ffbf411554..24b40b15c1 100644
--- a/docs/guides/storage-manifest.md
+++ b/docs/guides/storage-manifest.md
@@ -55,7 +55,9 @@ Agents that archived before the shelf existed often kept interim pages: `type: s
`stamped_field`). It writes nothing and prints a `plan_hash`. The index page (`<prefix>index`) is skipped.
2. The printed apply, `--apply --expect <plan_hash>` with one `--drop-field <dotted.name>` per refused field, runs
after the user agrees to leave those fields out. It registers each card with `origin: adopt` through the same
- path `storage-register` uses, then tags the original `storage-manifest-adopted`. It deletes nothing. A
+ path `storage-register` uses, then tags the original `storage-manifest-adopted`. It deletes nothing. On a hosted
+ shelf it then runs the shelf's managed `--no-pull` sync, so the shelf's sync checkpoint reaches the cards it
+ committed; `index` reports it, with the sync to run when it stayed behind. A
credential-shaped value (a secret, an environment assignment, a credential variable, a URL password, a signed URL,
a value under a credential-named key such as `restore.args.password`, `restic_password` or `token_count`, unless the
key ends in `_id`, `_ref`, `_name`, `_path`, `_file`, `_env`, `_var` or `_variable`) always refuses, whatever is
@@ -76,7 +78,8 @@ Agents that archived before the shelf existed often kept interim pages: `type: s
A rerun skips cards already on the shelf that match and originals already tagged. A card on the shelf that differs is
a conflict (a card without the original's access labels too): it is reported and never overwritten, and its original
-stays untagged. Every apply reports `side_effects: none | partial | complete`; a run that stopped part way prints the
+stays untagged. Every apply reports `side_effects: none | partial | complete`; an adopt apply also reports `counts`
+(`adopted`, `skipped`, `refused`, `pending`) and, on each `results` row that wrote, the write's `request_id`. A run that stopped part way prints the
command that finishes it. A write gbrain accepted that has not committed yet is listed under `pending` with its
receipt: poll it with `gbrain write-request <id>` (the command exits 10) and rerun once it has committed, never submit
it again.
diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.md
index 52f97984c8..88ea6cf36d 100644
--- a/docs/guides/write-refusals.md
+++ b/docs/guides/write-refusals.md
@@ -1141,7 +1141,7 @@ An adopt or import apply whose plan changed since its preview refuses `preview_c
| Code | What happened | What to do |
|---|---|---|
| `storage_source_managed` | `put_page`, `remember` or another page writer targeted the shelf. | Register with `gbrain storage-register`, change with `gbrain storage-update`. |
-| `storage_record_invalid` | A card field is missing or malformed, names a command (`command`, `script`, `exec` and similar), or is one gbrain sets itself (`registered_by`, `origin`). On adopt, reason `access_unpreservable` means an interim page's `readable_by` and the folder rules over it share no reader, and `access_pending` that a rule over it is still being applied, so no card could carry the same restriction; on import, `labels` means a line's `labels` holds something other than access labels; `remote_written` means a remote (MCP) client last wrote the interim page, so adopt never registers it (check it and use `gbrain storage-register`). `storage_get` refuses it too for a stored card that breaks these rules, such as a hand-edited card file. | Fix the field the message names. Restore runs through `restore.skill` and `restore.args`. For `access_pending`, finish the rule change (`gbrain access status`) and preview again; for `access_unpreservable`, give the page readers its folder rules also list. For a stored card, `gbrain doctor --only storage_manifest` lists the invalid cards, and the refusal carries the card's revision for `gbrain storage-update <id> --expected-revision <rev> --patch '<json>'`. |
+| `storage_record_invalid` | A card field is missing or malformed, names a command (`command`, `script`, `exec` and similar), or is one gbrain sets itself (`registered_by`, `origin`). On adopt, reason `access_unpreservable` means an interim page's `readable_by` and the folder rules over it share no reader, and `access_pending` that a rule over it is still being applied, so no card could carry the same restriction; on import, `labels` means a line's `labels` holds something other than access labels; `remote_written` means a remote (MCP) client last wrote the interim page, so adopt never registers it (check it and use `gbrain storage-register`); `truncated` means the interim page is longer than the 64 KiB adopt reads and its `## Record` block is cut off or past that point. `storage_get` refuses it too for a stored card that breaks these rules, such as a hand-edited card file. | Fix the field the message names. Restore runs through `restore.skill` and `restore.args`. For `access_pending`, finish the rule change (`gbrain access status`) and preview again; for `access_unpreservable`, give the page readers its folder rules also list; for `truncated`, move the `## Record` section to the top of the page. For a stored card, `gbrain doctor --only storage_manifest` lists the invalid cards, and the refusal carries the card's revision for `gbrain storage-update <id> --expected-revision <rev> --patch '<json>'`. |
| `storage_record_secret` | A field looks like a secret or has a credential shape: an environment assignment, a credential-named variable, a URL password, a signed-URL parameter, or a value under a credential-named key such as `password` or `token_value`. The value is not echoed. | Remove it; the restore skill reads credentials from its own environment. A key that holds no credential can be renamed to end in `_id`, `_ref`, `_name`, `_path`, `_file`, `_env`, `_var` or `_variable`. |
| `storage_card_exists` | A card with that id is already registered. | Update it with the revision `storage_get` returns, or use another id. |
| `storage_revision_conflict` | The card changed since its revision was read; `detail` holds the current revision. | Read it again, apply the change, update once. |
diff --git a/docs/mcp/ADMIN.md b/docs/mcp/ADMIN.md
index 47833377f8..1bf9412f3f 100644
--- a/docs/mcp/ADMIN.md
+++ b/docs/mcp/ADMIN.md
@@ -368,15 +368,23 @@ nothing is widened automatically: ask the user first.
The commands differ by credential type:
```bash
-# Legacy token: preview the operations added since the snapshot, then add the approved ones
+# Legacy token: list the operations added since the snapshot, preview adding them, then add them
gbrain auth rescope --token NAME --refresh-operations
-gbrain auth rescope --token NAME --refresh-operations --add put_pages
+gbrain auth rescope --token NAME --refresh-operations --add OP1,OP2,... --dry-run
+gbrain auth rescope --token NAME --refresh-operations --add OP1,OP2,...
# OAuth client: no refresh; pass the whole new snapshot, plus --surface full when the pin blocks too
gbrain auth rescope --client CLIENT_ID --operations OP1,OP2,... --surface full --dry-run
gbrain auth rescope --client CLIENT_ID --operations OP1,OP2,... --surface full
```
+`gbrain doctor` fills the list with every operation it counted for that
+grant except the membership operations below (for a client, the current
+snapshot plus those), and each `--dry-run` prints the operation list before
+and after without changing the grant. Counted membership operations are listed
+apart with a second command that adds them by name; it is never the doctor
+fix, because only the owner approves them.
+
`--refresh-operations` is token-only (a client gets
`client_refresh_operations_unsupported`). Removing the snapshot instead is a
separate, disclosed choice, never the default repair: `--operations all` for a
diff --git a/src/commands/auth.ts b/src/commands/auth.ts
index 886c642022..fcb6bb19a2 100644
--- a/src/commands/auth.ts
+++ b/src/commands/auth.ts
@@ -931,19 +931,18 @@ async function rescopeClientWith(engine: BrainEngine, clientId: string, parsed:
if (parsed.json) { console.log(JSON.stringify({ ...result, principal_grant: grantFromClient(result.after), ...(bound ? { binding: bound } : {}) }, null, 2)); return; }
console.log(`OAuth client ${parsed.dryRun ? 'grant preview' : 'rescoped'}: ${result.after.clientName} (${clientId})`);
console.log(` Revision: ${result.before.revision} -> ${result.after.revision}`);
- printClientGrantAxes(result.after);
+ printClientGrantAxes(result.after, parsed.dryRun ? result.before : undefined);
if (bound) console.log(bindingLine(bound, parsed.dryRun));
console.log('Restrictions apply on the next request. Added scopes require a new access token; the client secret is unchanged.');
}
-function printClientGrantAxes(grant: ClientGrant) {
- console.log(` Scopes: ${grant.scopes.join(' ') || '<none>'}`);
- console.log(` Write source: ${grant.sourcesNone ? 'none (every read and write refused)' : grant.sourceId}`);
- console.log(` Federated reads: ${grant.federatedRead.join(', ') || '<none>'}\n Operations: ${grant.allowedOperations === null ? 'all (no snapshot)' : grant.allowedOperations.join(', ') || 'none'}\n Slug prefixes: ${grant.boundSlugPrefixes?.join(', ') || '<none>'}`);
- console.log(` Takes holders: ${grant.takesHolders === null ? 'world (default)' : grant.takesHolders.join(', ') || 'none (every take hidden)'}`);
- console.log(` Private pages: ${renderPrivatePages(grant.privatePages)}`);
- console.log(` Tool surface: ${grant.surface ?? '<server default>'}`);
- console.log(` Delegated spending: ${grant.budgetUsdPerDay === null ? 'unlimited' : '$' + grant.budgetUsdPerDay + '/day'}`);
+/** A grant's axes, one line each; with `before` (a preview) a changed axis reads `before -> after`. */
+function printClientGrantAxes(grant: ClientGrant, before?: ClientGrant) {
+ const axes: Array<[string, (g: ClientGrant) => string]> = [['Scopes', g => g.scopes.join(' ') || '<none>'], ['Write source', g => g.sourcesNone ? 'none (every read and write refused)' : String(g.sourceId)],
+ ['Federated reads', g => g.federatedRead.join(', ') || '<none>'], ['Operations', g => g.allowedOperations === null ? 'all (no snapshot)' : g.allowedOperations.join(', ') || 'none'],
+ ['Slug prefixes', g => g.boundSlugPrefixes?.join(', ') || '<none>'], ['Takes holders', g => g.takesHolders === null ? 'world (default)' : g.takesHolders.join(', ') || 'none (every take hidden)'],
+ ['Private pages', g => renderPrivatePages(g.privatePages)], ['Tool surface', g => g.surface ?? '<server default>'], ['Delegated spending', g => g.budgetUsdPerDay === null ? 'unlimited' : '$' + g.budgetUsdPerDay + '/day']];
+ for (const [label, render] of axes) { const after = render(grant), was = before ? render(before) : after; console.log(` ${label}: ${was === after ? after : `${was} -> ${after}`}`); }
}
function printTokenRescope(result: RescopeTokenResult, json: boolean, bound?: BindingResult) {
diff --git a/src/commands/doctor/checks/grant-new-ops.ts b/src/commands/doctor/checks/grant-new-ops.ts
index 25f5ee07e5..103f9a066b 100644
--- a/src/commands/doctor/checks/grant-new-ops.ts
+++ b/src/commands/doctor/checks/grant-new-ops.ts
@@ -20,6 +20,7 @@ import { loadConfig, type GBrainConfig } from '../../../core/config.ts';
import { grantFromRow, grantFromTokenRow } from '../../../core/grants/model.ts';
import { readClientCatalogProvenance } from '../../../core/grants/service.ts';
import { ALL_OPERATIONS_CHOICE, grantAge, grantBlockers, grantOperationGaps, grantRescopeArgvs, type GrantGaps, type RescopeTarget } from '../../../core/harness/capabilities.ts';
+import { requiresExplicitApproval } from '../../../core/ops/execution-prerequisites.ts';
import { clampSurface, isMcpSurface, minSurface, resolveDefaultClientSurface, resolveSurface, surfaceWiderThan, type McpSurface } from '../../../mcp/surface.ts';
import { disabledOpsForPublishGates } from '../../../mcp/publish-gates.ts';
import type { Check } from '../../doctor.ts';
@@ -27,7 +28,6 @@ import { checkError, doctorVerify } from '../check-fix.ts';
import { connectedEngine, type DoctorContext, type DoctorEntry } from '../context.ts';
const DOCS = 'docs/mcp/ADMIN.md#grants-that-cannot-reach-new-operations';
-const BULK_WRITE = 'put_pages';
interface GrantFinding {
kind: 'oauth_client' | 'legacy_token';
@@ -37,21 +37,30 @@ interface GrantFinding {
blockers: Array<Record<string, unknown>>;
excluded_operations: { operation_snapshot: string[]; client_pin: string[]; server_ceiling: string[] };
grant_age: ReturnType<typeof grantAge>;
- preview_argv: string[];
- argv: string[];
+ /** Null when only by-name operations are missing: there is no default repair. */
+ preview_argv: string[] | null;
+ argv: string[] | null;
all_operations_argv: string[];
+ /** Missing operations the owner approves by name; argv leaves them out and by_name_argv adds them. */
+ by_name_operations: string[];
+ by_name_argv: string[] | null;
}
function finding(kind: GrantFinding['kind'], id: string, name: string, profile: string | null, gaps: GrantGaps, target: RescopeTarget,
snapshot: readonly string[] | null, age: ReturnType<typeof grantAge>, surfaces: { client: McpSurface | null; clientSetBy: string | null; server: McpSurface | null }): GrantFinding {
- const bulk = gaps.snapshotExcluded.includes(BULK_WRITE);
- const operations = !bulk ? null : kind === 'legacy_token' ? BULK_WRITE : [...new Set([...(snapshot ?? []), BULK_WRITE])].sort().join(',');
- const argvs = grantRescopeArgvs(target, gaps, operations);
+ const byName = gaps.snapshotExcluded.filter(requiresExplicitApproval);
+ const plain = gaps.snapshotExcluded.filter(op => !requiresExplicitApproval(op));
+ const list = (added: string[], all: string[]) => !added.length ? null
+ : kind === 'legacy_token' ? added.join(',') : [...new Set([...(snapshot ?? []), ...all])].sort().join(',');
+ const argvs = grantRescopeArgvs(target, { ...gaps, snapshotExcluded: plain }, list(plain, plain));
+ const repairable = plain.length > 0 || gaps.pinExcluded.length > 0;
const blockers = grantBlockers(gaps, { clientSurface: surfaces.client, clientSurfaceSetBy: surfaces.clientSetBy, serverSurface: surfaces.server });
return {
kind, id, name, profile, blockers,
excluded_operations: { operation_snapshot: gaps.snapshotExcluded, client_pin: gaps.pinExcluded, server_ceiling: gaps.serverExcluded },
- grant_age: age, preview_argv: argvs.preview, argv: argvs.apply, all_operations_argv: argvs.all_operations,
+ grant_age: age, preview_argv: repairable ? argvs.preview : null, argv: repairable ? argvs.apply : null, all_operations_argv: argvs.all_operations,
+ by_name_operations: byName,
+ by_name_argv: byName.length ? grantRescopeArgvs(target, { snapshotExcluded: byName, pinExcluded: [] }, list(byName, gaps.snapshotExcluded)).apply : null,
};
}
@@ -66,7 +75,13 @@ function describeFinding(f: GrantFinding): string {
: 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} Preview: ${shownCommand(f.preview_argv)}`;
+ return `${label}: ${parts.join(', ')}.${age}${f.preview_argv ? ` Preview: ${shownCommand(f.preview_argv)}` : ''}${byNameNote(f)}`;
+}
+
+function byNameNote(f: GrantFinding): string {
+ if (!f.by_name_argv) return '';
+ return ` ${f.by_name_operations.length} of the missing operations need the owner's approval by name (${f.by_name_operations.join(', ')}), `
+ + `so ${f.argv ? 'that command leaves them out' : 'there is no default repair'}; an owner who approves them adds them with ${shownCommand(f.by_name_argv)}`;
}
export async function checkGrantNewOps(engine: BrainEngine, opts: { cfg?: GBrainConfig | null } = {}): Promise<Check> {
@@ -117,16 +132,16 @@ export async function checkGrantNewOps(engine: BrainEngine, opts: { cfg?: GBrain
return { name: 'grant_new_ops_available', status: 'ok', message: `Every active client and token can call the operations its scopes allow.${ceilingNote}`,
details: { grants: [], server_surface: ceiling, docs: DOCS } };
}
- const first = findings[0];
- 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,
+ 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,
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}). `
- + `For ${first.name}: preview the change with ${shownCommand(first.preview_argv)}, then apply it; or leave it as it is; `
- + `or remove its snapshot with ${first.all_operations_argv.join(' ')} (${ALL_OPERATIONS_CHOICE}). Which do you want?`,
- ...(placeholder ? { inputs: [{ name: 'OPERATIONS', how: `The operations the user approves for ${first.name}, comma-separated (clients: the whole new snapshot, i.e. the current one plus the approved additions; details.grants[0].excluded_operations lists the candidates).` }] } : {}),
+ + `For ${first.name}: preview the change with ${shownCommand(first.preview_argv!)}, then apply it; or leave it as it is; `
+ + `or remove its snapshot with ${first.all_operations_argv.join(' ')} (${ALL_OPERATIONS_CHOICE}).${byNameNote(first)} Which do you want?`,
+ ...(placeholder ? { inputs: [{ name: 'OPERATIONS', how: `The operations the user approves for ${first.name}, comma-separated (clients: the whole new snapshot, i.e. the current one plus the approved additions; details.grants[${findings.indexOf(first)}].excluded_operations lists the candidates).` }] } : {}),
};
return {
name: 'grant_new_ops_available', status: 'warn',
@@ -136,7 +151,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/import-calls.ts b/src/commands/import-calls.ts
index e762fb5b67..f72b2164ab 100644
--- a/src/commands/import-calls.ts
+++ b/src/commands/import-calls.ts
@@ -15,25 +15,28 @@
* (facts_backstop: false), so nothing paid runs;
* - the file path is redacted like the title (call_import.file), and the page waits for the owner's approval before
* 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 (call_import.root and file
- * under the prefix, not 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
+ * - 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
* of their path on the second.
*
* These are not agent sessions: nothing here touches conversations/ or the conversation archive switch.
*/
import { createHash, randomUUID } from 'node:crypto';
import { lstatSync, readdirSync, readFileSync } from 'node:fs';
-import { basename, join, relative } from 'node:path';
+import { basename, dirname, join, relative } from 'node:path';
import type { BrainEngine } from '../core/engine.ts';
import type { RunImportResult } from './import.ts';
-import { writeJsonDocument } from '../core/cli-force-exit.ts';
+import { setCliExitVerdict, writeJsonDocument } from '../core/cli-force-exit.ts';
import { loadConfig } from '../core/config.ts';
import { getCliOptions } from '../core/cli-options.ts';
import { slugifySegment } from '../core/sync.ts';
import { neutralizeOutsideText } from '../core/outside-content.ts';
import { loadImportRedactionPatterns, redactSession, type ImportRedactionPattern } from '../core/transcripts/render.ts';
-import { CLI_WRITE_WAIT_MS } from '../core/persistence/write-wait.ts';
+import { 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';
export const CALL_FILE_RE = /\.(txt|md)$/i;
export const DEFAULT_CALL_PREFIX = 'calls';
@@ -44,6 +47,8 @@ export interface CallPage {
rel: string;
/** The relative path as stored and printed: redacted like the title and body. */
file: string;
+ /** call_import.path: a digest of the folder and the unredacted relative path, the file's identity across reruns. */
+ path?: string;
slug: string;
title: string;
date: string;
@@ -56,11 +61,14 @@ export interface CallPage {
export interface CallFileResult {
file: string;
slug: string;
- status: 'imported' | 'unchanged' | 'kept' | 'error';
+ status: 'imported' | 'unchanged' | 'kept' | 'pending' | 'error';
date_from?: CallPage['date_from'];
redactions?: number;
git_state?: string;
error?: string;
+ /** A pending write: its request and the command that reads its receipt. */
+ request_id?: string;
+ poll?: string;
}
/** .txt and .md files under `dir`, sorted; dot entries and symlinks are skipped. */
@@ -105,7 +113,7 @@ function firstLine(text: string): string {
}
/** The page one call file becomes: slug, title, date, and the redacted, structure-neutral content. */
-export function callPageFor(rel: string, text: string, mtimeMs: number, prefix: string, patterns: ImportRedactionPattern[], root?: string): CallPage {
+export function callPageFor(rel: string, text: string, mtimeMs: number, prefix: string, patterns: ImportRedactionPattern[], root?: string, pathId?: string): CallPage {
const redact = (s: string): string => redactCallPath(s, patterns).file;
const name = redact(basename(rel).replace(CALL_FILE_RE, ''));
const lead = LEADING_DATE_RE.exec(name);
@@ -131,17 +139,18 @@ export function callPageFor(rel: string, text: string, mtimeMs: number, prefix:
'call_import:',
` file: ${JSON.stringify(path.file)}`,
...(root ? [` root: ${JSON.stringify(root)}`] : []),
+ ...(pathId ? [` path: ${JSON.stringify(pathId)}`] : []),
` hash: ${JSON.stringify(hash)}`,
` redactions: ${redacted.redactionCount + path.redactions}`,
' embedding_hold: call_import',
'---',
].join('\n');
- return { rel, file: path.file, slug: `${prefix}/${date}-${slugTitle}`, title, date, date_from: fromName ? 'file_name' : fromLine ? 'first_line' : 'modified', content: `${frontmatter}\n${body}\n`, redactions: redacted.redactionCount + path.redactions, hash };
+ return { rel, file: path.file, ...(pathId ? { path: pathId } : {}), slug: `${prefix}/${date}-${slugTitle}`, title, date, date_from: fromName ? 'file_name' : fromLine ? 'first_line' : 'modified', content: `${frontmatter}\n${body}\n`, redactions: redacted.redactionCount + path.redactions, hash };
}
-const callImportOf = (frontmatter: unknown): { file?: unknown; root?: unknown; hash?: unknown } | null => {
+const callImportOf = (frontmatter: unknown): { file?: unknown; root?: unknown; path?: unknown; hash?: unknown } | null => {
const ci = (frontmatter as { call_import?: unknown } | null)?.call_import;
- return ci && typeof ci === 'object' ? ci as { file?: unknown; root?: unknown; hash?: unknown } : null;
+ return ci && typeof ci === 'object' ? ci as { file?: unknown; root?: unknown; path?: unknown; hash?: unknown } : null;
};
/** A file path with the same credential redaction as the call's title, so a secret in a file name is never stored or printed. */
@@ -158,7 +167,7 @@ function flagValue(args: string[], name: string): string | undefined {
return i >= 0 ? args[i + 1] : undefined;
}
-/** Import every call file under `dir` once, into `sourceId` (default when unset). */
+/** Import every call file under `dir` (or the one call file `dir` names, as its folder would) once, into `sourceId` (default when unset). */
export async function runCallImport(engine: BrainEngine, dir: string, args: string[], opts: { sourceId?: string; json: boolean }): Promise<RunImportResult> {
const prefix = (flagValue(args, '--prefix') ?? DEFAULT_CALL_PREFIX).split('/').map(slugifySegment).filter(Boolean).join('/') || DEFAULT_CALL_PREFIX;
const sourceId = opts.sourceId ?? 'default';
@@ -167,37 +176,50 @@ export async function runCallImport(engine: BrainEngine, dir: string, args: stri
const putPage = operations.find(op => op.name === 'put_page')!;
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 files = listCallFiles(dir);
- const root = callRootId(dir);
- const priorSlugs = new Map((await engine.executeRaw<{ slug: string; file: string }>(
- `SELECT slug, frontmatter->'call_import'->>'file' AS file FROM pages
+ 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])).map(r => [r.file, r.slug]));
- const sameImport = (frontmatter: unknown, file: string): boolean => { const ci = callImportOf(frontmatter); return ci?.file === file && ci.root === root; };
+ [sourceId, `${prefix}/`, root]);
+ 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 ci = callImportOf(frontmatter);
+ return ci?.root === root && (typeof ci.path === 'string' ? ci.path === page.path : ci.file === page.file);
+ };
const results: CallFileResult[] = [];
const used = new Set<string>();
+ let uncovered = 0;
for (const path of files) {
- const rel = relative(dir, path);
+ const rel = relative(folder, path);
let page: CallPage;
+ if (!CALL_FILE_RE.test(path)) {
+ results.push({ file: redactCallPath(rel, patterns).file, slug: '', status: 'error', error: 'not a .txt or .md call transcript; pass one, or the folder that holds them' });
+ continue;
+ }
try {
- page = callPageFor(rel, readFileSync(path, 'utf8'), lstatSync(path).mtimeMs, prefix, patterns, root);
+ page = callPageFor(rel, readFileSync(path, 'utf8'), lstatSync(path).mtimeMs, prefix, patterns, root, createHash('sha256').update(`${folder}\u0000${rel}`).digest('hex').slice(0, 16));
} 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 priorSlug = priorSlugs.get(page.file);
+ const legacy = byFile.get(page.file);
+ const priorSlug = byPath.get(page.path!) ?? (legacy && !used.has(legacy) ? legacy : undefined);
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.file) && slug !== suffixed) {
+ if (!priorSlug && existing && !sameImport(existing.page.frontmatter, page) && 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.file)) results.push({ ...base, status: 'error', error: `${slug} already holds another page; rename the file to import it` });
+ if (!sameImport(existing.page.frontmatter, page)) 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;
}
@@ -205,22 +227,27 @@ export async function runCallImport(engine: BrainEngine, dir: string, args: stri
const receipt = await putPage.handler(ctx, { slug, content: page.content, request_id: randomUUID() }) as { persistence?: { git_state?: string } } | null;
results.push({ ...base, status: 'imported', ...(receipt?.persistence?.git_state ? { git_state: receipt.persistence.git_state } : {}) });
} catch (e) {
- results.push({ ...base, status: 'error', error: e instanceof Error ? e.message : String(e) });
+ const receipt = pendingReceiptOf(e);
+ if (receipt && !acceptPendingCovers(receipt)) uncovered++;
+ if (receipt) results.push({ ...base, status: 'pending', request_id: receipt.request_id, poll: pollCommand(receipt.request_id, (e as { fix?: { argv?: readonly string[] } }).fix, cliRenderContext().routing) });
+ else results.push({ ...base, status: 'error', error: e instanceof Error ? e.message : String(e) });
}
}
const count = (s: CallFileResult['status']) => results.filter(r => r.status === s).length;
const imported = count('imported');
const errors = count('error');
+ const pending = count('pending');
const redactions = results.filter(r => r.status === 'imported').reduce((n, r) => n + (r.redactions ?? 0), 0);
const failures = results.filter(r => r.status === 'error').map(r => ({ path: r.file, error: r.error ?? 'unknown error' }));
if (opts.json) {
await writeJsonDocument(JSON.stringify({
- status: errors > 0 ? 'partial' : 'success', mode: 'calls', source_id: sourceId, prefix, total_files: files.length,
- imported, unchanged: count('unchanged'), kept: count('kept'), errors, redactions, pages: results, failures,
+ status: errors > 0 ? 'partial' : pending > 0 ? 'pending' : 'success', mode: 'calls', source_id: sourceId, prefix, total_files: files.length,
+ imported, unchanged: count('unchanged'), kept: count('kept'), pending, errors, redactions, pages: results, failures,
}));
} else {
- console.log(`Call import into source ${sourceId} under ${prefix}/: ${imported} imported, ${count('unchanged')} unchanged, ${count('kept')} kept (changed since import, not overwritten), ${errors} error(s); ${redactions} credential(s) redacted.`);
- for (const r of results) console.log(` ${r.status.padEnd(9)} ${r.slug || '-'} <- ${r.file}${r.error ? ` (${r.error})` : ''}`);
+ console.log(`Call import into source ${sourceId} under ${prefix}/: ${imported} imported, ${count('unchanged')} unchanged, ${count('kept')} kept (changed since import, not overwritten), ${pending} pending (accepted, still being written), ${errors} error(s); ${redactions} credential(s) redacted.`);
+ for (const r of results) console.log(` ${r.status.padEnd(9)} ${r.slug || '-'} <- ${r.file}${r.error ? ` (${r.error})` : ''}${r.poll ? ` (still being written; check with ${r.poll} before importing again)` : ''}`);
}
+ if (!errors && pending && (!acceptPendingRequested(getCliOptions().acceptPending) || uncovered > 0)) setCliExitVerdict(PENDING_WRITE_EXIT_CODE);
return { imported, skipped: results.length - imported, errors, chunksCreated: 0, failures };
}
diff --git a/src/commands/storage.ts b/src/commands/storage.ts
index 719d32ae91..237d466c1c 100644
--- a/src/commands/storage.ts
+++ b/src/commands/storage.ts
@@ -564,6 +564,7 @@ async function runStorageAdopt(engine: BrainEngine, args: string[]): Promise<voi
for (const row of result.results) console.log(` ${row.outcome.padEnd(10)} ${row.slug}${row.card_id ? ` -> ${row.card_id}` : ''}`);
if (result.conflicts.length) console.log(`Conflicts (a different card with that id is on the shelf; nothing was overwritten): ${result.conflicts.join(', ')}`);
printOutcome(result);
+ if (result.index?.resume) console.log(`The shelf's sync checkpoint is behind the cards committed; index them with ${argvText(result.index.resume)}`);
if (result.finalize) console.log(`Originals are kept. Preview deleting them: ${argvText(result.finalize)}`);
return;
}
diff --git a/src/commands/sync-delegate.ts b/src/commands/sync-delegate.ts
index 63fd07a0dc..cc83b43742 100644
--- a/src/commands/sync-delegate.ts
+++ b/src/commands/sync-delegate.ts
@@ -75,6 +75,7 @@ import { SYNC_FLAGS, syncFlagsRouted, type SyncFlagSpec } from '../core/sync-fla
import type { BrainEngine } from '../core/engine.ts';
import type { ConsumerRow } from '../core/persistence/consumer-heartbeat.ts';
import type { SyncOpts, SyncResult } from './sync.ts';
+import { VERSION } from '../version.ts';
/** Poll cadence for sync_status while a delegated job runs. */
const POLL_MS = 1000;
@@ -237,7 +238,7 @@ export async function maybeDelegateSyncToServe(dataDir: string, args: string[]):
serr(
`[sync] a live \`gbrain serve\` (PID ${holder.pid}) holds this PGLite brain's ` +
`single-writer lock but exposes no sync IPC (older gbrain, \`serve --http\`, or ` +
- `GBRAIN_SERVE_SYNC_IPC=0). ` + remediation(holder.pid, 'Restart that serve on this gbrain version.'),
+ `GBRAIN_SERVE_SYNC_IPC=0). ` + remediation(holder.pid, 'If that serve runs an older gbrain, restart it on this version.'),
);
await setVerdict(1);
return true;
@@ -570,6 +571,7 @@ export async function maybeDelegateManagedSyncToServe(engine: BrainEngine, args:
}
if (!owner) return own('no_owner');
const pid = owner.pid;
+ const sameBuild = owner.version === VERSION;
if (owner.kind !== 'serve') {
return own('owner_not_serve', `[sync] the live write owner on this host is a ${owner.kind} process (PID ${pid}), which cannot host a delegated sync; this run uses its own consumer beside it.`);
}
@@ -585,7 +587,8 @@ export async function maybeDelegateManagedSyncToServe(engine: BrainEngine, args:
const { sock, secret } = deps.socket ? await deps.socket(sourceId)
: { sock: await hookResolveSocketForConfig(cfg, sourceId, { delegation: true }), secret: readIpcSecretForConfig(cfg) };
if (!sock || !existsSync(sock) || !secret) {
- return own('no_socket', fallbackLine(pid, 'the running gbrain serve exposes no sync IPC socket (older gbrain, or GBRAIN_SERVE_SYNC_IPC=0 on the serve)', false));
+ return own('no_socket', fallbackLine(pid, 'the running gbrain serve exposes no sync IPC socket (older gbrain, or GBRAIN_SERVE_SYNC_IPC=0 on the serve)', false,
+ sameBuild ? `That serve already runs this gbrain version (v${VERSION}), so restarting it changes nothing here: unset GBRAIN_SERVE_SYNC_IPC=0 on the serve, or read its log for why its sync IPC did not start.` : undefined));
}
// 5. The hand-off: this CLI's durable writer registration (the one its own consumer would run under).
dispatch.endSyncDispatchRead();
@@ -617,7 +620,8 @@ export async function maybeDelegateManagedSyncToServe(engine: BrainEngine, args:
let start = await requestSyncStart(sock, { secret, clientToken, options, registration });
if (start === IPC_UNAVAILABLE && await ownerAlive()) start = await requestSyncStart(sock, { secret, clientToken, options, registration });
if (start === IPC_UNAVAILABLE) {
- return own('no_socket', fallbackLine(pid, 'the running gbrain serve is not answering its IPC socket', true), true);
+ return own('no_socket', fallbackLine(pid, 'the running gbrain serve is not answering its IPC socket', true,
+ sameBuild ? `That serve already runs this gbrain version (v${VERSION}); it may be wedged.` : undefined), true);
}
if ('degraded' in (start as object)) {
return own('older_serve', fallbackLine(pid, 'the running gbrain serve predates serve-delegated managed sync', true), true);
diff --git a/src/core/cli-flag-registry.generated.ts b/src/core/cli-flag-registry.generated.ts
index 5fe082b3e1..772d01f9fc 100644
--- a/src/core/cli-flag-registry.generated.ts
+++ b/src/core/cli-flag-registry.generated.ts
@@ -134,7 +134,7 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {
'smoke-test': ['--brain', '--help', '--json', '--source'],
'sources': ['--abandon', '--abbrev-ref', '--abort', '--accept-pending', '--accept-suggested', '--access', '--account', '--add', '--admin-intent', '--adopt-columns', '--adopt-permissions', '--adopt-slug-path', '--after', '--all', '--all-new', '--allow-unverified-remote', '--allowed-operations', '--app-id', '--app-install', '--app-pem', '--apply', '--approval-out', '--approved', '--as', '--attest-actor', '--attest-ops', '--attest-read', '--attest-sources', '--audit', '--auto-additive', '--autostash', '--background', '--backups', '--batch-check', '--before', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--branch', '--break-lock', '--budget-usd-per-day', '--cached', '--calendar-id', '--category', '--channels', '--classify', '--cleanup-dead-local-locks', '--clear', '--client', '--clone-dir', '--code', '--config', '--confirm-destructive', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--contacts-dir', '--count', '--cursor', '--days', '--db-url', '--decisions', '--delegated-namespace', '--delegated-slug-prefixes', '--depth', '--detect', '--diff-filter', '--dir', '--disable', '--dry-run', '--enable', '--error-unmatch', '--exclude', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--expected-epoch', '--expected-incarnation', '--expected-state', '--explain', '--federated', '--federated-read', '--fetch-timeout-ms', '--ff-only', '--file', '--fix', '--follow', '--force', '--force-with-lease', '--format', '--from', '--from-git', '--full', '--future-days', '--get', '--get-all', '--git-dir', '--git-path', '--github-repo', '--grant-types', '--group-by', '--hard', '--heads', '--help', '--history-days', '--holds', '--http', '--id', '--if-version', '--include', '--include-warns', '--install', '--is-ancestor', '--is-inside-work-tree', '--json', '--keep', '--keep-checkout', '--keep-storage', '--kind', '--lanes', '--legacy-lock', '--limit', '--list-out', '--local', '--local-env-vars', '--lookback-days', '--loops-exclude-labels', '--manifest', '--max-cost-usd', '--max-requests', '--may-act-for', '--member', '--message', '--migrate-legacy', '--migration', '--min-trust', '--mode', '--name', '--name-only', '--no-accept-pending', '--no-assume-unchanged', '--no-autostash', '--no-cron', '--no-edit', '--no-embed', '--no-extract', '--no-federate', '--no-federated', '--no-follow-tags', '--no-harden', '--no-lanes', '--no-pull', '--no-renames', '--no-skip-worktree', '--no-tags', '--no-verify', '--not', '--only', '--operation', '--operations', '--origin', '--others', '--out', '--params', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--path-format', '--plan', '--porcelain', '--prefix', '--preview', '--private-pages', '--probe', '--profile', '--progress-interval', '--progress-json', '--provider', '--pull', '--push-only', '--push-remote', '--quiet', '--read-sources', '--readers', '--reads-unscoped', '--rebase', '--record', '--recurse-submodules', '--redirect-uri', '--refresh-operations', '--remote', '--remove', '--remove-backup', '--repair', '--replace', '--repos', '--request-id', '--require-clean', '--reset-checkpoint', '--reset-default', '--resolve', '--resume', '--retire', '--retry-failed', '--room', '--sample', '--scan-secrets', '--scan-timeout', '--scope', '--scopes', '--secret', '--self-transfer', '--services', '--set', '--set-upstream-to', '--shared-skills', '--short', '--show-toplevel', '--since', '--skip', '--slug-prefixes', '--source', '--source-id', '--source-ids', '--sources', '--stale', '--stat', '--state', '--status', '--stdin', '--surface', '--symbolic-full-name', '--sync-interval-min', '--takes-holders', '--timeout', '--timezone', '--timings', '--to', '--token', '--token-command', '--token-endpoint-auth-method', '--token-env', '--token-ttl', '--transcript', '--unindexed', '--uninstall', '--unset-all', '--unsettle', '--untracked-files', '--url', '--usage', '--verify', '--visibility', '--wait', '--wait-drain', '--warn-only', '--window', '--yes'],
'status': ['--abbrev-ref', '--acknowledge-managed', '--all', '--allow-empty', '--apply', '--brain', '--break-lock', '--cached', '--check', '--code', '--concurrency', '--confirm-destructive', '--count', '--cursor', '--deadline-ms', '--delete', '--detail', '--diff-filter', '--empty', '--enable', '--exclude', '--exclude-standard', '--fast', '--filters', '--fix', '--force-break-lock', '--format', '--full', '--full-history', '--funnel', '--hard-deadline', '--help', '--hold-state', '--include-gitignored', '--include-hidden', '--install', '--interval', '--is-ancestor', '--is-shallow-repository', '--json', '--lanes', '--limit', '--max-age', '--max-sources', '--mcp-only', '--missing-path', '--name-only', '--no-auto-embed', '--no-bulk', '--no-delegate', '--no-embed', '--no-extract', '--no-gpg-sign', '--no-hard-deadline', '--no-lanes', '--no-llm', '--no-pull', '--no-renames', '--no-repair', '--no-schema-pack', '--no-verify', '--no-walk', '--others', '--parallel', '--path', '--prefer', '--preview', '--priority', '--quiet', '--reason', '--redact-paths', '--repo', '--request-id', '--reset-checkpoint', '--retry-failed', '--retry-held', '--reverse', '--section', '--serial', '--show-toplevel', '--skip-failed', '--slug', '--slugs', '--source', '--source-id', '--src-subpath', '--stale', '--status', '--strategy', '--timeout', '--url', '--verify', '--watch', '--workers', '--working-tree', '--yes'],
- 'storage': ['--apply', '--brain', '--card', '--client', '--dir', '--drop-field', '--dry-run', '--expect', '--expected-revision', '--finalize', '--from-prefix', '--help', '--id', '--json', '--jsonl', '--only', '--out', '--patch', '--plan', '--push-remote', '--repo', '--restore-only', '--restored-to', '--scopes', '--source', '--status', '--store', '--to'],
+ 'storage': ['--apply', '--brain', '--card', '--client', '--dir', '--drop-field', '--dry-run', '--expect', '--expected-revision', '--finalize', '--from-prefix', '--help', '--id', '--json', '--jsonl', '--no-pull', '--only', '--out', '--patch', '--plan', '--push-remote', '--repo', '--restore-only', '--restored-to', '--scopes', '--source', '--status', '--store', '--to'],
'sweep': ['--accept-pending', '--apply', '--as', '--assign-corpus', '--background', '--batch-limit', '--brain', '--budget-ms', '--delete-brain', '--explain', '--follow', '--help', '--home', '--json', '--no-accept-pending', '--no-delegate', '--once', '--only', '--progress-interval', '--progress-json', '--quiet', '--retry-failed', '--room', '--session', '--source', '--source-id', '--stale', '--timeout', '--timings', '--wait'],
'sync': ['--abbrev-ref', '--absolute-git-dir', '--accept-pending', '--access-policy', '--account', '--acknowledge-managed', '--admin-intent', '--adopt-columns', '--adopt-permissions', '--after', '--alert', '--all', '--allow-empty', '--allow-outside-source-root', '--apply', '--apply-rewrites', '--as', '--assign-corpus', '--attest-read', '--audit', '--auto', '--background', '--batch', '--batch-check', '--batch-size', '--brain', '--branch', '--break-lock', '--budget-ms', '--by-mention', '--cached', '--calls', '--catch-up', '--check', '--check-only', '--class', '--clear', '--client', '--close', '--code', '--concurrency', '--config', '--confirm-destructive', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--contacts-dir', '--content-audit', '--continue', '--conversation', '--count', '--cursor', '--cwd', '--db-url', '--delete-brain', '--depth', '--detach', '--detail', '--diff-filter', '--dim', '--dir', '--drain', '--dry-run', '--embedding-dimensions', '--embedding-model', '--empty', '--enable', '--end-of-options', '--entity', '--exclude', '--exclude-standard', '--expect', '--expect-local', '--expect-upstream', '--expected-epoch', '--expected-revision', '--expected-state', '--explain', '--facts', '--fast', '--ff-only', '--filter', '--filters', '--first-parent', '--fix', '--follow', '--force', '--force-break-lock', '--force-rechunk', '--force-retry', '--force-schema', '--format', '--fresh', '--from', '--from-meetings', '--full', '--full-history', '--get', '--get-regexp', '--git-dir', '--git-path', '--grammar', '--group-by', '--hard-deadline', '--harness', '--held', '--help', '--hold-state', '--home', '--http', '--id', '--ignore-missing', '--images', '--include-ambiguous', '--include-flagged', '--include-frontmatter', '--include-gitignored', '--include-hidden', '--include-null-signature', '--include-repairs', '--index-audit', '--infer-dates', '--input', '--install', '--instructions-only', '--interval', '--is-ancestor', '--is-bare-repository', '--is-inside-work-tree', '--is-shallow-repository', '--json', '--keep-checkout', '--kind', '--lanes', '--lang', '--left-right', '--legacy-lock', '--limit', '--link-source', '--link-type', '--list', '--local', '--locks', '--log-noop', '--manifest', '--markdown', '--max-age', '--max-cost', '--max-cost-usd', '--max-jobs', '--max-rss', '--max-sources', '--max-usd', '--may-act-for', '--migrate-legacy', '--migrate-only', '--missing-path', '--multimodal', '--name', '--name-only', '--name-status', '--ner', '--no-accept-pending', '--no-auto-embed', '--no-autopilot-install', '--no-bulk', '--no-capture', '--no-delegate', '--no-embed', '--no-extensions', '--no-extract', '--no-gpg-sign', '--no-hard-deadline', '--no-instructions', '--no-lanes', '--no-llm', '--no-pull', '--no-renames', '--no-repair', '--no-schema-pack', '--no-verify', '--no-walk', '--once', '--only', '--operations', '--others', '--output', '--oversized', '--overwrite', '--pace', '--pace-max-concurrency', '--pack', '--page', '--parallel', '--params', '--path', '--path-format', '--pending', '--pglite', '--phase', '--pid-file', '--plan', '--porcelain', '--prefer', '--prefer-postgres', '--prefix', '--preview', '--priority', '--privacy-url', '--probe', '--probe-pglite', '--progress-interval', '--progress-json', '--project', '--providers', '--prune-orphans', '--pull', '--purge', '--push', '--push-only', '--query', '--question', '--queue', '--quiet', '--raw', '--raw-only', '--reader-mode', '--readers', '--reads-unscoped', '--reauth', '--rebase', '--rebuild', '--redact-paths', '--refresh', '--regenerate', '--relative', '--remediate', '--remediation-plan', '--remote', '--remove', '--remove-core', '--replace', '--repo', '--request-id', '--reset', '--reset-checkpoint', '--reset-default', '--restart-only', '--restore-only', '--resume', '--retry-failed', '--retry-held', '--retry-parked', '--reverse', '--room', '--scan-secrets', '--scope', '--scopes', '--self-transfer', '--serial', '--serves', '--session', '--short', '--show-current', '--show-toplevel', '--side', '--since', '--skill-loading', '--skills-dir', '--skills-index-only', '--skip', '--skip-failed', '--slot', '--slug', '--slugs', '--source', '--source-id', '--sources', '--src-subpath', '--staged', '--stale', '--stat', '--state', '--status', '--stdin', '--strategy', '--supabase', '--surface', '--symbol-kind', '--symbolic-full-name', '--takes-holders', '--target', '--target-score', '--terms-url', '--tier', '--timeout', '--timings', '--to', '--token', '--token-env', '--top-k', '--type', '--unindexed', '--unshallow', '--untracked-files', '--url', '--url-env', '--verbose', '--verify', '--version', '--wait', '--wakeshift', '--watch', '--where', '--window', '--workers', '--working-tree', '--workspace', '--yes'],
'takes': ['--about', '--accept', '--applied', '--apply', '--batch-size', '--before', '--brain', '--bucket-size', '--by', '--claim', '--date', '--dim', '--dir', '--domain', '--dry-run', '--embedding-dimensions', '--embedding-model', '--evidence', '--expected-revision', '--expired', '--failed', '--force', '--from-pages', '--group-by', '--help', '--holder', '--include-covered', '--json', '--kind', '--limit', '--max-pages', '--min-confidence', '--min-n', '--no-embed', '--no-embedding', '--offset', '--outcome', '--path', '--quality', '--reject', '--request-id', '--retry-failed', '--row', '--semantic', '--since', '--slug', '--sort', '--source', '--source-id', '--stale', '--state', '--status', '--supabase', '--to', '--unapplied', '--unit', '--until', '--value', '--verdict', '--weight', '--who', '--yes'],
diff --git a/src/core/context/retrieval-reflex.ts b/src/core/context/retrieval-reflex.ts
index 500e2e4d6b..1e4cc2ffbe 100644
--- a/src/core/context/retrieval-reflex.ts
+++ b/src/core/context/retrieval-reflex.ts
@@ -422,7 +422,7 @@ export async function resolveEntitiesToPointers(
AND ( lower(p.title) = ANY($2::text[])
OR p.slug = ANY($3::text[])
OR p.slug LIKE ANY($4::text[])
- OR (lower(p.title) LIKE ANY($5::text[]) AND p.type = 'person') )`,
+ OR (lower(p.title) LIKE ANY($5::text[]) AND p.type = 'person') ) ORDER BY p.id`,
[sourceIds, titlesLc, exactSlugs, slugSuffixes, surnamePatterns],
)
: await engine.executeRaw<PageRow>(
@@ -432,7 +432,7 @@ export async function resolveEntitiesToPointers(
AND p.source_id = ANY($1::text[])
AND ( lower(p.title) = ANY($2::text[])
OR p.slug = ANY($3::text[])
- OR p.slug LIKE ANY($4::text[]) )`,
+ OR p.slug LIKE ANY($4::text[]) ) ORDER BY p.id`,
[sourceIds, titlesLc, exactSlugs, slugSuffixes],
);
} catch {
diff --git a/src/core/cycle/extract-atoms.ts b/src/core/cycle/extract-atoms.ts
index bc044b205c..fd8ec2ab61 100644
--- a/src/core/cycle/extract-atoms.ts
+++ b/src/core/cycle/extract-atoms.ts
@@ -711,6 +711,7 @@ export async function runPhaseExtractAtoms(
const sourceId = opts.sourceId ?? 'default';
const guestSkip = await (await import('../guests/derived.ts')).guestSourceSkip(engine, 'extract_atoms', sourceId);
if (guestSkip) return { phase: 'extract_atoms', status: 'skipped', duration_ms: 0, summary: `extract_atoms: ${guestSkip.summary}`, details: guestSkip.details };
+ if (await (await import('../storage-manifest/door.ts')).isStorageManifestSource(engine, sourceId)) return { phase: 'extract_atoms', status: 'skipped', duration_ms: 0, summary: `extract_atoms: source ${sourceId} is the storage shelf, which holds archive records, not pages to extract atoms from`, details: { reason: 'storage_manifest_source' } };
const chat = opts._chat ?? gatewayChat;
const managed = await managedAtomSession(engine, sourceId, opts._managedRetry, opts.attempt?.writeWait, opts.signal);
// v0.41.2.1: loadConfigWithEngine() so the dream.* DB-plane merge from Phase 1 reaches this phase.
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index 08eaa7a4a1..01c2715fb0 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -853,7 +853,7 @@ export const CODES = {
storage_adopt_unverified: { class: 'caller', summary: "An adopted interim original has no card on the storage shelf that matches its record, so finalize deleted nothing.", why: 'Finalize soft-deletes an original only when its card holds everything the record mapped to, so no archive record is lost.', docs: 'docs/guides/write-refusals.md#storage-manifest-refusals', suggestion: 'Compare the original with its card (gbrain storage-get), fix the card or the record, then preview gbrain storage adopt --finalize again.' },
storage_card_exists: { class: 'caller', summary: "A storage card with this id is already on the storage shelf; nothing was written.", why: 'Registering never overwrites a card, so two archives cannot silently share one id; a change to an existing card names the revision it read.', docs: 'docs/guides/write-refusals.md#storage-manifest-refusals', suggestion: 'Change the card with gbrain storage-update <id> --expected-revision <revision from storage_get>, or register the new item under another id.' },
storage_manifest_missing: { class: 'consent', actor: 'user', summary: "This brain has no storage shelf to write to (or the storage source ID belongs to another source); nothing was written.", why: 'On a brain with a Git checkout the shelf is a hosted git-canonical repository, created only after the user previews it, and hosting needs managed persistence. A repo-less brain gets its database-only shelf on the first register.', docs: 'docs/guides/write-refusals.md#storage-manifest-refusals', suggestion: 'Preview gbrain storage init --dir <absolute path> --dry-run and apply the command it prints after the user agrees.' },
- storage_record_invalid: { class: 'caller', summary: "A storage card failed validation (a missing or malformed field, a command field, or a field gbrain stamps itself); nothing was written.", why: 'Every card must say where the item is, how big it is and how to restore it, and carries no commands, so a card is complete and safe to act on when it is found months later.', reasons: ['schema', 'command_field', 'stamped_field', 'not_json', 'not_object', 'too_large', 'id_change', 'no_record', 'duplicate_id', 'access_unpreservable', 'access_pending', 'labels', 'remote_written'], docs: 'docs/guides/write-refusals.md#storage-manifest-refusals', suggestion: 'Fix the field the message names and send the card again; gbrain storage-register --help lists the card fields. For an adopt blocked on access_pending or access_unpreservable, settle the access rules over the interim page (gbrain access status) or give it readers its folder rules also list, then preview again.' },
+ storage_record_invalid: { class: 'caller', summary: "A storage card failed validation (a missing or malformed field, a command field, or a field gbrain stamps itself); nothing was written.", why: 'Every card must say where the item is, how big it is and how to restore it, and carries no commands, so a card is complete and safe to act on when it is found months later.', reasons: ['schema', 'command_field', 'stamped_field', 'not_json', 'not_object', 'too_large', 'id_change', 'no_record', 'truncated', 'duplicate_id', 'access_unpreservable', 'access_pending', 'labels', 'remote_written'], docs: 'docs/guides/write-refusals.md#storage-manifest-refusals', suggestion: 'Fix the field the message names and send the card again; gbrain storage-register --help lists the card fields. For an adopt blocked on access_pending or access_unpreservable, settle the access rules over the interim page (gbrain access status) or give it readers its folder rules also list, then preview again. For truncated, move the ## Record section to the top of the interim page.' },
storage_record_secret: { class: 'caller', summary: "A storage card field looks like a secret or has a credential shape; nothing was written and the value is not echoed.", why: 'Cards are read by agents and copied into the stores; credentials stay in the environment of the skill that restores an item.', reasons: ['secret_scanner', 'env_assignment', 'credential_variable', 'url_userinfo', 'presigned_url', 'credential_key'], docs: 'docs/guides/write-refusals.md#storage-manifest-refusals', suggestion: 'Remove the secret, environment assignment, credential variable, URL password, signed-URL parameter or credential-named field from the card; a credential-named field that holds no credential can be renamed to end in _id, _ref or another suffix the rule passes.' },
storage_revision_conflict: { class: 'caller', summary: "A storage card changed since the revision the update named was read; nothing was written.", why: 'Updates bind to the revision they read, so two writers never silently overwrite each other; the refusal carries the current revision in detail.', docs: 'docs/guides/write-refusals.md#storage-manifest-refusals', suggestion: 'Read the card again with storage_get, apply the change to what it says now, and update once with its revision.' },
storage_source_managed: { class: 'caller', summary: "A page write targeted the storage shelf outside the storage verbs; nothing was written.", why: 'The storage source holds only validated cards, so put_page, remember and the other page writers are refused there.', docs: 'docs/guides/write-refusals.md#storage-manifest-refusals', suggestion: 'Register cards with gbrain storage-register and change them with gbrain storage-update.' },
diff --git a/src/core/harness/capabilities.ts b/src/core/harness/capabilities.ts
index 30f5219557..287cc25ad7 100644
--- a/src/core/harness/capabilities.ts
+++ b/src/core/harness/capabilities.ts
@@ -168,18 +168,21 @@ export type RescopeTarget = { kind: 'oauth_client'; id: string } | { kind: 'lega
/**
* The host commands that lift snapshot and client-pin blockers. They differ by
- * credential type: tokens refresh their snapshot (`--refresh-operations`
- * previews, `--add` widens by exactly the named operations); clients have no
- * refresh, so they take an explicit `--operations` list plus `--surface full`
- * when their stored surface blocks too. `operations` fills the list; null
- * leaves the `<OPERATIONS>` placeholder for the owner to choose. `all` is the
+ * credential type: tokens refresh their snapshot (`--add` widens by exactly
+ * the named operations); clients have no refresh, so they take an explicit
+ * `--operations` list plus `--surface full` when their stored surface blocks
+ * too. Each preview is the apply command with `--dry-run`, so it prints the
+ * grant before and after. `operations` fills the list; null leaves the
+ * `<OPERATIONS>` placeholder for the owner to choose, and a token's preview is
+ * then a bare `--refresh-operations` listing the candidates. `all` is the
* disclosed no-snapshot choice, never the default repair.
*/
export function grantRescopeArgvs(target: RescopeTarget, gaps: Pick<GrantGaps, 'snapshotExcluded' | 'pinExcluded'> & Partial<Pick<GrantGaps, 'approvalExcluded'>>, operations: string | null) {
const value = operations ?? '<OPERATIONS>';
if (target.kind === 'legacy_token') {
const base = ['gbrain', 'auth', 'rescope', ...target.flag];
- return { preview: [...base, '--refresh-operations'], apply: [...base, '--refresh-operations', '--add', value],
+ const apply = [...base, '--refresh-operations', '--add', value];
+ return { preview: operations === null ? [...base, '--refresh-operations'] : [...apply, '--dry-run'], apply,
all_operations: [...base, '--reset-default', 'operations', '--dry-run'] };
}
const base = ['gbrain', 'auth', 'rescope', '--client', target.id];
diff --git a/src/core/onboard/checks.ts b/src/core/onboard/checks.ts
index e4ddf8db6d..df33cba09d 100644
--- a/src/core/onboard/checks.ts
+++ b/src/core/onboard/checks.ts
@@ -664,6 +664,16 @@ export async function checkPackUpgradeAvailable(
}
}
+const PAGE_TYPE_PAIRS_SQL = `WITH RECURSIVE pairs AS (
+ (SELECT source_id, type FROM pages WHERE deleted_at IS NULL AND type IS NOT NULL ORDER BY source_id, type LIMIT 1)
+ UNION ALL
+ SELECT n.source_id, n.type FROM pairs, LATERAL (
+ SELECT p.source_id, p.type FROM pages p
+ WHERE p.deleted_at IS NULL AND p.type IS NOT NULL AND (p.source_id, p.type) > (pairs.source_id, pairs.type)
+ ORDER BY p.source_id, p.type LIMIT 1) n
+)
+SELECT source_id, type FROM pairs`;
+
/**
* type_proliferation (D16): pack-aware ratio. Warns when distinct typed
* pages exceed pack-declared types + 5; fails at declared × 2. No false
@@ -674,6 +684,9 @@ export async function checkPackUpgradeAvailable(
* DB config included); sources sharing a pack pool their labels, and an
* alias counts as its canonical type. A source whose pack does not resolve,
* or a failed query, is "not verified" (warn), never ok.
+ *
+ * The (source, type) pairs are read by a skip scan over idx_pages_source_type
+ * (v316): one index probe per distinct pair, never a pass over every page.
*/
export async function checkTypeProliferation(
engine: BrainEngine,
@@ -682,8 +695,7 @@ export async function checkTypeProliferation(
({ check: { name: 'type_proliferation', status, message }, remediations: [] });
let rows: Array<{ source_id: string; type: string }>;
try {
- rows = await engine.executeRaw<{ source_id: string; type: string }>(
- `SELECT DISTINCT source_id, type FROM pages WHERE deleted_at IS NULL AND type IS NOT NULL ORDER BY source_id, type`);
+ rows = await engine.executeRaw<{ source_id: string; type: string }>(PAGE_TYPE_PAIRS_SQL);
} catch (e) {
return result('warn', `type_proliferation not verified: the page type query failed (${(e as Error).message}).`);
}
diff --git a/src/core/persistence/atom-maintenance.ts b/src/core/persistence/atom-maintenance.ts
index 0e3965916d..b938ec2ab6 100644
--- a/src/core/persistence/atom-maintenance.ts
+++ b/src/core/persistence/atom-maintenance.ts
@@ -16,6 +16,7 @@ import { isConnectorSourceKind } from './connector-identity.ts';
import { preparePageMutation } from './page-prepare.ts';
import { assertPersistenceAccepting, waitForWrite, writeResponse } from './service.ts';
import { MaintenanceWriteWait } from './maintenance-wait.ts';
+import { STORAGE_ROLE } from '../storage-manifest/door.ts';
import type { PreparedMutation } from './coordinator.ts';
import type { WriteAuthority, WriteRequest } from './model.ts';
import type { WriteReceipt } from './types.ts';
@@ -907,7 +908,7 @@ export async function listHeldManagedAtoms(engine: BrainEngine, sourceIds?: stri
h.completed_keys->0->>'failure' AS failure, h.completed_keys->0->>'attempts' AS attempts, h.updated_at AS held_at
FROM op_checkpoints h JOIN sources s ON s.id=h.completed_keys->0->>'sourceId' AND s.incarnation::text=h.completed_keys->0->>'incarnation'
WHERE h.op='managed-atoms' AND h.completed_keys->0->>'held'='true'
- AND ($1::text[] IS NULL OR s.id=ANY($1::text[]))
+ AND ($1::text[] IS NULL OR s.id=ANY($1::text[])) AND s.config->>'role' IS DISTINCT FROM $2
AND (h.completed_keys->0->>'kind'<>'page' OR EXISTS (SELECT 1 FROM pages p WHERE p.source_id=s.id
AND p.id::text=h.completed_keys->0->>'pageId' AND p.content_hash=h.completed_keys->0->>'contentHash' AND p.deleted_at IS NULL))
AND NOT EXISTS (SELECT 1 FROM op_checkpoints ac WHERE ac.op='managed-atoms' AND ac.completed_keys->0->>'failure' IS NULL
@@ -916,7 +917,7 @@ export async function listHeldManagedAtoms(engine: BrainEngine, sourceIds?: stri
AND (CASE WHEN h.completed_keys->0->>'kind'='page' THEN ac.completed_keys->0->>'pageId'=h.completed_keys->0->>'pageId'
ELSE ac.completed_keys->0->>'locator'=h.completed_keys->0->>'locator' END)
AND ac.completed_keys->0->>'contentHash'=h.completed_keys->0->>'contentHash')
- ORDER BY h.completed_keys->0->>'requestId', h.updated_at`, [sourceIds ?? null]);
+ ORDER BY h.completed_keys->0->>'requestId', h.updated_at`, [sourceIds ?? null, STORAGE_ROLE]);
return rows.map(row => ({ ...row, attempts: Number(row.attempts), held_at: new Date(row.held_at).toISOString() }))
.sort((a, b) => a.source_id.localeCompare(b.source_id) || a.locator.localeCompare(b.locator));
}
diff --git a/src/core/persistence/root-registry.ts b/src/core/persistence/root-registry.ts
index 0cbe254a5b..4c606ad857 100644
--- a/src/core/persistence/root-registry.ts
+++ b/src/core/persistence/root-registry.ts
@@ -38,16 +38,17 @@ export function enclosingGitMetadata(root: string): string | null {
/**
* #7988: the git metadata directory of the checkout `root` belongs to: its own `.git`, or an enclosing checkout whose HEAD
* 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 an enclosing `.git` that is not a repository (#9430). A Git read
- * that fails for another reason keeps the enclosing checkout.
+ * 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.
*/
export function checkoutGitMetadata(root: string): string | null {
const own = gitMetadataDirectory(root);
- if (own) return own;
- const enclosing = enclosingGitMetadata(root);
+ if (own && isGitDirectory(own)) return own;
+ 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 || !isGitDirectory(enclosing)) return null; }
+ catch (error) { if ((error as { status?: unknown }).status === 1 || own || !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/src/core/repair/agent-session-facts.ts b/src/core/repair/agent-session-facts.ts
index 5a5eb135e0..982ba199e8 100644
--- a/src/core/repair/agent-session-facts.ts
+++ b/src/core/repair/agent-session-facts.ts
@@ -77,6 +77,8 @@ const OPENING_CHARS = 160;
const OPENING_MIN_CHARS = 40;
const OPENING_MIN_OTHERS = 3;
const HEAD_BYTES = 64 * 1024;
+/** #9390: what Claude Code writes into a user turn around a slash command (/clear, /model), never text the owner typed. */
+const HARNESS_BLOCKS = /<(local-command-caveat|command-name|command-message|command-args|local-command-stdout|local-command-stderr)>[\s\S]*?<\/\1>/g;
const NOTE_SEPARATOR = CONTEXT_NOTE_SEPARATOR;
const NOTE_MARK = 'speaker: agent ';
@@ -163,7 +165,7 @@ function readHead(path: string): string {
} finally { closeSync(fd); }
}
-/** The session's first user turn, normalized; null when no retained file holds one long enough to compare, 'unread' when its files could not be read. */
+/** The session's first user turn with owner text once harness blocks are dropped, normalized; null when no retained file holds one long enough to compare, 'unread' when its files could not be read. */
function openingKey(paths: string[], unreadable: string[]): string | null {
const ranked = paths.map(path => {
let mtime = Number.POSITIVE_INFINITY;
@@ -174,8 +176,9 @@ function openingKey(paths: string[], unreadable: string[]): string | null {
for (const { path, wb } of ranked) {
let head: string;
try { head = readHead(path); } catch { unreadable.push(path); unread = true; continue; }
- const turn = wb ? stripPastedContent(head).text : parseCorpusTurns(head).find(t => t.role === 'user')?.body;
- const key = turn?.replace(/\s+/g, ' ').trim().toLowerCase().slice(0, OPENING_CHARS);
+ const ownerText = (text: string) => text.replace(HARNESS_BLOCKS, ' ').replace(/\s+/g, ' ').trim();
+ const turn = wb ? ownerText(stripPastedContent(head).text) : parseCorpusTurns(head).filter(t => t.role === 'user').map(t => ownerText(t.body)).find(Boolean);
+ const key = turn?.toLowerCase().slice(0, OPENING_CHARS);
if (key) return key.length >= OPENING_MIN_CHARS ? key : null;
}
return unread ? 'unread' : null;
diff --git a/src/core/schema-migrations/latest.generated.ts b/src/core/schema-migrations/latest.generated.ts
index a910e3d1a5..cb8e941e5c 100644
--- a/src/core/schema-migrations/latest.generated.ts
+++ b/src/core/schema-migrations/latest.generated.ts
@@ -4,4 +4,4 @@
// The highest schema migration version (migrate.ts LATEST_VERSION), importable without
// loading the migrations themselves.
-export const LATEST_SCHEMA_VERSION = 315;
+export const LATEST_SCHEMA_VERSION = 316;
diff --git a/src/core/schema-migrations/registry.generated.ts b/src/core/schema-migrations/registry.generated.ts
index 03c68d24b1..c6761f0918 100644
--- a/src/core/schema-migrations/registry.generated.ts
+++ b/src/core/schema-migrations/registry.generated.ts
@@ -316,6 +316,7 @@ import { v312 } from './v312-guest-notes.ts';
import { v313 } from './v313-wake-events.ts';
import { v314 } from './v314-guest-notes-fail-closed.ts';
import { v315 } from './v315-facts-context-head-index.ts';
+import { v316 } from './v316-pages-source-type-index.ts';
// Array order is historical (see HISTORICAL_ARRAY_ORDER in the generator); the
// runner sorts by version before applying.
@@ -630,4 +631,5 @@ export const MIGRATIONS: Migration[] = [
v313,
v314,
v315,
+ v316,
];
diff --git a/src/core/schema-migrations/v316-pages-source-type-index.ts b/src/core/schema-migrations/v316-pages-source-type-index.ts
new file mode 100644
index 0000000000..ad2885fd26
--- /dev/null
+++ b/src/core/schema-migrations/v316-pages-source-type-index.ts
@@ -0,0 +1,21 @@
+import type { Migration } from './types.ts';
+import { buildIndexOnline, migrationNotice } from './helpers.ts';
+
+// Applied by src/core/migrate.ts on the next initSchema(); see docs/ENGINES.md
+// ("Canonical schema sources") for when schema.sql or a TS fragment also changes.
+//
+// Doctor `type_proliferation` reads the distinct (source, type) pairs of live typed pages. With only single-column
+// indexes on source_id and type, every way to read those pairs visits every page row, which took over 20 s on a
+// large brain. idx_pages_source_type lets the check walk the pairs with one index probe each (a skip scan,
+// checkTypeProliferation). Postgres builds it CONCURRENTLY outside the migration transaction (a handler); PGLite
+// builds inline. Nothing is rewritten. No schema.sql mirror, like v315.
+export const v316: Migration = {
+ version: 316,
+ name: 'pages_source_type_index',
+ idempotent: true,
+ sql: '',
+ handler: async (engine) => {
+ await buildIndexOnline(engine, 316, { name: 'idx_pages_source_type', table: 'pages',
+ sql: 'CREATE INDEX IF NOT EXISTS idx_pages_source_type ON pages (source_id, type) WHERE deleted_at IS NULL' }, { notice: migrationNotice });
+ },
+};
diff --git a/src/core/storage-manifest/adopt.ts b/src/core/storage-manifest/adopt.ts
index 083b33d2e2..f9e27f8f1e 100644
--- a/src/core/storage-manifest/adopt.ts
+++ b/src/core/storage-manifest/adopt.ts
@@ -35,7 +35,7 @@ import { hasReaders, normalizeReaders } from '../access/principals.ts';
import { canonicalJson } from '../remediation-step.ts';
import { readShelfCards } from './find.ts';
import { accessLabels, CARD_KEYS, cardContent, cardDigest, credentialShape, holdsCredential, isCommandKey, parseCardInput, STAMPED_KEYS, STORED_OBJECT_TYPE, type AccessLabels, type CardInput } from './schema.ts';
-import { shelfWritable, STORAGE_SOURCE_ID } from './source.ts';
+import { shelfWritable, storageSourceState, STORAGE_SOURCE_ID } from './source.ts';
export const ADOPT_DEFAULT_PREFIX = 'storage-manifest/';
export const ADOPT_DEFAULT_SOURCE = 'default';
@@ -62,15 +62,24 @@ export function pendingWrite(item: string, error: unknown): PendingWrite | null
return receipt ? { item, request_id: receipt.request_id, state: receipt.state, poll: ['gbrain', 'write-request', receipt.request_id] } : null;
}
+/** The receipt id of a committed write's response, to report beside the record it wrote. */
+function receiptId(response: unknown): { request_id?: string } {
+ const id = (response as { request_id?: unknown } | null)?.request_id;
+ return typeof id === 'string' ? { request_id: id } : {};
+}
+
/** What a run changed: an accepted pending write counts as a change, and as unfinished. */
export function sideEffects(wrote: boolean, unfinished: boolean): SideEffects {
return !wrote ? 'none' : unfinished ? 'partial' : 'complete';
}
export interface AdoptApplyResult {
action: 'adopt'; dry_run: false; source_id: string; prefix: string; plan_hash: string; side_effects: SideEffects;
- results: Array<{ slug: string; card_id: string | null; outcome: 'registered' | 'retagged' | 'skipped' | 'conflict' }>;
- conflicts: string[]; failure?: StepFailure; pending?: PendingWrite[]; rerun?: string[]; finalize?: string[];
+ results: Array<{ slug: string; card_id: string | null; outcome: 'registered' | 'retagged' | 'skipped' | 'conflict'; request_id?: string }>;
+ counts: { adopted: number; skipped: number; refused: number; pending: number };
+ conflicts: string[]; failure?: StepFailure; pending?: PendingWrite[]; rerun?: string[]; finalize?: string[]; index?: ShelfIndex;
}
+/** On a hosted shelf, whether the sync checkpoint reached the cards the run committed; `resume` indexes them when it did not. */
+export interface ShelfIndex { source_id: string; status: 'indexed' | 'behind'; last_commit: string | null; resume?: string[] }
export interface FinalizeEntry { slug: string; card_id: string | null; state: 'delete' | 'deleted' | 'unverified' | 'not_adopted'; other_sections?: string[]; unread_tail?: boolean; content?: string }
export interface FinalizePlan { action: 'finalize'; dry_run: true; source_id: string; prefix: string; entries: FinalizeEntry[]; plan_hash: string; summary: string[]; apply?: string[] }
export interface FinalizeApplyResult {
@@ -190,9 +199,10 @@ function originalLabels(row: InterimAccess, frontmatter: Record<string, unknown>
}
/** Map one interim page onto a card. Pure: reads nothing beyond the row. */
-export function mapInterimPage(row: Pick<InterimRow, 'slug' | 'title' | 'frontmatter' | 'body'> & InterimAccess, prefix: string): Pick<AdoptEntry, 'card' | 'labels' | 'refused' | 'problem'> {
+export function mapInterimPage(row: Pick<InterimRow, 'slug' | 'title' | 'frontmatter' | 'body'> & Partial<Pick<InterimRow, 'long_body'>> & InterimAccess, prefix: string): Pick<AdoptEntry, 'card' | 'labels' | 'refused' | 'problem'> {
if (row.write_channel?.startsWith('mcp:')) return { card: null, labels: null, refused: [], problem: invalidRecord('remote_written', `the page was last written by a remote client (${row.write_channel}); adopt takes only records written on this machine or by sync`) };
const text = recordJson(row.body ?? '');
+ if (text === null && (row.long_body || (row.body?.length ?? 0) >= BOUNDED_PREFIX_BYTES)) return { card: null, labels: null, refused: [], problem: invalidRecord('truncated', 'the page is longer than the 64 KiB adopt reads and no complete json block under a ## Record heading is in that part, so the record is cut off or past it; move the ## Record section to the top of the page') };
if (text === null) return { card: null, labels: null, refused: [], problem: invalidRecord('no_record', 'the page has no json block under a ## Record heading in its first 64 KiB') };
let record: unknown;
try { record = JSON.parse(text); } catch { return { card: null, labels: null, refused: [], problem: invalidRecord('not_json', 'the ## Record block is not valid JSON') }; }
@@ -312,11 +322,11 @@ export async function applyAdopt(ctx: OperationContext, opts: AdoptOptions & { e
if (entry.state === 'conflict' || entry.state === 'adopted') { results.push({ slug: entry.slug, card_id: entry.card_id, outcome: entry.state === 'conflict' ? 'conflict' : 'skipped' }); continue; }
try {
if (entry.state === 'register') {
- await registerCard(ctx, entry.card!, 'adopt', undefined, entry.labels!);
- results.push({ slug: entry.slug, card_id: entry.card_id, outcome: 'registered' });
+ const registered = await registerCard(ctx, entry.card!, 'adopt', undefined, entry.labels!);
+ results.push({ slug: entry.slug, card_id: entry.card_id, outcome: 'registered', ...receiptId(registered.write) });
}
- await submitPageMutation(ctx, { operation: 'add_tag', params: { slug: entry.slug, tag: ADOPTED_TAG, source_id: opts.sourceId } });
- results.push({ slug: entry.slug, card_id: entry.card_id, outcome: 'retagged' });
+ const tagged = await submitPageMutation(ctx, { operation: 'add_tag', params: { slug: entry.slug, tag: ADOPTED_TAG, source_id: opts.sourceId } });
+ results.push({ slug: entry.slug, card_id: entry.card_id, outcome: 'retagged', ...receiptId(tagged) });
} catch (error) {
const held = pendingWrite(entry.slug, error);
if (held) { pending.push(held); continue; }
@@ -326,13 +336,42 @@ export async function applyAdopt(ctx: OperationContext, opts: AdoptOptions & { e
}
}
const wrote = pending.length > 0 || results.some((r) => r.outcome === 'registered' || r.outcome === 'retagged');
+ const index = results.some((r) => r.outcome === 'registered') && (await storageSourceState(ctx.engine)).hosted ? await indexShelfCommits(ctx.engine) : undefined;
return { action: 'adopt', dry_run: false, source_id: opts.sourceId, prefix: opts.prefix, plan_hash: plan.plan_hash,
side_effects: sideEffects(wrote, !!failure || pending.length > 0), results,
+ counts: { adopted: new Set(results.filter((r) => r.outcome === 'retagged').map((r) => r.slug)).size, skipped: results.filter((r) => r.outcome === 'skipped').length,
+ refused: results.filter((r) => r.outcome === 'conflict').length + (failure ? 1 : 0), pending: pending.length },
conflicts: results.filter((r) => r.outcome === 'conflict').map((r) => r.slug),
- ...(failure ? { failure } : {}), ...(pending.length ? { pending } : {}),
+ ...(failure ? { failure } : {}), ...(pending.length ? { pending } : {}), ...(index ? { index } : {}),
...(failure || pending.length ? { rerun } : { finalize: [...adoptArgv(opts), '--finalize'] }) };
}
+/**
+ * Index the commits a run made on a hosted (git-canonical) shelf, as the strict pass of a git conversion does after its own
+ * commits: the managed --no-pull sync under the shelf's drain lease, which reads committed blobs only, so Git stays the
+ * parent. The cycle skips the shelf, so without this its checkpoint stayed behind until someone ran that sync by hand.
+ */
+async function indexShelfCommits(engine: OperationContext['engine']): Promise<ShelfIndex> {
+ const [{ withDrainLease, leaseHeldResult, readDrainHolder }, { drainManagedSync }, { withSyncTail }, { LockUnavailableError, syncLockId }, { withHumanLogsToStderr }] = await Promise.all([
+ import('../persistence/sync-lease.ts'), import('../persistence/sync-drain.ts'), import('../persistence/sync-tail.ts'), import('../db-lock.ts'), import('../console-prefix.ts')]);
+ const opts = { sourceId: STORAGE_SOURCE_ID, noPull: true };
+ let status: string;
+ try {
+ status = await withHumanLogsToStderr(async () => {
+ const drained = await withDrainLease(engine, STORAGE_SOURCE_ID, { holder: { kind: 'cli', id: null }, remote: false },
+ (signal) => drainManagedSync(engine, signal ? { ...opts, signal } : opts, false));
+ return (await withSyncTail(engine, STORAGE_SOURCE_ID, drained)).status;
+ });
+ } catch (error) {
+ if (!(error instanceof LockUnavailableError) || error.lockId !== syncLockId(STORAGE_SOURCE_ID)) throw error;
+ status = leaseHeldResult(STORAGE_SOURCE_ID, await readDrainHolder(engine, STORAGE_SOURCE_ID).catch(() => null)).status;
+ }
+ const [row] = await engine.executeRaw<{ last_commit: string | null }>('SELECT last_commit FROM sources WHERE id = $1', [STORAGE_SOURCE_ID]);
+ const indexed = ['up_to_date', 'synced', 'first_sync'].includes(status);
+ return { source_id: STORAGE_SOURCE_ID, status: indexed ? 'indexed' : 'behind', last_commit: row?.last_commit ?? null,
+ ...(indexed ? {} : { resume: ['gbrain', 'sync', '--source', STORAGE_SOURCE_ID, '--no-pull'] }) };
+}
+
/** Preview finalize: the tagged originals to soft-delete. Writes nothing. */
export async function previewFinalize(ctx: OperationContext, opts: AdoptOptions): Promise<FinalizePlan> {
await assertInterimSource(ctx, opts);
diff --git a/src/core/storage-manifest/find.ts b/src/core/storage-manifest/find.ts
index 1ad0dfd237..4df16b4183 100644
--- a/src/core/storage-manifest/find.ts
+++ b/src/core/storage-manifest/find.ts
@@ -1,5 +1,5 @@
/**
- * Ranked lookup on the storage shelf (GST-1943), keyless: exact id, exact alias (page_aliases), then the words of the
+ * Ranked lookup on the storage shelf (GST-1943), keyless: exact id, exact alias (page_aliases), exact title, then the words of the
* phrase over each card's title, aliases and body, then pg_trgm similarity on title and aliases for the closest cards
* when nothing matches. One statement; the shelf is small (hundreds to thousands of cards).
*/
@@ -16,7 +16,7 @@ const CLOSEST_FLOOR = 0.1;
export interface CardFilters { store?: string; status?: string; onSourceMachine?: boolean }
export interface CardRow { id: string; title: string; status: string | null; kind: string | null; stores: string[]; original_path: string | null; on_source_machine: boolean | null; updated_at: string }
-export interface FindHit extends CardRow { match: 'id' | 'alias' | 'words'; matched_terms: number; similarity: number }
+export interface FindHit extends CardRow { match: 'id' | 'alias' | 'title' | 'words'; matched_terms: number; similarity: number }
export interface FindResult { query: string; terms: string[]; hits: FindHit[]; not_found: boolean; closest: Array<CardRow & { similarity: number }> }
export function queryTerms(query: string): string[] {
@@ -44,10 +44,11 @@ export async function findCards(engine: BrainEngine, query: string, opts: { limi
const params: unknown[] = [STORAGE_SOURCE_ID, STORED_OBJECT_TYPE, query.trim().toLowerCase(), normalizeAlias(query), terms];
const policy = pageReadFilter('p', opts.policy, params, true);
const filters = cardFilterSql('p', opts.filters, params);
- const rows = await engine.executeRaw<CardRow & { exact_id: boolean; exact_alias: boolean; matched: number; rank: number; similarity: number }>(`
+ const rows = await engine.executeRaw<CardRow & { exact_id: boolean; exact_alias: boolean; exact_title: boolean; matched: number; rank: number; similarity: number }>(`
SELECT ${CARD_COLUMNS},
p.slug = $3 AS exact_id,
EXISTS (SELECT 1 FROM page_aliases a WHERE a.source_id = p.source_id AND a.slug = p.slug AND a.alias_norm = $4) AS exact_alias,
+ lower(btrim(p.title)) = $3 AS exact_title,
(SELECT count(*) FROM unnest($5::text[]) t WHERE d.doc @@ plainto_tsquery('simple', t))::int AS matched,
GREATEST(word_similarity($3, lower(p.title)),
COALESCE((SELECT max(word_similarity($3, a.alias_norm)) FROM page_aliases a WHERE a.source_id = p.source_id AND a.slug = p.slug), 0))::float8 AS similarity
@@ -55,13 +56,13 @@ export async function findCards(engine: BrainEngine, query: string, opts: { limi
CROSS JOIN LATERAL (SELECT to_tsvector('simple', p.title || ' ' || COALESCE((SELECT string_agg(a.alias_norm, ' ') FROM page_aliases a WHERE a.source_id = p.source_id AND a.slug = p.slug), '')
|| ' ' || p.slug || ' ' || ${boundedBodyPrefixSql('p')}) AS doc) d
WHERE p.source_id = $1 AND p.type = $2 AND ${policy}${filters}
- ORDER BY exact_id DESC, exact_alias DESC, matched DESC, similarity DESC, p.slug
+ ORDER BY exact_id DESC, exact_alias DESC, exact_title DESC, matched DESC, similarity DESC, p.slug
LIMIT 500`, params);
const needed = Math.max(1, Math.ceil(terms.length / 2));
- const strip = ({ exact_id: _e, exact_alias: _a, matched: _m, rank: _r, similarity: _s, ...card }: (typeof rows)[number]): CardRow => ({ ...card, stores: card.stores ?? [] });
+ const strip = ({ exact_id: _e, exact_alias: _a, exact_title: _t, matched: _m, rank: _r, similarity: _s, ...card }: (typeof rows)[number]): CardRow => ({ ...card, stores: card.stores ?? [] });
const hits: FindHit[] = [];
for (const row of rows) {
- const match = row.exact_id ? 'id' : row.exact_alias ? 'alias' : terms.length && row.matched >= needed ? 'words' : null;
+ const match = row.exact_id ? 'id' : row.exact_alias ? 'alias' : row.exact_title ? 'title' : terms.length && row.matched >= needed ? 'words' : null;
if (match) hits.push({ ...strip(row), match, matched_terms: Number(row.matched), similarity: Number(row.similarity) });
}
const shown = hits.slice(0, opts.limit);
diff --git a/src/core/storage-manifest/schema.ts b/src/core/storage-manifest/schema.ts
index 255e725160..e3bdefe5c3 100644
--- a/src/core/storage-manifest/schema.ts
+++ b/src/core/storage-manifest/schema.ts
@@ -32,7 +32,7 @@ const count = z.number().int().nonnegative();
const LocationSchema = z.object({
store: z.enum(STORES),
bucket: text(200).nullish(),
- path: text(2000).min(1),
+ path: text(2000).min(1, 'is empty; for an item at the root of its bucket or repository, write "/"'),
tool: z.enum(TOOLS),
repository: text(2000).nullish(),
snapshot: text(200).nullish(),
diff --git a/test/checkout-git-metadata-invalid-enclosing-9430.test.ts b/test/checkout-git-metadata-invalid-enclosing-9430.test.ts
index 749b6d6ccc..76b7ef0ce8 100644
--- a/test/checkout-git-metadata-invalid-enclosing-9430.test.ts
+++ b/test/checkout-git-metadata-invalid-enclosing-9430.test.ts
@@ -6,7 +6,10 @@
* `$HOME` (connector clones included) refused `writer_coordinator_required`.
* An enclosing `.git` that is not a repository is no checkout: the root is
* marked in its own directory, and a marker an older release left there reads
- * as the stale enclosing marker the refusal already names (#7988).
+ * as the stale enclosing marker the refusal already names (#7988). The same
+ * holds for the root's own `.git`: one that is not a repository (an empty
+ * directory, or a gitdir file pointing nowhere, where recording the root
+ * failed with ENOENT) is no checkout either.
*/
import { afterAll, expect, test } from 'bun:test';
import { execFileSync } from 'node:child_process';
@@ -46,6 +49,55 @@ for (const kind of ['empty-dir', 'dangling-gitdir-file'] as const) {
});
}
+for (const kind of ['empty-dir', 'dangling-gitdir-file'] as const) {
+ test(`a root's own .git that is not a repository (${kind}) is not its checkout`, async () => {
+ const base = mkdtempSync(join(tmpdir(), 'gbrain-9430-own-'));
+ bases.push(base);
+ const root = join(base, 'source-a');
+ mkdirSync(root);
+ if (kind === 'empty-dir') mkdirSync(join(root, '.git'));
+ else writeFileSync(join(root, '.git'), `gitdir: ${join(base, 'missing', '.git')}\n`);
+ expect(checkoutGitMetadata(root)).toBeNull();
+ await withEnv({ GBRAIN_HOME: join(base, 'gbrain-home') }, () => {
+ recordManagedRoots(randomUUID(), [{ local_path: root, source_id: 'source-a' }]);
+ });
+ expect(existsSync(join(root, '.gbrain-managed'))).toBe(true);
+ expect(managedRootMarkerFor(join(root, 'mail.md'))?.root).toBe(root);
+ });
+}
+
+test('control: a tracked directory holding a stray empty .git still belongs to the repository that tracks it', () => {
+ const base = mkdtempSync(join(tmpdir(), 'gbrain-9430-stray-'));
+ bases.push(base);
+ const wiki = join(base, 'repo', 'wiki');
+ mkdirSync(wiki, { recursive: true });
+ writeFileSync(join(wiki, 'alice-example.md'), 'Notes.\n');
+ const git = (...args: string[]) => execFileSync('git', ['-C', join(base, 'repo'), ...args], { stdio: 'ignore' });
+ git('init', '-q'); git('add', '.');
+ git('-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-qm', 'wiki');
+ mkdirSync(join(wiki, '.git'));
+ expect(checkoutGitMetadata(wiki)).toBe(join(base, 'repo', '.git'));
+});
+
+test('an untracked folder whose own .git file points nowhere does not take the real repository around it', async () => {
+ const base = mkdtempSync(join(tmpdir(), 'gbrain-9430-dangling-in-repo-'));
+ bases.push(base);
+ const repo = join(base, 'repo'), root = join(repo, 'clones', 'source-a');
+ mkdirSync(root, { recursive: true });
+ writeFileSync(join(repo, 'alice-example.md'), 'Notes.\n');
+ const git = (...args: string[]) => execFileSync('git', ['-C', repo, ...args], { stdio: 'ignore' });
+ git('init', '-q'); git('add', 'alice-example.md');
+ git('-c', 'user.name=Example', '-c', '[email protected]', 'commit', '-qm', 'notes');
+ writeFileSync(join(root, '.git'), `gitdir: ${join(base, 'missing', '.git')}\n`);
+ expect(checkoutGitMetadata(root)).toBeNull();
+ await withEnv({ GBRAIN_HOME: join(base, 'gbrain-home') }, () => {
+ recordManagedRoots(randomUUID(), [{ local_path: root, source_id: 'source-a' }]);
+ });
+ expect(existsSync(join(repo, '.git', 'gbrain-managed.json'))).toBe(false);
+ expect(managedRootMarkerFor(join(repo, 'notes', 'todo.md'))).toBeNull();
+ expect(managedRootMarkerFor(join(root, 'mail.md'))?.root).toBe(root);
+});
+
test('a marker an older release wrote into an invalid enclosing .git reads as a stale enclosing marker', async () => {
const h = home('empty-dir');
const marker = join(h.dir, '.git', 'gbrain-managed.json');
diff --git a/test/doctor-grant-by-name-ops.test.ts b/test/doctor-grant-by-name-ops.test.ts
new file mode 100644
index 0000000000..25550e890d
--- /dev/null
+++ b/test/doctor-grant-by-name-ops.test.ts
@@ -0,0 +1,116 @@
+/**
+ * `grant_new_ops_available` with membership operations missing: the default
+ * fix and its preview never add an operation gbrain says the owner approves by
+ * name (join_brain, sync_brain_skills, leave_brain). The check lists those and
+ * carries a separate by-name command, never the fix. The count and the commands
+ * agree: missing = added by the default command + listed as by-name. Real CLI
+ * subprocesses against a sandboxed PGLite brain, for an OAuth client and a
+ * legacy token whose scopes allow the membership operations.
+ * Regression it catches: a doctor fix that pre-fills by-name operations, which
+ * turns the owner's by-name approval into one keystroke.
+ */
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createEngine } from '../src/core/engine-factory.ts';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';
+import { sqlQueryForEngine } from '../src/core/sql-query.ts';
+import { readClientGrant, resolveGrantProfile } from '../src/core/grants/service.ts';
+import { grantFromTokenRow } from '../src/core/grants/model.ts';
+import { mintLegacyToken } from '../src/core/token-mint.ts';
+import { checkGrantNewOps } from '../src/commands/doctor/checks/grant-new-ops.ts';
+import { requiresExplicitApproval } from '../src/core/ops/execution-prerequisites.ts';
+import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
+
+const CLI = join(resolve(import.meta.dir, '..'), 'src', 'cli.ts');
+const cfg = { engine: 'pglite' } as any;
+let root: string, home: string, db: string;
+
+function env(): Record<string, string> {
+ const out: Record<string, string> = {};
+ for (const [key, value] of Object.entries(process.env)) if (value !== undefined) out[key] = value;
+ for (const key of ['DATABASE_URL', 'GBRAIN_DATABASE_URL', 'GBRAIN_BRAIN_ID', 'GBRAIN_SOURCE', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'VOYAGE_API_KEY']) delete out[key];
+ return { ...out, HOME: home, GBRAIN_HOME: home, GBRAIN_SELF_UPGRADE_MODE: 'off', GBRAIN_SKIP_STARTUP_HOOKS: '1', GBRAIN_SWEEP: '0' };
+}
+
+async function cli(argv: string[]) {
+ expect(argv[0]).toBe('gbrain');
+ const proc = Bun.spawn(['bun', 'run', CLI, ...argv.slice(1)], { cwd: root, env: env(), stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' });
+ const [stdout, stderr, exitCode] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+ return { stdout, stderr, exitCode };
+}
+
+async function withBrain<T>(run: (engine: BrainEngine) => Promise<T>): Promise<T> {
+ const config = { engine: 'pglite' as const, database_path: db };
+ const engine = await createEngine(config);
+ await engine.connect(config);
+ try { return await run(engine); } finally { await disposePersistenceConsumer(engine); await engine.disconnect(); }
+}
+
+type Finding = { kind: string; id: string; name: string; preview_argv: string[] | null; argv: string[] | null; by_name_operations: string[]; by_name_argv: string[] | null;
+ excluded_operations: { operation_snapshot: string[] } };
+const check = () => withBrain(engine => checkGrantNewOps(engine, { cfg }));
+const findings = async () => ((await check()).details?.grants ?? []) as Finding[];
+const snapshotOf = (f: Finding) => withBrain(async engine => f.kind === 'oauth_client'
+ ? (await readClientGrant(engine, f.id)).allowedOperations!
+ : grantFromTokenRow((await engine.executeRaw<Record<string, unknown>>('SELECT * FROM access_tokens WHERE id = $1::uuid', [f.id]))[0]).allowedOperations!);
+
+const ok = (kind: string, r: { exitCode: number; stderr: string }) =>
+ expect({ kind, exitCode: r.exitCode, stderr: r.exitCode ? r.stderr : '' }).toEqual({ kind, exitCode: 0, stderr: '' });
+
+beforeAll(async () => {
+ root = mkdtempSync(join(tmpdir(), 'gb-grant-by-name-'));
+ home = join(root, 'home');
+ db = join(root, 'db');
+ mkdirSync(join(home, '.gbrain'), { recursive: true });
+ writeFileSync(join(home, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite', database_path: db }));
+ await withBrain(async engine => {
+ await engine.initSchema();
+ const profile = resolveGrantProfile({ profile: 'memory-writer', sourceId: 'default' });
+ const snapshot = profile.allowedOperations!.filter(op => op !== 'put_pages');
+ const provider = new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
+ await provider.registerClientManual('member-example', ['client_credentials'], 'read write skills_member_self', [], 'default', undefined, undefined, undefined,
+ { ...profile, scopes: ['read', 'write', 'skills_member_self'], allowedOperations: snapshot });
+ await mintLegacyToken(engine, { name: 'member-token-example', scopes: ['read', 'write', 'skills_member_self'], takesHolders: ['world'], allowedOperations: snapshot });
+ });
+}, 120_000);
+
+afterAll(() => { rmSync(root, { recursive: true, force: true }); });
+
+describe('grant_new_ops_available leaves by-name operations out of the default fix', () => {
+ test('missing = added by the default command + listed as by-name; the by-name command is separate and never the fix', async () => {
+ const result = await check();
+ const found = (result.details?.grants ?? []) as Finding[];
+ expect(found.map(f => f.kind).sort()).toEqual(['legacy_token', 'oauth_client']);
+ const fix = result.fix as { argv: string[]; preview_argv: string[]; user_message: string };
+ for (const f of found) {
+ const missing = f.excluded_operations.operation_snapshot;
+ expect(missing).toContain('put_pages');
+ const before = await snapshotOf(f);
+ const preview = await cli(f.preview_argv!);
+ ok(f.kind, preview);
+ expect(await snapshotOf(f)).toEqual(before);
+ ok(f.kind, await cli(f.argv!));
+ const afterDefault = await snapshotOf(f);
+ const added = afterDefault.filter(op => !before.includes(op));
+ expect(added.filter(requiresExplicitApproval)).toEqual([]);
+ expect([...f.by_name_operations].sort()).toEqual(missing.filter(requiresExplicitApproval).sort());
+ expect([...f.by_name_operations].sort()).toEqual(['join_brain', 'leave_brain', 'sync_brain_skills']);
+ expect(fix.argv).not.toEqual(f.by_name_argv);
+ expect(result.message).toContain(`${f.by_name_operations.length} of the missing operations need the owner's approval by name (${f.by_name_operations.join(', ')})`);
+ expect(preview.stdout).toContain(`Operations: ${before.join(', ')} -> ${afterDefault.join(', ')}`);
+ expect([...added, ...f.by_name_operations].sort()).toEqual([...missing].sort());
+ }
+ expect(fix.user_message).toContain('need the owner\'s approval by name');
+
+ const remaining = await check();
+ const left = (remaining.details?.grants ?? []) as Finding[];
+ expect(left.map(f => ({ kind: f.kind, argv: f.argv, missing: [...f.excluded_operations.operation_snapshot].sort() })).sort((a, b) => a.kind.localeCompare(b.kind)))
+ .toEqual(['legacy_token', 'oauth_client'].map(kind => ({ kind, argv: null, missing: ['join_brain', 'leave_brain', 'sync_brain_skills'] })));
+ expect(remaining.fix).toBeUndefined();
+ for (const f of left) ok(f.kind, await cli(f.by_name_argv!));
+ expect((await check()).status).toBe('ok');
+ }, 240_000);
+});
diff --git a/test/doctor-grant-new-ops-fix.test.ts b/test/doctor-grant-new-ops-fix.test.ts
new file mode 100644
index 0000000000..10ebf4ce36
--- /dev/null
+++ b/test/doctor-grant-new-ops-fix.test.ts
@@ -0,0 +1,104 @@
+/**
+ * `grant_new_ops_available` fix commands, run as real CLI subprocesses against
+ * a sandboxed PGLite brain: the preview the check prints shows the operation
+ * list before and after and changes nothing, and the apply command grants every
+ * operation the check counted, for an OAuth client and a legacy token, so the
+ * check is ok afterwards. Nothing outside the grant's scopes is added.
+ * Regression it catches: a fix that adds one operation (`put_pages`) while the
+ * check counts many, leaving remote clients unable to reach new tools.
+ */
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createEngine } from '../src/core/engine-factory.ts';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';
+import { sqlQueryForEngine } from '../src/core/sql-query.ts';
+import { readClientGrant, resolveGrantProfile } from '../src/core/grants/service.ts';
+import { grantFromTokenRow } from '../src/core/grants/model.ts';
+import { mintLegacyToken } from '../src/core/token-mint.ts';
+import { checkGrantNewOps } from '../src/commands/doctor/checks/grant-new-ops.ts';
+import { disposePersistenceConsumer } from '../src/core/persistence/service.ts';
+
+const CLI = join(resolve(import.meta.dir, '..'), 'src', 'cli.ts');
+const cfg = { engine: 'pglite' } as any;
+let root: string, home: string, db: string;
+
+function env(): Record<string, string> {
+ const out: Record<string, string> = {};
+ for (const [key, value] of Object.entries(process.env)) if (value !== undefined) out[key] = value;
+ for (const key of ['DATABASE_URL', 'GBRAIN_DATABASE_URL', 'GBRAIN_BRAIN_ID', 'GBRAIN_SOURCE', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'VOYAGE_API_KEY']) delete out[key];
+ return { ...out, HOME: home, GBRAIN_HOME: home, GBRAIN_SELF_UPGRADE_MODE: 'off', GBRAIN_SKIP_STARTUP_HOOKS: '1', GBRAIN_SWEEP: '0' };
+}
+
+async function cli(argv: string[]) {
+ expect(argv[0]).toBe('gbrain');
+ const proc = Bun.spawn(['bun', 'run', CLI, ...argv.slice(1)], { cwd: root, env: env(), stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' });
+ const [stdout, stderr, exitCode] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+ return { stdout, stderr, exitCode };
+}
+
+async function withBrain<T>(run: (engine: BrainEngine) => Promise<T>): Promise<T> {
+ const config = { engine: 'pglite' as const, database_path: db };
+ const engine = await createEngine(config);
+ await engine.connect(config);
+ try { return await run(engine); } finally { await disposePersistenceConsumer(engine); await engine.disconnect(); }
+}
+
+type Finding = { kind: string; id: string; name: string; preview_argv: string[]; argv: string[]; excluded_operations: { operation_snapshot: string[] } };
+const check = () => withBrain(engine => checkGrantNewOps(engine, { cfg }));
+const findings = async () => ((await check()).details?.grants ?? []) as Finding[];
+const snapshotOf = (f: Finding) => withBrain(async engine => f.kind === 'oauth_client'
+ ? (await readClientGrant(engine, f.id)).allowedOperations!
+ : grantFromTokenRow((await engine.executeRaw<Record<string, unknown>>('SELECT * FROM access_tokens WHERE id = $1::uuid', [f.id]))[0]).allowedOperations!);
+
+/** A writer granted before several operations existed: its snapshot lacks three it may call. */
+const writerOps = () => resolveGrantProfile({ profile: 'memory-writer', sourceId: 'default' }).allowedOperations!;
+let dropped: string[] = [];
+
+beforeAll(async () => {
+ root = mkdtempSync(join(tmpdir(), 'gb-grant-fix-'));
+ home = join(root, 'home');
+ db = join(root, 'db');
+ mkdirSync(join(home, '.gbrain'), { recursive: true });
+ writeFileSync(join(home, '.gbrain', 'config.json'), JSON.stringify({ engine: 'pglite', database_path: db }));
+ await withBrain(async engine => {
+ await engine.initSchema();
+ const all = writerOps();
+ dropped = ['put_pages', ...all.filter(op => op !== 'put_pages' && op !== 'get_page').slice(0, 2)];
+ const snapshot = all.filter(op => !dropped.includes(op));
+ const provider = new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
+ const profile = resolveGrantProfile({ profile: 'memory-writer', sourceId: 'default' });
+ await provider.registerClientManual('writer-example', ['client_credentials'], 'read write', [], 'default', undefined, undefined, undefined,
+ { ...profile, surface: 'starter', surfaceSetBy: 'operator', allowedOperations: snapshot });
+ await mintLegacyToken(engine, { name: 'token-example', scopes: ['read', 'write'], takesHolders: ['world'], allowedOperations: snapshot });
+ });
+}, 120_000);
+
+afterAll(() => { rmSync(root, { recursive: true, force: true }); });
+
+describe('grant_new_ops_available fix commands', () => {
+ test('the preview shows the before and after operation lists and changes nothing; the apply grants every counted operation', async () => {
+ const found = await findings();
+ expect(found.map(f => f.kind).sort()).toEqual(['legacy_token', 'oauth_client']);
+ for (const f of found) {
+ const counted = f.excluded_operations.operation_snapshot;
+ expect(counted).toContain('put_pages');
+ expect(counted.length).toBeGreaterThan(1);
+ const before = await snapshotOf(f);
+
+ const preview = await cli(f.preview_argv);
+ expect({ kind: f.kind, exitCode: preview.exitCode, stderr: preview.exitCode ? preview.stderr : '' }).toEqual({ kind: f.kind, exitCode: 0, stderr: '' });
+ expect(await snapshotOf(f)).toEqual(before);
+
+ const applied = await cli(f.argv);
+ expect({ kind: f.kind, exitCode: applied.exitCode, stderr: applied.exitCode ? applied.stderr : '' }).toEqual({ kind: f.kind, exitCode: 0, stderr: '' });
+ const after = await snapshotOf(f);
+ expect([...after].sort()).toEqual([...new Set([...before, ...counted])].sort());
+ expect(preview.stdout).toContain(`Operations: ${before.join(', ')} -> ${after.join(', ')}`);
+ }
+ const recheck = await check();
+ expect({ status: recheck.status, grants: (recheck.details?.grants as unknown[]).length }).toEqual({ status: 'ok', grants: 0 });
+ }, 240_000);
+});
diff --git a/test/doctor-grant-new-ops.test.ts b/test/doctor-grant-new-ops.test.ts
index c7a3aa0f87..9cde908dc4 100644
--- a/test/doctor-grant-new-ops.test.ts
+++ b/test/doctor-grant-new-ops.test.ts
@@ -101,7 +101,7 @@ describe('grant_new_ops_available', () => {
const found = grants((await checkGrantNewOps(engine, { cfg })).details);
const token = found.find(f => f.kind === 'legacy_token')!;
const client = found.find(f => f.id === clientId)!;
- expect(token.preview_argv).toEqual(['gbrain', 'auth', 'rescope', '--token', 'old-token', '--refresh-operations']);
+ expect(token.preview_argv).toEqual(['gbrain', 'auth', 'rescope', '--token', 'old-token', '--refresh-operations', '--add', 'put_pages', '--dry-run']);
expect(token.argv).toEqual(['gbrain', 'auth', 'rescope', '--token', 'old-token', '--refresh-operations', '--add', 'put_pages']);
expect(token.argv).not.toContain('--client');
expect(client.argv).not.toContain('--refresh-operations');
@@ -117,7 +117,7 @@ describe('grant_new_ops_available', () => {
const first = await mintLegacyToken(engine, { name: 'twin-token', scopes: ['read', 'write'], takesHolders: ['world'], allowedOperations: ops });
await mintLegacyToken(engine, { name: 'twin-token', scopes: ['read', 'write'], takesHolders: ['world'], allowedOperations: ops });
const found = grants((await checkGrantNewOps(engine, { cfg })).details);
- expect(found.find(f => f.id === first.id)!.preview_argv).toEqual(['gbrain', 'auth', 'rescope', '--id', first.id, '--refresh-operations']);
+ expect(found.find(f => f.id === first.id)!.preview_argv).toEqual(['gbrain', 'auth', 'rescope', '--id', first.id, '--refresh-operations', '--add', 'put_pages', '--dry-run']);
});
test('the fix asks the user, previews first, and never defaults to --operations all', async () => {
diff --git a/test/doctor-type-proliferation-plan.test.ts b/test/doctor-type-proliferation-plan.test.ts
new file mode 100644
index 0000000000..c5feb26533
--- /dev/null
+++ b/test/doctor-type-proliferation-plan.test.ts
@@ -0,0 +1,59 @@
+/**
+ * Doctor `type_proliferation` reads the distinct (source, type) pairs of live
+ * typed pages without visiting every page.
+ *
+ * Protects: the check's one read of `pages` reaches it only through index
+ * probes on idx_pages_source_type (v316), never a sequential scan, and returns
+ * exactly the pairs `SELECT DISTINCT source_id, type` returns (deleted pages
+ * left out).
+ * Fails when: the read goes back to `SELECT DISTINCT source_id, type FROM
+ * pages`, which scans every page row (over 20 s on a large brain), or the
+ * index is missing.
+ * Seams: executeRaw is wrapped to record the statements the check runs;
+ * in-memory PGLite with planner statistics.
+ */
+import { afterAll, beforeAll, expect, test } from 'bun:test';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { checkTypeProliferation } from '../src/core/onboard/checks.ts';
+import { emptyHome, withEnv } from './helpers/with-env.ts';
+
+let engine: PGLiteEngine;
+
+beforeAll(async () => {
+ engine = new PGLiteEngine();
+ await engine.connect({});
+ await engine.initSchema();
+ await engine.executeRaw(`INSERT INTO sources (id, name) VALUES ('source-a', 'source-a') ON CONFLICT (id) DO NOTHING`);
+ await engine.executeRaw(`INSERT INTO pages (source_id, slug, type, title)
+ SELECT 'default', 'notes/n-' || g, (ARRAY['note', 'meeting', 'person', 'company', 'project', 'idea'])[1 + g % 6], 'n' FROM generate_series(1, 3000) g`);
+ await engine.executeRaw(`INSERT INTO pages (source_id, slug, type, title)
+ SELECT 'source-a', 'notes/a-' || g, (ARRAY['note', 'transcript', 'call'])[1 + g % 3], 'a' FROM generate_series(1, 600) g`);
+ await engine.executeRaw(`INSERT INTO pages (source_id, slug, type, title, deleted_at) VALUES ('source-a', 'notes/gone', 'deleted-only', 'gone', now())`);
+ await engine.executeRaw('ANALYZE pages');
+}, 120_000);
+afterAll(async () => { await engine.disconnect(); });
+
+type PlanNode = { 'Node Type': string; 'Relation Name'?: string; 'Index Name'?: string; Plans?: PlanNode[] };
+const walk = (node: PlanNode, out: PlanNode[] = []): PlanNode[] => { out.push(node); for (const child of node.Plans ?? []) walk(child, out); return out; };
+
+test('the check reads pages once, through index probes only, and gets every live typed pair', async () => {
+ const statements: string[] = [];
+ const raw = engine.executeRaw.bind(engine);
+ engine.executeRaw = ((sql: string, params?: unknown[]) => { statements.push(sql); return raw(sql, params); }) as typeof engine.executeRaw;
+ try {
+ await withEnv({ GBRAIN_HOME: emptyHome(), GBRAIN_SCHEMA_PACK: undefined }, () => checkTypeProliferation(engine));
+ } finally { engine.executeRaw = raw; }
+
+ const pageReads = statements.filter(sql => /\bpages\b/i.test(sql) && /^\s*(WITH|SELECT)/i.test(sql));
+ expect(pageReads.length).toBe(1);
+ const [{ 'QUERY PLAN': plan }] = await engine.executeRaw<{ 'QUERY PLAN': Array<{ Plan: PlanNode }> }>(`EXPLAIN (FORMAT JSON) ${pageReads[0]}`);
+ const scans = walk(plan[0].Plan).filter(node => node['Relation Name'] === 'pages');
+ expect(scans.length).toBeGreaterThan(0);
+ for (const scan of scans) expect({ node: scan['Node Type'], index: scan['Index Name'] }).toEqual({ node: expect.stringMatching(/^Index (Only )?Scan$/), index: 'idx_pages_source_type' });
+
+ const pairs = await engine.executeRaw<{ source_id: string; type: string }>(pageReads[0]);
+ const distinct = await engine.executeRaw<{ source_id: string; type: string }>(
+ 'SELECT DISTINCT source_id, type FROM pages WHERE deleted_at IS NULL AND type IS NOT NULL ORDER BY source_id, type');
+ expect(pairs).toEqual(distinct);
+ expect(pairs.length).toBe(9);
+});
diff --git a/test/extract-atoms-storage-shelf.test.ts b/test/extract-atoms-storage-shelf.test.ts
new file mode 100644
index 0000000000..d42ffa9af9
--- /dev/null
+++ b/test/extract-atoms-storage-shelf.test.ts
@@ -0,0 +1,77 @@
+/**
+ * The storage shelf holds archive records, not pages to extract atoms from. A page of an extractable type on the shelf
+ * (a stray file a hosted shelf's sync imported, say) must not be extracted: every atom write into the shelf is refused,
+ * so the drain struck it until doctor extract_atoms_held_failed named the shelf. The phase skips the shelf, and the
+ * check never names it.
+ */
+import { afterAll, beforeAll, beforeEach, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { __setChatTransportForTests, configureGateway, resetGateway, type ChatResult } from '../src/core/ai/gateway.ts';
+import { runExtractAtomsDrainForSource } from '../src/core/cycle/extract-atoms-drain.ts';
+import { disposePersistenceConsumer, stopPersistenceConsumer } from '../src/core/persistence/service.ts';
+import { ensureStorageSource } from '../src/core/storage-manifest/source.ts';
+import { atomHeldFailedEntry } from '../src/commands/doctor/checks/atom-holds.ts';
+import type { DoctorContext } from '../src/commands/doctor/context.ts';
+import type { Check } from '../src/commands/doctor.ts';
+import { resetPgliteState } from './helpers/reset-pglite.ts';
+import { withEnv } from './helpers/with-env.ts';
+
+let engine: PGLiteEngine;
+beforeAll(async () => {
+ configureGateway({ embedding_model: 'openai:text-embedding-3-large', embedding_dimensions: 1536, env: {} });
+ engine = new PGLiteEngine();
+ await engine.connect({});
+ await engine.initSchema();
+}, 60_000);
+beforeEach(async () => { await stopPersistenceConsumer(engine); await resetPgliteState(engine); await engine.unsetConfig('sync.repo_path'); });
+afterAll(async () => { __setChatTransportForTests(null); await engine.disconnect(); resetGateway(); });
+
+const REPLY = JSON.stringify([{ title: 'Measured progress', atom_type: 'insight', body: 'Measure progress against clear exit criteria.' }]);
+
+test('the atom drain never extracts from the storage shelf, and doctor extract_atoms_held_failed never names it', async () => {
+ const home = mkdtempSync(join(tmpdir(), 'gbrain-atom-shelf-'));
+ let calls = 0;
+ __setChatTransportForTests(async (): Promise<ChatResult> => {
+ calls++;
+ return { text: REPLY, blocks: [], stopReason: 'end', usage: { input_tokens: 10, output_tokens: 10, cache_read_tokens: 0, cache_creation_tokens: 0 },
+ model: 'anthropic:claude-haiku-4-5', providerId: 'anthropic' };
+ });
+ try {
+ await withEnv({ GBRAIN_HOME: home, ANTHROPIC_API_KEY: '[redacted]' }, async () => {
+ await ensureStorageSource(engine);
+ await engine.putPage('notes/2026-01-01-shelf-readme', { type: 'source', title: 'Shelf readme', compiled_truth: 'A careful archive record. '.repeat(40) }, { sourceId: 'storage' });
+ await engine.executeRaw('UPDATE persistence_brain SET enabled=true WHERE singleton=1');
+ await engine.setConfig('models.dream.extract_atoms', 'anthropic:claude-haiku-4-5');
+ const result = await runExtractAtomsDrainForSource(engine, { sourceId: 'storage', windowSeconds: 120, maxBatches: 10 });
+ await disposePersistenceConsumer(engine);
+ expect(calls).toBe(0);
+ expect(result.failure_count).toBe(0);
+ const doctor = (await atomHeldFailedEntry.run({ engine } as unknown as DoctorContext) as Check[])[0]!;
+ expect(doctor.status).toBe('ok');
+ expect(await engine.executeRaw("SELECT slug FROM pages WHERE source_id='storage' AND type='atom'")).toEqual([]);
+ });
+ } finally {
+ __setChatTransportForTests(null);
+ await disposePersistenceConsumer(engine);
+ await stopPersistenceConsumer(engine);
+ await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
+ rmSync(home, { recursive: true, force: true });
+ }
+}, 120_000);
+
+test('a held atom origin an earlier release left on the storage shelf is not named; one on an ordinary source still is', async () => {
+ await ensureStorageSource(engine);
+ const seed = async (sourceId: string, requestId: string) => {
+ const [{ incarnation }] = await engine.executeRaw<{ incarnation: string }>('SELECT incarnation::text AS incarnation FROM sources WHERE id=$1', [sourceId]);
+ await engine.executeRaw("INSERT INTO op_checkpoints(op, fingerprint, completed_keys) VALUES ('managed-atoms', $1, $2::text::jsonb)", [`fixture-${sourceId}`,
+ JSON.stringify([{ sourceId, incarnation, kind: 'transcript', locator: 'transcripts/2026-01-01.txt', requestId, failure: 'revision_conflict', attempts: 3, held: true, contentHash: 'c'.repeat(64) }])]);
+ };
+ await seed('storage', '00000000-0000-4000-8000-000000000001');
+ await seed('default', '00000000-0000-4000-8000-000000000002');
+ const doctor = (await atomHeldFailedEntry.run({ engine } as unknown as DoctorContext) as Check[])[0]!;
+ expect(doctor.status).toBe('warn');
+ expect((doctor.details?.items as Array<{ source_id: string }>).map((item) => item.source_id)).toEqual(['default']);
+}, 60_000);
diff --git a/test/fixtures/goldens/catalog/pglite-engine-init-default.json b/test/fixtures/goldens/catalog/pglite-engine-init-default.json
index cd801ccf9e..c19734fd4d 100644
--- a/test/fixtures/goldens/catalog/pglite-engine-init-default.json
+++ b/test/fixtures/goldens/catalog/pglite-engine-init-default.json
@@ -1470,6 +1470,7 @@
"idx_pages_slug_trgm": "CREATE INDEX idx_pages_slug_trgm ON public.pages USING gin (slug gin_trgm_ops)",
"idx_pages_source_id": "CREATE INDEX idx_pages_source_id ON public.pages USING btree (source_id)",
"idx_pages_source_title_lower": "CREATE INDEX idx_pages_source_title_lower ON public.pages USING btree (source_id, lower(title))",
+ "idx_pages_source_type": "CREATE INDEX idx_pages_source_type ON public.pages USING btree (source_id, type) WHERE (deleted_at IS NULL)",
"idx_pages_title_search": "CREATE INDEX idx_pages_title_search ON public.pages USING gin (ts_filter(search_vector, '{a}'::\"char\"[]))",
"idx_pages_trgm": "CREATE INDEX idx_pages_trgm ON public.pages USING gin (title gin_trgm_ops)",
"idx_pages_type": "CREATE INDEX idx_pages_type ON public.pages USING btree (type)",
diff --git a/test/fixtures/goldens/catalog/pglite-engine-init-fts-portuguese.json b/test/fixtures/goldens/catalog/pglite-engine-init-fts-portuguese.json
index ed49abea9f..ab9f75c6c7 100644
--- a/test/fixtures/goldens/catalog/pglite-engine-init-fts-portuguese.json
+++ b/test/fixtures/goldens/catalog/pglite-engine-init-fts-portuguese.json
@@ -1470,6 +1470,7 @@
"idx_pages_slug_trgm": "CREATE INDEX idx_pages_slug_trgm ON public.pages USING gin (slug gin_trgm_ops)",
"idx_pages_source_id": "CREATE INDEX idx_pages_source_id ON public.pages USING btree (source_id)",
"idx_pages_source_title_lower": "CREATE INDEX idx_pages_source_title_lower ON public.pages USING btree (source_id, lower(title))",
+ "idx_pages_source_type": "CREATE INDEX idx_pages_source_type ON public.pages USING btree (source_id, type) WHERE (deleted_at IS NULL)",
"idx_pages_title_search": "CREATE INDEX idx_pages_title_search ON public.pages USING gin (ts_filter(search_vector, '{a}'::\"char\"[]))",
"idx_pages_trgm": "CREATE INDEX idx_pages_trgm ON public.pages USING gin (title gin_trgm_ops)",
"idx_pages_type": "CREATE INDEX idx_pages_type ON public.pages USING btree (type)",
diff --git a/test/fixtures/goldens/catalog/pglite-engine-init-high-dims.json b/test/fixtures/goldens/catalog/pglite-engine-init-high-dims.json
index ec128e16ef..0a71f909f7 100644
--- a/test/fixtures/goldens/catalog/pglite-engine-init-high-dims.json
+++ b/test/fixtures/goldens/catalog/pglite-engine-init-high-dims.json
@@ -1468,6 +1468,7 @@
"idx_pages_slug_trgm": "CREATE INDEX idx_pages_slug_trgm ON public.pages USING gin (slug gin_trgm_ops)",
"idx_pages_source_id": "CREATE INDEX idx_pages_source_id ON public.pages USING btree (source_id)",
"idx_pages_source_title_lower": "CREATE INDEX idx_pages_source_title_lower ON public.pages USING btree (source_id, lower(title))",
+ "idx_pages_source_type": "CREATE INDEX idx_pages_source_type ON public.pages USING btree (source_id, type) WHERE (deleted_at IS NULL)",
"idx_pages_title_search": "CREATE INDEX idx_pages_title_search ON public.pages USING gin (ts_filter(search_vector, '{a}'::\"char\"[]))",
"idx_pages_trgm": "CREATE INDEX idx_pages_trgm ON public.pages USING gin (title gin_trgm_ops)",
"idx_pages_type": "CREATE INDEX idx_pages_type ON public.pages USING btree (type)",
diff --git a/test/fixtures/goldens/catalog/postgres-engine-init-default.json b/test/fixtures/goldens/catalog/postgres-engine-init-default.json
index 124d233fb3..93651da54d 100644
--- a/test/fixtures/goldens/catalog/postgres-engine-init-default.json
+++ b/test/fixtures/goldens/catalog/postgres-engine-init-default.json
@@ -1473,6 +1473,7 @@
"idx_pages_slug_trgm": "CREATE INDEX idx_pages_slug_trgm ON public.pages USING gin (slug gin_trgm_ops)",
"idx_pages_source_id": "CREATE INDEX idx_pages_source_id ON public.pages USING btree (source_id)",
"idx_pages_source_title_lower": "CREATE INDEX idx_pages_source_title_lower ON public.pages USING btree (source_id, lower(title))",
+ "idx_pages_source_type": "CREATE INDEX idx_pages_source_type ON public.pages USING btree (source_id, type) WHERE (deleted_at IS NULL)",
"idx_pages_title_search": "CREATE INDEX idx_pages_title_search ON public.pages USING gin (ts_filter(search_vector, '{a}'::\"char\"[]))",
"idx_pages_trgm": "CREATE INDEX idx_pages_trgm ON public.pages USING gin (title gin_trgm_ops)",
"idx_pages_type": "CREATE INDEX idx_pages_type ON public.pages USING btree (type)",
diff --git a/test/fixtures/goldens/catalog/postgres-engine-init-fts-portuguese.json b/test/fixtures/goldens/catalog/postgres-engine-init-fts-portuguese.json
index c8dfbe02aa..515ed181fc 100644
--- a/test/fixtures/goldens/catalog/postgres-engine-init-fts-portuguese.json
+++ b/test/fixtures/goldens/catalog/postgres-engine-init-fts-portuguese.json
@@ -1473,6 +1473,7 @@
"idx_pages_slug_trgm": "CREATE INDEX idx_pages_slug_trgm ON public.pages USING gin (slug gin_trgm_ops)",
"idx_pages_source_id": "CREATE INDEX idx_pages_source_id ON public.pages USING btree (source_id)",
"idx_pages_source_title_lower": "CREATE INDEX idx_pages_source_title_lower ON public.pages USING btree (source_id, lower(title))",
+ "idx_pages_source_type": "CREATE INDEX idx_pages_source_type ON public.pages USING btree (source_id, type) WHERE (deleted_at IS NULL)",
"idx_pages_title_search": "CREATE INDEX idx_pages_title_search ON public.pages USING gin (ts_filter(search_vector, '{a}'::\"char\"[]))",
"idx_pages_trgm": "CREATE INDEX idx_pages_trgm ON public.pages USING gin (title gin_trgm_ops)",
"idx_pages_type": "CREATE INDEX idx_pages_type ON public.pages USING btree (type)",
diff --git a/test/fixtures/goldens/catalog/postgres-engine-init-high-dims.json b/test/fixtures/goldens/catalog/postgres-engine-init-high-dims.json
index b2a1913b49..b63c09106a 100644
--- a/test/fixtures/goldens/catalog/postgres-engine-init-high-dims.json
+++ b/test/fixtures/goldens/catalog/postgres-engine-init-high-dims.json
@@ -1471,6 +1471,7 @@
"idx_pages_slug_trgm": "CREATE INDEX idx_pages_slug_trgm ON public.pages USING gin (slug gin_trgm_ops)",
"idx_pages_source_id": "CREATE INDEX idx_pages_source_id ON public.pages USING btree (source_id)",
"idx_pages_source_title_lower": "CREATE INDEX idx_pages_source_title_lower ON public.pages USING btree (source_id, lower(title))",
+ "idx_pages_source_type": "CREATE INDEX idx_pages_source_type ON public.pages USING btree (source_id, type) WHERE (deleted_at IS NULL)",
"idx_pages_title_search": "CREATE INDEX idx_pages_title_search ON public.pages USING gin (ts_filter(search_vector, '{a}'::\"char\"[]))",
"idx_pages_trgm": "CREATE INDEX idx_pages_trgm ON public.pages USING gin (title gin_trgm_ops)",
"idx_pages_type": "CREATE INDEX idx_pages_type ON public.pages USING btree (type)",
diff --git a/test/fixtures/goldens/migrations/records.json b/test/fixtures/goldens/migrations/records.json
index 3457054ffa..60445a18a9 100644
--- a/test/fixtures/goldens/migrations/records.json
+++ b/test/fixtures/goldens/migrations/records.json
@@ -1,6 +1,6 @@
{
"golden": {
- "count": 310,
+ "count": 311,
"gaps": [
17,
18,
@@ -100,7 +100,7 @@
"widenIdentityIndex": "86a6176bd7637d964dbc1d3cd3b1bdfa3ca0161e1ee248c37d7380a1471282e6",
"withSchemaLockTimeout": "95605bd3004955e11e936c7a4aa6889319b401098abf9db18ef3e48da2c3fc59"
},
- "latest": 315,
+ "latest": 316,
"records": [
{
"handler": {
@@ -5118,6 +5118,34 @@
"transaction": "absent",
"verify": "absent",
"version": 315
+ },
+ {
+ "handler": {
+ "form": "arrow",
+ "helpers": [
+ "PLANNER_REPAIR_TABLES",
+ "analyzeAfterIndexBuild",
+ "analyzeDeferred",
+ "analyzeYieldingToVacuum",
+ "buildIndexOnline",
+ "dropInvalidConcurrentIndex",
+ "lockTableForAnalyze",
+ "migrationNotice",
+ "quietMigrationNotices",
+ "tableRows"
+ ],
+ "sha256": "20e9ffa5e24ca7daff6ac6d7117a56854b18dd1c836161bb7dd37df29bb4b2b6"
+ },
+ "idempotent": true,
+ "name": "pages_source_type_index",
+ "sql": {
+ "length": 0,
+ "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+ },
+ "sqlFor": "absent",
+ "transaction": "absent",
+ "verify": "absent",
+ "version": 316
}
],
"versions": [
@@ -5430,7 +5458,8 @@
312,
313,
314,
- 315
+ 315,
+ 316
]
},
"normalizer": "migrations-record-v1"
diff --git a/test/fixtures/goldens/pglite-upgrade-replay/catalog-after-boot.json b/test/fixtures/goldens/pglite-upgrade-replay/catalog-after-boot.json
index 724a3e91e2..70c823596c 100644
--- a/test/fixtures/goldens/pglite-upgrade-replay/catalog-after-boot.json
+++ b/test/fixtures/goldens/pglite-upgrade-replay/catalog-after-boot.json
@@ -1470,6 +1470,7 @@
"idx_pages_slug_trgm": "CREATE INDEX idx_pages_slug_trgm ON public.pages USING gin (slug gin_trgm_ops)",
"idx_pages_source_id": "CREATE INDEX idx_pages_source_id ON public.pages USING btree (source_id)",
"idx_pages_source_title_lower": "CREATE INDEX idx_pages_source_title_lower ON public.pages USING btree (source_id, lower(title))",
+ "idx_pages_source_type": "CREATE INDEX idx_pages_source_type ON public.pages USING btree (source_id, type) WHERE (deleted_at IS NULL)",
"idx_pages_title_search": "CREATE INDEX idx_pages_title_search ON public.pages USING gin (ts_filter(search_vector, '{a}'::\"char\"[]))",
"idx_pages_trgm": "CREATE INDEX idx_pages_trgm ON public.pages USING gin (title gin_trgm_ops)",
"idx_pages_type": "CREATE INDEX idx_pages_type ON public.pages USING btree (type)",
diff --git a/test/graduation-older-release-fetch.test.ts b/test/graduation-older-release-fetch.test.ts
new file mode 100644
index 0000000000..93d10c4aea
--- /dev/null
+++ b/test/graduation-older-release-fetch.test.ts
@@ -0,0 +1,70 @@
+/**
+ * The graduation E2E's beforeAll (test/e2e/graduation-clients.test.ts) lists and fetches older
+ * release tags from origin before it builds their binaries. A git call over a connection that
+ * opens and then never answers used to block it until the 900 s hook limit. This probe points
+ * origin at a local TCP listener that accepts and never replies, then requires each network git
+ * call in test/helpers/graduation-e2e.ts to give up on its own bound, retry, and fail with an
+ * error that names the timeout. The helper runs in a child process: Bun.spawnSync blocks the
+ * event loop, so a hang in-process would also stop this test's own bound.
+ */
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import net from 'node:net';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const REPO = resolve(import.meta.dir, '..');
+const OUTER_BOUND_MS = 25_000;
+let server: net.Server;
+const sockets: net.Socket[] = [];
+let hungUrl = '';
+const cache = mkdtempSync(join(tmpdir(), 'gbrain-older-release-probe-'));
+
+beforeAll(async () => {
+ server = net.createServer(socket => { sockets.push(socket); });
+ await new Promise<void>(done => server.listen(0, '127.0.0.1', done));
+ hungUrl = `http://127.0.0.1:${(server.address() as net.AddressInfo).port}/hung/gbrain.git`;
+});
+
+afterAll(async () => {
+ for (const socket of sockets) socket.destroy();
+ await new Promise<void>(done => server.close(() => done()));
+ rmSync(cache, { recursive: true, force: true });
+});
+
+function hungOriginEnv(): Record<string, string> {
+ const origin = Bun.spawnSync(['git', '-C', REPO, 'config', '--get', 'remote.origin.url'], { stdout: 'pipe', stderr: 'pipe' });
+ const rewrite = origin.exitCode === 0
+ ? { GIT_CONFIG_KEY_0: `url.${hungUrl}.insteadOf`, GIT_CONFIG_VALUE_0: origin.stdout.toString().trim() }
+ : { GIT_CONFIG_KEY_0: 'remote.origin.url', GIT_CONFIG_VALUE_0: hungUrl };
+ return { PATH: process.env.PATH ?? '', HOME: process.env.HOME ?? cache, GIT_TERMINAL_PROMPT: '0', GIT_CONFIG_COUNT: '1', ...rewrite, GBRAIN_OLDER_RELEASE_DIR: cache };
+}
+
+async function probe(call: string): Promise<{ settled: boolean; code: number | null; stderr: string; ms: number }> {
+ const script = `import { olderReleaseBinary, previousReleaseTags } from './test/helpers/graduation-e2e.ts';\n${call};`;
+ const started = Date.now();
+ const child = Bun.spawn([process.execPath, '-e', script], { cwd: REPO, env: hungOriginEnv(), stdout: 'pipe', stderr: 'pipe' });
+ const killer = setTimeout(() => child.kill('SIGKILL'), OUTER_BOUND_MS);
+ const code = await child.exited;
+ clearTimeout(killer);
+ const ms = Date.now() - started;
+ return { settled: child.signalCode !== 'SIGKILL', code, stderr: await new Response(child.stderr).text(), ms };
+}
+
+describe('graduation older-release helper against an origin that accepts and never answers', () => {
+ test('listing release tags gives up on its bound, retries, and names the timeout', async () => {
+ const r = await probe('previousReleaseTags(2, { timeoutMs: 1_500, attempts: 2 })');
+ expect(r.settled).toBe(true);
+ expect(r.code).not.toBe(0);
+ expect(r.stderr).toMatch(/git ls-remote .*failed 2 time\(s\).*timed out after 1\.5s/);
+ expect(r.ms).toBeLessThan(OUTER_BOUND_MS);
+ }, OUTER_BOUND_MS + 10_000);
+
+ test('fetching an uncached release tag gives up on its bound, retries, and names the timeout', async () => {
+ const r = await probe("olderReleaseBinary('v0.0.0.1', { timeoutMs: 1_500, attempts: 2 })");
+ expect(r.settled).toBe(true);
+ expect(r.code).not.toBe(0);
+ expect(r.stderr).toMatch(/git fetch .*v0\.0\.0\.1.*failed 2 time\(s\).*timed out after 1\.5s/);
+ expect(r.ms).toBeLessThan(OUTER_BOUND_MS);
+ }, OUTER_BOUND_MS + 10_000);
+});
diff --git a/test/helpers/graduation-e2e.ts b/test/helpers/graduation-e2e.ts
index e267b3837d..5620ee3635 100644
--- a/test/helpers/graduation-e2e.ts
+++ b/test/helpers/graduation-e2e.ts
@@ -278,18 +278,32 @@ export const FIRST_GRADUATION_RELEASE = '0.60.52.0';
* marker, the source row or the tombstone. A graduation-aware release refuses where these tests
* need an unaware writer, so the newest tags at or after FIRST_GRADUATION_RELEASE never qualify.
*/
-export function previousReleaseTags(count = 2): string[] {
+export function previousReleaseTags(count = 2, bound: NetworkBound = {}): string[] {
const version = [readFileSync(join(REPO, 'VERSION'), 'utf8').trim(), FIRST_GRADUATION_RELEASE]
.sort((a, b) => cmpVersion(a.split('.').map(Number), b.split('.').map(Number)))[0]!;
- const out = Bun.spawnSync(['git', '-C', REPO, 'ls-remote', '--tags', '--refs', 'origin', 'v*'], { stdout: 'pipe', stderr: 'pipe' });
- if (out.exitCode !== 0) throw new Error(`git ls-remote failed: ${out.stderr.toString()}`);
+ const out = networkGit(['ls-remote', '--tags', '--refs', 'origin', 'v*'], bound);
const parse = (tag: string) => tag.slice(1).split('.').map(Number);
const cmp = (a: number[], b: number[]) => { for (let i = 0; i < Math.max(a.length, b.length); i++) { const d = (a[i] ?? 0) - (b[i] ?? 0); if (d) return d; } return 0; };
const current = version.split('.').map(Number);
- return out.stdout.toString().split('\n').map(line => line.split('refs/tags/')[1]).filter((t): t is string => !!t && /^v\d+(\.\d+){3}$/.test(t))
+ return out.split('\n').map(line => line.split('refs/tags/')[1]).filter((t): t is string => !!t && /^v\d+(\.\d+){3}$/.test(t))
.filter(t => cmp(parse(t), current) < 0).sort((a, b) => cmp(parse(b), parse(a))).slice(0, count);
}
+/** Each network git call's own bound: a connection that opens and never answers must not hold the suite's beforeAll to its 900 s limit. */
+export interface NetworkBound { timeoutMs?: number; attempts?: number }
+
+/** `git -C REPO <args>` against origin, killed after `timeoutMs` and retried up to `attempts` times; throws naming the last failure. */
+function networkGit(args: string[], { timeoutMs = 60_000, attempts = 3 }: NetworkBound = {}): string {
+ let last = '';
+ for (let attempt = 1; attempt <= attempts; attempt++) {
+ const r = Bun.spawnSync(['git', '-C', REPO, ...args], { stdout: 'pipe', stderr: 'pipe', timeout: timeoutMs, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+ if (r.exitCode === 0) return r.stdout.toString();
+ last = r.exitedDueToTimeout ? `timed out after ${timeoutMs / 1000}s` : `exit ${r.exitCode}: ${r.stderr.toString().trim().slice(-500)}`;
+ }
+ throw new Error(`git ${args.join(' ')} failed ${attempts} time(s); last: ${last}. The older-release binaries need origin reachable; `
+ + 'prebuild them under GBRAIN_OLDER_RELEASE_DIR or point GBRAIN_OLDER_RELEASE_BIN_<tag> at one.');
+}
+
function cmpVersion(a: number[], b: number[]): number {
for (let i = 0; i < Math.max(a.length, b.length); i++) { const d = (a[i] ?? 0) - (b[i] ?? 0); if (d) return d; }
return 0;
@@ -300,7 +314,7 @@ function cmpVersion(a: number[], b: number[]): number {
* (`GBRAIN_OLDER_RELEASE_DIR`, default ~/.cache/gbrain-older-releases).
* `GBRAIN_OLDER_RELEASE_BIN_<tag with dots as underscores>` points at a prebuilt one.
*/
-export function olderReleaseBinary(tag: string): string {
+export function olderReleaseBinary(tag: string, bound: NetworkBound = {}): string {
const preset = process.env[`GBRAIN_OLDER_RELEASE_BIN_${tag.replace(/\./g, '_')}`];
if (preset) return preset;
const cache = process.env.GBRAIN_OLDER_RELEASE_DIR || join(process.env.HOME ?? '/tmp', '.cache', 'gbrain-older-releases');
@@ -308,10 +322,11 @@ export function olderReleaseBinary(tag: string): string {
const binary = join(tree, 'bin', 'gbrain');
if (existsSync(binary)) return binary;
const run = (argv: string[], cwd = REPO) => {
- const r = Bun.spawnSync(argv, { cwd, stdout: 'pipe', stderr: 'pipe' });
- if (r.exitCode !== 0) throw new Error(`${argv.join(' ')}: ${r.stderr.toString().slice(-2000)}`);
+ const r = Bun.spawnSync(argv, { cwd, stdout: 'pipe', stderr: 'pipe', timeout: 300_000 });
+ if (r.exitCode !== 0) throw new Error(`${argv.join(' ')}: ${r.exitedDueToTimeout ? 'timed out after 300s' : r.stderr.toString().slice(-2000)}`);
};
- run(['git', 'fetch', '-q', 'origin', 'tag', tag, '--no-tags']);
+ const local = Bun.spawnSync(['git', '-C', REPO, 'rev-parse', '-q', '--verify', `refs/tags/${tag}`], { stdout: 'pipe', stderr: 'pipe' });
+ if (local.exitCode !== 0) networkGit(['fetch', '-q', 'origin', 'tag', tag, '--no-tags'], bound);
if (!existsSync(tree)) run(['git', 'worktree', 'add', '-q', '--detach', tree, tag]);
run([process.execPath, 'install', '--frozen-lockfile', '--ignore-scripts'], tree);
run([process.execPath, 'build', '--compile', '--no-compile-autoload-bunfig', '--outfile', 'bin/gbrain', 'src/cli.ts'], tree);
diff --git a/test/import-calls.test.ts b/test/import-calls.test.ts
index 1231325bb2..8133d3fca0 100644
--- a/test/import-calls.test.ts
+++ b/test/import-calls.test.ts
@@ -10,14 +10,17 @@
* a --prefix value read as the import folder, a page written under conversations/.
* 3. A new mode on an existing command; test/setup-brain-layout.test.ts covers it through gbrain setup.
*/
-import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, mock, spyOn, test } from 'bun:test';
import { spawnSync } from 'node:child_process';
import { randomBytes } from 'node:crypto';
-import { mkdirSync, mkdtempSync, rmSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { runCli } from './helpers/cli-spawn.ts';
-import { callPageFor, listCallFiles } from '../src/commands/import-calls.ts';
+import { callPageFor, callRootId, listCallFiles, runCallImport } from '../src/commands/import-calls.ts';
+import { operations } from '../src/core/operations.ts';
+import { OperationError } from '../src/core/ops/contract.ts';
+import { _resetCliExitVerdictForTests, currentExitCode } from '../src/core/cli-force-exit.ts';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { parseMarkdown } from '../src/core/markdown.ts';
import { listBudgetLimitedPages, planPageEmbedding } from '../src/core/page-embedding-budget.ts';
@@ -183,6 +186,56 @@ describe('gbrain import --calls', () => {
expect(JSON.parse((await imp(b)).stdout)).toMatchObject({ imported: 1, kept: 0, errors: 0 });
expect((await runCli(['get', 'calls/2026-04-03-retro'], { env })).stdout).toContain('Bob: retro.');
}, 240_000);
+
+ test('two files a redaction pattern names alike both import, and neither name is stored or printed', async () => {
+ const root = temp('gbrain-calls-alike-');
+ 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' };
+ expect((await runCli(['init', '--pglite', '--no-embedding', '--json'], { env })).exitCode).toBe(0);
+ writeFileSync(join(home, '.gbrain', 'harvest-private-patterns.txt'), 'acme-example-[0-9]+\n');
+ const calls = join(root, 'calls');
+ mkdirSync(calls);
+ writeFileSync(join(calls, 'acme-example-1.txt'), 'Kickoff 2026-04-01\nAlice: one.\n');
+ const run = async () => {
+ const r = await runCli(['import', calls, '--calls', '--no-embed', '--json'], { env });
+ expect(r.stdout).not.toMatch(/acme-example-\d/);
+ return JSON.parse(r.stdout);
+ };
+ expect(await run()).toMatchObject({ imported: 1, errors: 0 });
+ writeFileSync(join(calls, 'acme-example-2.txt'), 'Review 2026-04-02\nAlice: two.\n');
+ const second = await run();
+ expect(second).toMatchObject({ imported: 1, unchanged: 1, kept: 0, errors: 0 });
+ expect(second.pages.map((p: any) => p.slug).sort()).toEqual(['calls/2026-04-01-kickoff', 'calls/2026-04-02-review']);
+ expect(await run()).toMatchObject({ imported: 0, unchanged: 2, kept: 0, errors: 0 });
+ const stored = await runCli(['get', 'calls/2026-04-02-review'], { env });
+ expect(stored.stdout).toContain('Alice: two.');
+ expect(stored.stdout).not.toMatch(/acme-example-\d/);
+ }, 240_000);
+
+ test('a single call file imports, a later folder import finds it, and a file of another kind is an error', async () => {
+ const root = temp('gbrain-calls-single-');
+ 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' };
+ expect((await runCli(['init', '--pglite', '--no-embedding', '--json'], { env })).exitCode).toBe(0);
+ const calls = join(root, 'calls');
+ mkdirSync(calls);
+ writeFileSync(join(calls, '2026-04-05 planning.txt'), 'Alice: plan.\n');
+ writeFileSync(join(calls, 'agenda.pdf'), 'x\n');
+ const imp = async (target: string) => {
+ const r = await runCli(['import', target, '--calls', '--no-embed', '--json'], { env });
+ return { code: r.exitCode, doc: JSON.parse(r.stdout) };
+ };
+ const single = await imp(join(calls, '2026-04-05 planning.txt'));
+ expect(single.doc).toMatchObject({ total_files: 1, imported: 1, errors: 0 });
+ expect(single.doc.pages[0]).toMatchObject({ file: '2026-04-05 planning.txt', slug: 'calls/2026-04-05-planning' });
+ expect((await runCli(['get', 'calls/2026-04-05-planning'], { env })).stdout).toContain('Alice: plan.');
+ expect((await imp(calls)).doc).toMatchObject({ total_files: 1, imported: 0, unchanged: 1, errors: 0 });
+ const other = await imp(join(calls, 'agenda.pdf'));
+ expect(other.code).toBe(1);
+ expect(other.doc).toMatchObject({ imported: 0, errors: 1 });
+ }, 240_000);
});
describe('call page embedding', () => {
@@ -201,3 +254,40 @@ describe('call page embedding', () => {
expect(held.map(h => [h.slug, h.reason])).toContainEqual([page.slug, 'call_import']);
});
});
+
+describe('call import, in process', () => {
+ let engine: PGLiteEngine;
+ beforeAll(async () => { engine = new PGLiteEngine(); await engine.connect({}); await engine.initSchema(); }, 120_000);
+ afterAll(async () => { await engine.disconnect(); });
+ beforeEach(() => _resetCliExitVerdictForTests());
+ afterEach(() => mock.restore());
+
+ test('a page imported before call_import.path was stored is still found by its file after its modified day moved', async () => {
+ const dir = realpathSync(temp('gbrain-calls-legacy-'));
+ writeFileSync(join(dir, 'legacy.txt'), 'Legacy sync\nAlice: legacy.\n');
+ const page = callPageFor('legacy.txt', 'Legacy sync\nAlice: legacy.\n', MTIME, 'legacy', [], callRootId(dir));
+ expect(page.content).not.toContain(' path:');
+ const parsed = parseMarkdown(page.content);
+ await engine.putPage(page.slug, { type: 'meeting', title: page.title, compiled_truth: parsed.compiled_truth, frontmatter: parsed.frontmatter });
+ spyOn(console, 'log').mockImplementation(() => {});
+ expect(await runCallImport(engine, dir, ['--calls', '--prefix', 'legacy'], { json: false })).toMatchObject({ imported: 0, errors: 0 });
+ });
+
+ test('a write still pending is reported pending, not as an error, and exits 10', async () => {
+ const dir = realpathSync(temp('gbrain-calls-pending-'));
+ writeFileSync(join(dir, '2026-05-02 pending.txt'), 'Alice: pending.\n');
+ const requestId = '7a1c0d2e-0000-4000-8000-00000000ca11';
+ spyOn(operations.find(op => op.name === 'put_page')!, 'handler').mockImplementation((async () => {
+ const error = new OperationError('write_pending', 'The page write was accepted and is still running.', 'Poll the receipt.');
+ error.writeRequest = { request_id: requestId, state: 'queued', retry_after_ms: 500 } as never;
+ throw error;
+ }) as never);
+ const lines: string[] = [];
+ spyOn(console, 'log').mockImplementation((line: string) => { lines.push(line); });
+ const result = await runCallImport(engine, dir, ['--calls', '--prefix', 'pending'], { json: false });
+ expect(result).toMatchObject({ imported: 0, errors: 0, failures: [] });
+ expect(currentExitCode()).toBe(10);
+ expect(lines.join('\n')).toContain('1 pending');
+ expect(lines.join('\n')).toContain(`gbrain write-request -- ${requestId}`);
+ });
+});
diff --git a/test/repair-agent-session-facts.test.ts b/test/repair-agent-session-facts.test.ts
index ecb0cca9be..36e34a6ef7 100644
--- a/test/repair-agent-session-facts.test.ts
+++ b/test/repair-agent-session-facts.test.ts
@@ -162,6 +162,27 @@ describe('gbrain repair agent-session-facts, unmanaged repo-less brain', () => {
expect(wave.spec.count(wave.check.details!)).toBe(3);
}, 120_000);
+ test('#9390: Claude Code slash-command and caveat text is not an opening; owner sessions that start with /clear are not repeated_opening', async () => {
+ const CAVEAT = '<local-command-caveat>Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to.</local-command-caveat>';
+ const CLEAR = '<command-name>/clear</command-name>\n<command-message>clear</command-message>\n<command-args></command-args>';
+ const STDOUT = '<local-command-stdout></local-command-stdout>';
+ const write = (id: string, body: string) => writeFileSync(join(corpus, `${id}.txt`), body);
+ const owner = ['Draft the agenda for the planning sync with the platform group.', 'Walk me through why the nightly export got slower this week.',
+ 'Help me rewrite the onboarding note so new teammates find the setup steps.', 'Compare the two caching options we discussed and pick one for me.'];
+ owner.forEach((text, i) => write(`sess-cc${i}`, `[user]\n${CAVEAT}\n\n[user]\n${CLEAR}\n${STDOUT}\n\n[user]\n${text}\n\n[assistant]\nSure.`));
+ for (const n of [0, 1, 2, 3]) write(`sess-only${n}`, `[user]\n${CAVEAT}\n${CLEAR}\n${STDOUT}\n\n[assistant]\nOk.`);
+ for (const n of [0, 1, 2, 3]) write(`sess-hb${n}`, `[user]\n${CLEAR}\n\n[user]\n${BRIEF}\nTask ${n}: handle ticket ${n}.\n\n[assistant]\nOn it.`);
+ const ownerFact = await insert('Prefers short agendas', 'sess-cc0');
+ const harnessOnly = await insert('Prefers quiet mornings', 'sess-only0');
+ const unattended = await insert('Prefers small commits', 'sess-hb0');
+ const template = await insert('Prefers tidy branches', 'sess-t1');
+ const listed = classes(await repair(engine, []));
+ expect(listed[ownerFact]).toBeUndefined();
+ expect(listed[harnessOnly]).toBeUndefined();
+ expect(listed[unattended]).toBe('ambiguous');
+ expect(listed[template]).toBe('ambiguous');
+ }, 120_000);
+
test('apply re-attributes, adds the note, retires only all-agent takes, deletes nothing; ambiguous needs --include-ambiguous', async () => {
await engine.putPage(ALICE, { type: 'person', title: 'Alice Example', compiled_truth: '# Alice Example' }, { sourceId: 'default' });
const a = await insert('Prefers terse status updates', 'sess-sidecar');
diff --git a/test/retrieval-reflex-row-order.test.ts b/test/retrieval-reflex-row-order.test.ts
new file mode 100644
index 0000000000..b36e951002
--- /dev/null
+++ b/test/retrieval-reflex-row-order.test.ts
@@ -0,0 +1,38 @@
+/**
+ * The retrieval reflex's title and slug arm returns its pages in creation
+ * order, whatever plan reads them.
+ *
+ * Protects: with one pointer to give (Codex gets a single fragment) and two
+ * names in one turn, the page the reflex injects does not change when the
+ * other page is rewritten (its row moves to the end of the table) or when an
+ * index gives the planner another way in.
+ * Fails when: the arm's query has no ORDER BY, so the first row is whatever the
+ * plan happened to read first (heap order for a sequential scan, index order
+ * for an index scan). A new index on pages (source_id, type) moved BrainBench's
+ * codex push recall from 0.55 to 0.42 this way.
+ * Seams: none; in-memory PGLite.
+ */
+import { afterAll, beforeAll, expect, test } from 'bun:test';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { resolveEntitiesToPointers } from '../src/core/context/retrieval-reflex.ts';
+
+let engine: PGLiteEngine;
+
+beforeAll(async () => {
+ engine = new PGLiteEngine();
+ await engine.connect({});
+ await engine.initSchema();
+ await engine.executeRaw(`INSERT INTO pages (source_id, slug, type, title, compiled_truth) VALUES
+ ('default', 'people/alice-example', 'person', 'Alice Example', 'first page'),
+ ('default', 'people/bob-example', 'person', 'Bob Example', 'second page')`);
+}, 120_000);
+afterAll(async () => { await engine.disconnect(); });
+
+const firstPointer = async () => (await resolveEntitiesToPointers(engine, 'default',
+ [{ display: 'Bob Example', query: 'Bob Example' }, { display: 'Alice Example', query: 'Alice Example' }], { maxPointers: 1 }))?.pointers.map(p => p.slug);
+
+test('with two names in a turn and one pointer, the page created first is injected, before and after it is rewritten', async () => {
+ expect(await firstPointer()).toEqual(['people/alice-example']);
+ await engine.executeRaw(`UPDATE pages SET compiled_truth = 'first page, edited' WHERE slug = 'people/alice-example'`);
+ expect(await firstPointer()).toEqual(['people/alice-example']);
+});
diff --git a/test/serve-sync-handoff.serial.test.ts b/test/serve-sync-handoff.serial.test.ts
index 5b031de86e..81a022019b 100644
--- a/test/serve-sync-handoff.serial.test.ts
+++ b/test/serve-sync-handoff.serial.test.ts
@@ -51,6 +51,7 @@ import { implyManagedNoPull } from '../src/commands/sync/managed-no-pull.ts';
import type { ConsumerRow } from '../src/core/persistence/consumer-heartbeat.ts';
import type { SyncOpts } from '../src/commands/sync.ts';
import { withEnv } from './helpers/with-env.ts';
+import { VERSION } from '../src/version.ts';
const home = mkdtempSync(join(tmpdir(), 'gbrain-handoff-'));
const sources: string[] = [];
@@ -289,6 +290,28 @@ describe('maybeDelegateManagedSyncToServe (the Postgres ladder, client half)', (
expect(ownConsumerForcedReason()).toBeNull();
}), 120_000);
+ test('a serve already on this gbrain version is never told to restart on this version; an older one still is', async () => withEnv({ GBRAIN_HOME: home }, async () => {
+ const f = await fixture(1);
+ const dead = join(home, `dead-${randomUUID().slice(0, 8)}.sock`);
+ writeFileSync(dead, '');
+ const current = serveRow({ version: VERSION });
+ resetOwnConsumerForTest();
+ captureStderr();
+ const noSock = await maybeDelegateManagedSyncToServe(engine, [], baseOpts(f.id), deps({ sock: null, row: current }));
+ const silent = await maybeDelegateManagedSyncToServe(engine, [], baseOpts(f.id), deps({ sock: dead, row: current }));
+ const older = await maybeDelegateManagedSyncToServe(engine, [], baseOpts(f.id), deps({ sock: null, row: serveRow({ version: '0.0.1.0' }) }));
+ releaseStderr();
+ resetOwnConsumerForTest();
+ for (const outcome of [noSock, silent]) {
+ const line = outcome.kind === 'own_consumer' ? outcome.line ?? '' : '';
+ expect(line).not.toMatch(/[Rr]estart that serve on this gbrain version/);
+ expect(line).toContain(`already runs this gbrain version (v${VERSION})`);
+ }
+ expect(noSock.kind === 'own_consumer' && noSock.line).toMatch(/GBRAIN_SERVE_SYNC_IPC=0/);
+ expect(silent.kind === 'own_consumer' && silent.line).toMatch(/not answering its IPC socket.*may be wedged/);
+ expect(older.kind === 'own_consumer' && older.line).toMatch(/Restart that serve on this gbrain version/);
+ }), 120_000);
+
test('#7167: a dry run that is not delegated says it previews in this process and writes nothing, and never forces a consumer of its own', async () => withEnv({ GBRAIN_HOME: home }, async () => {
const f = await fixture(1);
const dead = join(home, `dead-${randomUUID().slice(0, 8)}.sock`);
diff --git a/test/storage-manifest-adopt-hosted.test.ts b/test/storage-manifest-adopt-hosted.test.ts
index d5ebf0df82..d4133541d0 100644
--- a/test/storage-manifest-adopt-hosted.test.ts
+++ b/test/storage-manifest-adopt-hosted.test.ts
@@ -56,4 +56,18 @@ describe('storage adopt on a brain with a Git checkout', () => {
expect(await applyFinalize(ctx, { ...opts, expect: finalize.plan_hash })).toMatchObject({ side_effects: 'complete', deleted: ['storage-manifest/runs-2026'] });
expect((await call(ctx, 'storage_get', { id: 'runs-2026' })).origin).toBe('adopt');
}), 90_000);
+
+ test('the adopt apply leaves its own commits indexed: the shelf checkpoint reaches HEAD with no hand-run sync', () => managedBrain(async ({ engine, ctx, root }) => {
+ await call(ctx, 'put_page', { slug: 'storage-manifest/runs-2027', request_id: randomUUID(),
+ content: `---\ntype: stored-object\ntitle: Interim runs\n---\n## Record\n\n${FENCE}json\n${JSON.stringify(record('runs-2027'))}\n${FENCE}\n` });
+ const dir = join(dirname(root), 'shelf');
+ const preview = await initStorageSource(engine, { dir, dryRun: true });
+ await initStorageSource(engine, { dir, dryRun: false, expect: preview.plan!.plan_hash });
+ const plan = await previewAdopt(ctx, opts);
+ const applied = await applyAdopt(ctx, { ...opts, expect: plan.plan_hash, dropFields: ['restore.command'] });
+ const head = git(join(dir, 'worktree'), 'rev-parse', 'HEAD').trim();
+ expect(await engine.executeRaw("SELECT last_commit FROM sources WHERE id='storage'")).toEqual([{ last_commit: head }]);
+ expect(applied).toMatchObject({ side_effects: 'complete', index: { source_id: 'storage', status: 'indexed' } });
+ expect(applied.index!.last_commit).toBe(head);
+ }), 90_000);
});
diff --git a/test/storage-manifest-adopt.test.ts b/test/storage-manifest-adopt.test.ts
index b7835470f5..3bc781495e 100644
--- a/test/storage-manifest-adopt.test.ts
+++ b/test/storage-manifest-adopt.test.ts
@@ -173,6 +173,32 @@ describe('storage adopt on a repo-less brain', () => {
expect((await refusal(applyAdopt(ctx(), { ...opts, expect: plan.plan_hash, dropFields: [] })))).toMatchObject({ code: 'storage_record_invalid' });
}, 60_000);
+ test('a record cut off by the 64 KiB read is reported as truncated, not as a page with no record', async () => {
+ const notes = `## Notes\n\n${'archive notes line\n'.repeat(4000)}\n`;
+ const content = `---\ntype: stored-object\ntitle: Long record\n---\n# Long record\n\n${notes}## Record\n\n${FENCE}json\n${JSON.stringify(record('dataset-long'), null, 2)}\n${FENCE}\n`;
+ await call('put_page', { slug: 'storage-manifest/dataset-long', content, request_id: randomUUID() });
+ const plan = await previewAdopt(ctx(), opts);
+ expect(plan.entries.map((e) => [e.slug, e.state, e.problem?.code ?? null, e.problem?.reason ?? null])).toEqual([['storage-manifest/dataset-long', 'blocked', 'storage_record_invalid', 'truncated']]);
+ expect(plan.entries[0]!.problem!.message).toContain('64 KiB');
+ expect((await refusal(applyAdopt(ctx(), { ...opts, expect: plan.plan_hash, dropFields: [] })))).toMatchObject({ code: 'storage_record_invalid', reason: 'truncated' });
+ }, 60_000);
+
+ test('apply --json counts what it adopted, skipped and refused, with the write receipt of each record it wrote', async () => {
+ await interim('storage-manifest/dataset-a', record('dataset-a'));
+ await interim('storage-manifest/dataset-b', record('dataset-b'));
+ await interim('storage-manifest/dataset-c', record('dataset-c'));
+ await call('storage_register', { card: { ...record('dataset-c'), reason: 'something else' } });
+ const plan = await previewAdopt(ctx(), opts);
+ const applied = await applyAdopt(ctx(), { ...opts, expect: plan.plan_hash, dropFields: [] });
+ expect(applied.counts).toEqual({ adopted: 2, skipped: 0, refused: 1, pending: 0 });
+ const written = applied.results.filter((r) => r.outcome === 'registered' || r.outcome === 'retagged');
+ expect(written).toHaveLength(4);
+ for (const row of written) expect(await call('get_write_request', { request_id: row.request_id })).toMatchObject({ request_id: row.request_id, state: 'committed' });
+ expect(applied.results.find((r) => r.outcome === 'conflict')).toMatchObject({ slug: 'storage-manifest/dataset-c', card_id: 'dataset-c' });
+ const again = await previewAdopt(ctx(), opts);
+ expect((await applyAdopt(ctx(), { ...opts, expect: again.plan_hash, dropFields: [] })).counts).toEqual({ adopted: 0, skipped: 2, refused: 1, pending: 0 });
+ }, 60_000);
+
test('a matching card is only tagged, a differing one is a conflict, and a half-finished run applies with the hash it printed', async () => {
await interim('storage-manifest/dataset-a', record('dataset-a'));
await interim('storage-manifest/dataset-b', record('dataset-b'));
diff --git a/test/storage-manifest.test.ts b/test/storage-manifest.test.ts
index dd694e928e..9bc4332c1d 100644
--- a/test/storage-manifest.test.ts
+++ b/test/storage-manifest.test.ts
@@ -121,6 +121,23 @@ describe('storage shelf on a repo-less brain', () => {
expect((await call('storage_find', { query: 'export', store: 'supabase' })).hits).toEqual([]);
}, 30_000);
+ test('a card asked for by its exact title is an exact hit, even when the title tokenizes as one word (a file name, an email)', async () => {
+ await call('storage_register', { card: card('arc-one', { title: 'mail-archive.tar.gz', description: null }) });
+ await call('storage_register', { card: card('arc-two', { title: '[email protected] mailbox', description: null }) });
+ for (const [title, id] of [['mail-archive.tar.gz', 'arc-one'], ['[email protected] Mailbox', 'arc-two']]) {
+ const found = await call('storage_find', { query: title });
+ expect(found).toMatchObject({ not_found: false, closest: [] });
+ expect(found.hits[0]).toMatchObject({ id, match: 'title' });
+ }
+ }, 30_000);
+
+ test('an empty location path refuses with what to write for an item at the root of its bucket or repository', async () => {
+ const r = await refusal(call('storage_register', { card: card('root-item', { locations: [{ store: 'b2', bucket: 'bucket-a', path: '', tool: 'restic', size_bytes: 1 }] }) }));
+ expect(r).toMatchObject({ code: 'storage_record_invalid', reason: 'schema' });
+ expect(r!.message).toContain('locations.0.path');
+ expect(r!.message).toContain('write "/"');
+ }, 30_000);
+
test('validation refuses incomplete cards, command fields, stamped fields, secrets and credential shapes', async () => {
const fake = (...parts: string[]) => parts.join('');
const cases: Array<[Record<string, unknown>, string, string]> = [
diff --git a/test/sync-delegate-ladder.test.ts b/test/sync-delegate-ladder.test.ts
index 15ae60ec18..66ae72540e 100644
--- a/test/sync-delegate-ladder.test.ts
+++ b/test/sync-delegate-ladder.test.ts
@@ -224,6 +224,23 @@ describe('maybeDelegateSyncToServe brain + source gates (F3)', () => {
expect(await withBrainOption('Not-A-Valid-Id!', () => maybeDelegateSyncToServe(dir, []))).toBe(false);
});
+ test('a live serve with no sync IPC is not told to restart on this version: the PGLite lock records no build to compare', async () => {
+ const savedExitCode = process.exitCode;
+ _resetCliExitVerdictForTests();
+ const cap = captureConsoleError();
+ try {
+ expect(await maybeDelegateSyncToServe(dirWithLiveServeLock(), [])).toBe(true);
+ const text = cap.lines.join('\n');
+ expect(text).toContain('exposes no sync IPC');
+ expect(text).not.toContain('Restart that serve on this gbrain version.');
+ expect(text).toContain('If that serve runs an older gbrain, restart it on this version.');
+ } finally {
+ cap.restore();
+ _resetCliExitVerdictForTests();
+ process.exitCode = savedExitCode ?? 0;
+ }
+ });
+
test('brain resolver throw + live serve → the ladder CONTINUES as if host (fail open to old behavior)', async () => {
// REALITY pin: the catch does NOT return false — it falls through to the
// holder probe, so under a live serve the resolver throw still yields the